69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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` を参照
|