pi-runner

Pi Runner

まず shared/references/model-preview.md を使用してブランチを選択してください。決定的なチェックではモデルを選択する必要はありません。実際のディスパッチでは、承認済みの具体的なスナップショットを1つ使用します。ネストされた呼び出しは、再解決や追加のワーカーを使わずにそのスナップショットを引き継ぎます。

非対話モードで Pi（pi）を通じてプロンプトを実行します。厳密なリクエスト制御には起動時ハンドシェイクを伴う RPC を使用し、従来の呼び出しでは print モードを維持します。呼び出しごとに --provider と --model でゲートウェイとモデルを固定するか、--seat で中央の名前付きシートを選択してください。認証情報はゲートウェイ環境または Pi の認証ストアから取得します。モデルを厳密に選択しても、推論プロバイダーのフォールバックは制限されません。この別個のポリシーは --provider-routing で引き継いでください。

ネイティブルーティング

外部ルートを選択する前に、shared/references/host-model-execution.md を読んでください。現在のホストが、必要な推論レベル、分離、レシートポリシーを満たして、選択されたプロバイダーモデルをネイティブのサブエージェントまたはタスクスレッドでディスパッチできる場合は、そのルートを使用してください。ホストのスキル記述子では、ネイティブモデルはディスパッチされません。

名前付きシート

名前付きシートとその正確なモデル ID は shared/model-routing.json にあります。 --seat は直接選択する際にこれらの固定値を読み込み、エンベロープにラベルを付けます。ワークフローの ディスパッチでは、承認済みスナップショットに含まれる明示的な --provider、--model、推論レベル、 ポリシーを使用します。シートの固定値を再解決することはありません。明示的な --model は、 承認済みプランがある場合、そのプランと一致している必要があります。管理対象の固定値は中央ファイルでのみ変更してください。CLI またはキーがない場合は status: seat_unavailable が報告され、別のシートへのフォールバックはありません。

ゲートウェイと機能

中央のランナー設定でデフォルトのゲートウェイを選択します。OpenRouter は OPENROUTER_API_KEY または Pi の認証ストアを使用します。明示的に選択した ゲートウェイには --provider を使用してください。バンドルされたカタログにないモデル ID には、検証済みの 機能メタデータが必要です。文字列を渡すだけでは、モデルへのアクセス、画像 サポート、ツール、推論レベル制御の証明にはなりません。

中央のモデルエントリーから、サポートされる推論レベルと実行時の推論レベルを読み取ってください。選択した制御可能な推論レベルを明示的に渡します。GLM は low、high、max を受け付けます。省略した場合や、ネイティブ値として認識されない値を指定した場合は、max が選択されることがあります。汎用の medium または xhigh を 変換するのではなく、サポートされていない値は拒否してください。選択可能な推論レベルがないモデルでは、実行時に制御される推論レベルを維持し、存在しない レベルを作らないでください。新しいルートを使用する前に、シリアル化された設定を取得してください。

プロバイダーのリクエストポリシー

承認済みの provider_routing オブジェクトは、コンパクトな JSON として --provider-routing を通じて渡されます。OpenRouter の厳格なルートでは、 gateway: openrouter、zdr: true、data_collection: deny、 require_parameters: true が含まれます。選択した推論プロバイダーの 許可リストを指定する場合は only を、プランで指定されている場合は allow_fallbacks を含めます。承認済みセット内でのプロバイダーの フォールバックと、別のモデルへのフォールバックは別のものです。 可用性を回復するためにプライバシー制御を削除してはいけません。厳格な 呼び出しでは、モデルレジストリとは独立してゲートウェイ URL を固定します。 別の URL を指すプロバイダーラベルは、タスク内容が送信される前に拒否されます。

モデルエントリーに検証済みのプライバシーブロック（shared/model-routing.json の 選択したゲートウェイに対する zdr_available: true）があるシートでは、 --provider-routing が省略された場合、中央の profile_policy.provider_routing がデフォルトになります。明示的なポリシーが 指定された場合は、リクエストごとにそちらが優先されます。中央のポリシーで 固定するのはプライバシー制御のみです。ゲートウェイがゼロ保持のエンドポイントから 選択するため、推論プロバイダーは固定されません。

実行ごとに設定をスコープする、パッケージ化されたリクエスト強制経路を使用します。 初回、ツール、修復、再開時のすべてのリクエストで、選択したポリシーが 正確に維持される必要があります。無関係な拡張機能の検出は無効のままにし、 変更可能なグローバルモデルレジストリに依存しないでください。強制機能がない場合や ゲートウェイが誤っている場合、リポジトリの内容が送信される前に厳格なルートが ブロックされます。ソース共有のメタデータだけでは、リクエストポリシーは強制されません。

厳格な実行には、ランタイムアダプターで指定された最小の安定版 Pi、またはそれ以降の 安定版リリースが必要です。リクエストフックは、タスク内容が送信される前に準備完了を 確認する必要があります。インストール済みのランタイムはリクエストフックの外部で セッションを圧縮するため、厳格な実行では圧縮前に停止し、完了を受け付ける前に 処理済みイベントを待ちます。コンテキストがいっぱいになった場合は、承認済みの 新しいコンテキストパケットが必要です。保護されていないリクエストを通じて暗黙的に 要約することはできません。

リクエストの強制を確認した後に限り、status: enforced、gateway、 policy_sha256、および正の request_count を含む provider_policy_receipt を保持します。ソースやシークレットをログに記録せず、 合成ローカルリクエストを取得して、正確なモデル、推論、プロバイダー制御、 ツール、画像ペイロードを検証します。レシートがない場合、厳格なルートが 受け入れられたとは確認できません。ポリシーを省略した場合、検証済みの プライバシーブロックがないモデルに限りレガシー動作が維持されますが、厳格な プライバシーとして報告することはできません。

