yoi/tickets/spawn-pod-tool.md

SpawnPod ツール: LLM から Pod を生成する

背景

オーケストレーションの起点。LLM が「このタスクを別 Pod に任せたい」と判断したとき、SpawnPod ツールを呼び出して新しい Pod プロセスを起動する。

依存

• tickets/scope-lock.md: scope 分譲の記録基盤

仕様

ツール定義

SpawnPod は通常の Tool trait 実装として Worker に登録される。

入力:

• name: spawned Pod の識別名
• instruction: instruction ファイル参照（省略時は $insomnia/default）
• task: 最初のメッセージ（spawn 後に即座に run される）
• scope: 譲渡する scope 定義（allow ルール）。spawner の effective scope のサブセットでなければならない

出力:

• spawned Pod の name と接続先 address（socket path）

内部動作

1. scope lock file を flock → spawner の effective scope を確認 → 要求された scope がサブセットか検証
2. spawner の allocation に deny を追記 + 新 Pod の allocation を登録（delegated_from = spawner）→ unlock
3. PodFactory のカスケード（user / project manifest）に spawner からの overlay（name, pwd, scope, instruction）を重ねて PodManifest を構築
4. pod バイナリを独立プロセスとして起動（Command::new(pod_command)）
5. spawned Pod の socket が利用可能になるまで待機
6. spawner の callback address を spawned Pod に渡す（Method::Notify 経由の受け口として）
7. task を Method::Run で送信
8. spawn 記録を Pod のランタイム状態に保存

Pod 起動コマンド

• デフォルト: pod（PATH 上のバイナリ）
• 環境変数 INSOMNIA_POD_COMMAND またはユーザー manifest で上書き可能
• 引数: --overlay <toml> で scope / instruction / name / pwd を渡す

spawn 記録

Pod が保持する既知の Pod リスト。各エントリ:

• name, name, socket_path, scope_delegated, callback_address
• spawner 復帰時にこの記録を読んで再接続する

設計で決めること

• spawn 記録の永続化: session-store に載せるか、runtime_dir にファイルとして書くか
• socket 待機のタイムアウト: spawned Pod が socket を開くまでの待機時間
• callback address の形式: ローカルでは spawner の socket path、リモートでは insomnia@host:pod-name

完了条件

• LLM が SpawnPod ツールを呼び出すと、新しい Pod プロセスが独立して起動する
• scope lock file に分譲が記録され、spawner の effective scope が縮小する
• 要求 scope が spawner の effective scope を超えていたらツールエラー
• spawned Pod の socket に接続でき、task が Method::Run で送信される
• spawn 記録が保存され、ListPods で参照できる
• spawner が停止しても spawned Pod は続行する

範囲外

• Pod 間通信ツール（SendToPod / ReadPodOutput / StopPod / ListPods）は tickets/pod-comm-tools.md
• コールバック通知は tickets/pod-callback.md
• リモート spawn（SSH 越し）は docs/network-peering.md を参照