yoi/tickets/pod-comm-tools.md

Pod 間通信ツール: SendToPod / ReadPodOutput / StopPod / ListPods

背景

SpawnPod で Pod を生成した後、spawner の LLM が spawned Pod に指示を送り、結果を読み、完了したら停止させる手段が必要。

依存

• tickets/spawn-pod-tool.md: SpawnPod による Pod 生成と spawn 記録

ツール群

すべて都度接続の request-response で動作する。spawned Pod の socket に接続し、操作を行い、切断する。

SendToPod

既知の Pod にメッセージを送る。

入力:

• name: 対象の Pod
• message: 送信するテキスト

出力:

• 送信確認

内部動作:

• spawn 記録から name の socket path を引く
• socket に接続 → Method::Run { input: message } を送信 → ack 受信 → 切断

ReadPodOutput

既知の Pod の出力を読む。前回読んだ位置を自動追跡（カーソルベース）。

入力:

• name: 対象の Pod

出力:

• 前回読んだ位置以降の assistant テキスト出力
• 現在の状態（running / idle / stopped）

内部動作:

• spawn 記録から socket path を引く
• socket に接続 → Method::GetHistory で履歴取得 → 前回カーソル以降の assistant text を抽出 → カーソル更新 → 切断
• 接続できなければ stopped として返す

StopPod

既知の Pod を終了させ、譲渡した scope を回収する。

入力:

• name: 対象の Pod

出力:

• 終了確認
• 回収された scope の要約

内部動作:

• socket に接続 → Method::Shutdown 送信 → 終了確認受信 → 切断
• scope lock file を flock → 対象の allocation 削除 → spawner の deny を解除 → unlock
• spawn 記録から対象を削除

ListPods

自分が知っている Pod の一覧と状態を返す。

入力: なし

出力:

• 各 Pod の name、name、status、譲渡中の scope 要約、最終応答の要約

内部動作:

• spawn 記録を元にリストを構築
• 各 Pod に都度接続して health check（Method::GetHistory でステータス取得、接続できなければ stopped）
• stopped な Pod は scope lock file の stale 回収をトリガー

設計で決めること

• ReadPodOutput のカーソル管理: spawn 記録内に last_read_hash を持つか、別の場所で管理するか
• StopPod と scope 回収の順序: 先に Shutdown してから lock file を更新するか、lock file を先に更新するか（Shutdown が失敗した場合の整合性）
• ListPods の health check コスト: 大量の Pod がいるとき全部に接続するのは重い。キャッシュ戦略

完了条件

• SendToPod で spawned Pod にメッセージを送り、Pod がそれを処理する
• ReadPodOutput で spawned Pod の最新出力を読め、カーソルベースの差分取得が動作する
• StopPod で spawned Pod を graceful に停止でき、scope が spawner に返却される
• ListPods で既知の Pod の状態を一覧でき、health check が機能する
• 接続できない Pod は stopped として扱われ、scope の stale 回収がトリガーされる
• 単体テストで各ツールの正常系・異常系が検証される

範囲外

• コールバック通知は tickets/pod-callback.md
• Pod ネットワークの GUI / TUI 可視化