yoi/tickets/pod-callback.md

Pod 間コールバック通知

背景

spawned Pod がイベント（ターン完了、エラー、終了、scope 又貸し）を発生させたとき、spawner に自動通知する仕組みが必要。Method::Notify（実装済み）が受け口となり、spawned Pod がそこにコールバックを送る。

依存

• tickets/spawn-pod-tool.md: spawn 記録と callback address の受け渡し
• Method::Notify: 実装済み。コールバック受信 → LLM への system message 注入

仕組み

callback address

spawn 時に spawner が自身の callback address を spawned Pod に渡す:

• ローカル: spawner の unix socket path
• リモート: insomnia@host:pod-name 形式（将来。docs/network-peering.md 参照）

spawned Pod はこの address を保持し、イベント発生時に一発接続して通知を送り、即切断する（webhook モデル）。

通知の種類

通知	タイミング	含まれるデータ
ターン完了	spawned Pod の1ターンが終了	name
エラー	spawned Pod でエラー発生	name, error_message
終了	spawned Pod が停止	name（scope 返却のトリガー）
scope 又貸し	spawned Pod が自身の scope を別 Pod に委譲	name, sub_name, sub_pod_socket, delegated_scope

通知は「シグナル」のみ

通知にはイベント種類と最小限のメタデータだけを含める。応答テキスト全体は含まない。spawner が内容を知りたければ ReadPodOutput で取りに行く。

spawner 側の処理

1. callback を受信
2. pod.push_notification(source, formatted_message) でバッファに追加
3. PodInterceptor::pre_llm_request が次の LLM リクエスト時に context に注入
4. IDLE なら Method::Notify の IDLE パスで自動ターン起動

scope 又貸し通知の特殊性

spawned Pod (B) が孫 Pod (D) に scope を又貸しした場合:

• B は spawner (A) に通知: 「/src/core を D に委譲した。D の socket は ...」
• A は D の存在と address をこの通知で知る（= 親からの紹介）
• A の spawn 記録に D が追加される
• B が死亡しても A は D を直接把握しており、scope lock file の stale 回収で delegated_from が A に付け替わる

コールバック送信の実装箇所

spawned Pod 側に callback 送信の仕組みが必要:

• ターン完了: Controller の RunEnd イベント発行時に callback を fire
• エラー: Controller の Error イベント発行時に callback を fire
• 終了: Controller の shutdown シーケンス内で callback を fire
• scope 又貸し: SpawnPod ツールの実行後に callback を fire

ポーリングでの代替

コールバックが失敗しても、spawner は ListPods のポーリングで状態を拾える。コールバックは最適化であり、唯一の手段ではない。

設計で決めること

• callback の message format: JSON? protocol crate の型を再利用? 独自の軽量フォーマット?
• callback 送信の非同期性: ターン完了時に callback 送信を await するか、fire-and-forget で spawn するか
• callback 失敗時のリトライ: リトライするか、ログだけ出して諦めるか
• callback address の更新: spawner が再起動して socket path が変わった場合の再登録手順

完了条件

• spawned Pod のターン完了・エラー・終了時に spawner の callback address に通知が送信される
• scope 又貸し時に spawner に通知が送信され、spawner が孫 Pod の存在を把握する
• callback 受信が Method::Notify パイプラインに乗り、spawner の LLM に system message として伝わる
• callback 送信が失敗しても spawned Pod は続行する
• 単体テストで各通知種別の送受信が検証される

範囲外

• リモートの callback（SSH 越し）。ローカル unix socket のみ
• callback の配信保証（at-least-once / exactly-once）。fire-and-forget で十分