前提条件

• pi CLI がすでにインストールされ、PATH に含まれていること。未インストールの場合は準備不足であり、グローバルインストールが許可されるわけではありません
• サービングプロバイダーの API キーが環境に設定されていること（デフォルトのプロバイダーでは OPENROUTER_API_KEY）

隔離された実行

実行ごとに、無関係な拡張機能、スキル、プロンプトテンプレート、テーマ、プロジェクト指示の検出を無効にします。選択したポリシー向けに明示的にパッケージ化されたリクエストフックは、制御された例外です。ロールの概要、許可されたファイル、ドライバーの指示、画像アーティファクトを明示的に渡します。ツールでの読み取りや許可された添付ファイルによって入力が拡張される場合があります。ツールが有効なときに、プロンプトが入力全体であると説明しないでください。

ツールモード

• act（書き込みロール、--allow-write、またはロール指定なし）：Pi の組み込みツール一式（読み取り、bash、編集、書き込み）を使用できます。
• restricted（--restrict-tools、分析ロールのデフォルト）：ファイル読み取りツールのみが有効です。このモードには検索ツールも読み取り専用のシェルもありません。
• no_tools（--no-tools）：ネイティブのツール無効化です。担当は提供された入力に基づいて回答します。ポーリングモードの評議会担当が使用します。
• browser（--tool-policy browser）：選択したドライバーのファイル／画像読み取りとシェルアクセスが可能です。取得した準備状況の証拠を添えて、--browser-mechanism playwright-cli または agent-browser と --browser-preflight <file> を渡します。シェルアクセスによってブラウザー専用のサンドボックスが適用されることはなく、製品の修復が許可されるわけでもありません。

外部の Pi ワーカーはホストのブラウザーツールを継承しません。視覚的な作業では、合成画像を使ってアダプター経由でモデルの画像サポート、ドライバーのアーティファクトパス、型付き画像コンテンツを事前確認してください。明示的に添付するには --image-file <path> を使い、許可されている画像を複数添付する場合は繰り返し指定します。テキストにスクリーンショットのパスを書くだけでは不十分です。 1 つの作業経路につきドライバーを 1 つ、ロールごとに分離したセッションを 1 つ使用してください。ドライバー、ツール、画像、プライバシー機能のいずれかが不足している場合、その経路は利用できません。

共有ラッパーのリファレンス

サポートされるオプション、ロール、--json エンベロープ、戻りコードについては、shared/references/runner-common.md に記載されています。エンベロープには runner=pi または担当名と effective_runner=pi が報告されます。model_author はベンダーを示し、gateway は API の経路を示します。inference_provider には実際の上流の証拠が必要であり、証拠がない場合は不明のままです。従来の effective_provider ベンダーフィールドは、推論ホストを示すものではありません。ターミナルの native_model_id によってクライアントからモデルのレシートが報告されることがありますが、推論プロバイダーを独立して証明するものではありません。リクエストポリシーのレシートとモデルのレシートは分けてください。

使用方法

読み込まれたスキルから SKILL_DIR を解決し、実行スナップショットから選択内容を正確にコピーします。エフォートを選択できるモデルの場合：

SKILL_DIR="<absolute path of this skill directory>";
python3 "$SKILL_DIR/scripts/run_pi.py" --prompt-file <role-brief.md> \
  --provider <approved-gateway> \
  --model <approved-model-id> --thinking <selected-effort> \
  --session <unique-role-session-file> \
  --provider-routing '<approved-provider-routing-json>' --disable-fallback --json

実行時に制御するエフォートの場合は、選択したモデルでサポートされている実行時の方法を使用してください。high の値を独自に作らないでください。選択した経路にプロバイダーポリシーがない場合に限り、--provider-routing を省略します。プライバシー制限が確認された担当には、デフォルトで中央の厳格なポリシーが適用されます。概要のみのロールには --no-tools を、ファイルやブラウザーを使う作業には明示的に選択したツールポリシーを使用してください。

注意点

• 認証情報がなくても終了コードは 0 です。 選択したプロバイダーのキーがない場合、pi は「Use /login ...」というヒントを表示して、エージェントイベントを生成せずに正常終了します。ラッパーはこれを検出して success: false、status: auth_missing、auth_ok: false を報告します。Pi の終了コードだけを信用しないでください。
• ネイティブのスキーマ切り替えはありません。 --output-schema は契約をプロンプトに追加し、ローカルで適用します。最終回答がスキーマに準拠する JSON 値 1 つだけでない場合、実行は status: malformed_output で失敗します。
• 差分ストリームは圧縮されます。 Pi の --mode json はトークンごとに message_update 行を出力します。ラッパーはこれらを保存される stdout から除き、完全なメッセージとサービス提供レシート（プロバイダー、モデル、使用量、stopReason）を含む最終イベントを保持します。stdout ではなく agent_message を確認してください。
• ネイティブのタイムアウトフラグはありません。 ラッパーの --timeout はサブプロセスレベルで適用され、タイムアウト時には return_code -1 を報告します。
• セッションの再開にはネイティブの --session <id|path> を使用します。--no-session-persistence／--ephemeral はネイティブの --no-session に対応します。Pi の --mode json ストリームはセッション ID を通知しないため、エンベロープの session_id には呼び出し元が渡した値のみが反映されます。

必要に応じて読み込む

• references/continuation.md：ロールで Pi のターンを追加する必要がある場合、またはワークフローでテキストの引き継ぎが必要な場合。