81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
# 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 で十分
|