58 lines
4.1 KiB
Markdown
58 lines
4.1 KiB
Markdown
# Subagent Anti-Blackhole Runbook
|
||
|
||
## Dispatch receipt fields
|
||
|
||
Dispatch receipt 僅定義子代理派發當下所需的欄位，用來識別本次派發、關聯子 session，以及標記預期完成時限。
|
||
|
||
- `runId`: 本次 subagent dispatch 的唯一執行識別碼。用於把同一次任務派發、後續狀態檢查與回報關聯到同一個 run。
|
||
- `childSessionKey`: 子代理 session 的穩定關聯鍵。用於把 dispatch receipt 對應到實際被派發出去的 child session。
|
||
- `dispatchAt`: dispatch receipt 寫入時間，也就是主流程實際派發 subagent 的時間戳記。建議使用可排序的標準時間格式。
|
||
- `expectedBy`: 依照當次任務 SLA 或預估完成時間計算出的期望完成時間戳記。用於判斷目前仍屬正常執行中，或已超過預期等待窗口。
|
||
|
||
> 本節僅定義 dispatch receipt 欄位，不涵蓋 completion receipts、watchdog logic、recovery 流程或其他後續 task。
|
||
|
||
## Minimal example
|
||
|
||
```json
|
||
{
|
||
"runId": "run_2026-04-24_001",
|
||
"childSessionKey": "agent:engineering:subagent:example",
|
||
"dispatchAt": "2026-04-24T10:00:00+08:00",
|
||
"expectedBy": "2026-04-24T10:15:00+08:00"
|
||
}
|
||
```
|
||
|
||
## Completion receipt fields
|
||
|
||
Completion receipt 僅定義子代理完成結果被接收到之後所需記錄的欄位，用來區分「子代理已完成」與「結果是否已成功轉交 main conversation」。
|
||
|
||
- `completionReceivedAt`: 主流程或監看機制實際收到 completion/result 的時間戳記。用於確認子代理何時已經完成並回傳結果，不再只靠 `expectedBy` 推估。
|
||
- `forwardedToMain`: 布林欄位，表示該 completion/result 是否已成功轉送到 main conversation。用於區分「已收到結果」與「已完成主線回報」這兩個不同狀態。
|
||
- `resultSource`: completion/result 的來源標記，例如來自主動 completion push、補抓回來的 session 狀態，或其他明確來源。用於後續判讀結果是正常送達還是經由補救路徑取得。
|
||
|
||
> 本節僅定義 completion receipt 欄位，不涵蓋 watchdog logic、recovery 流程、scenario tests 或其他後續 task。
|
||
|
||
|
||
## Watchdog statuses
|
||
|
||
Watchdog status 僅定義監看子代理完成投遞狀態時可使用的狀態列舉，用於區分仍在正常等待、疑似投遞失敗、結果已存在但未轉交，以及已完成或已卡住等情況。
|
||
|
||
- `active`: dispatch receipt 已存在，且目前仍在 `expectedBy` 之前，也還沒有任何 completion receipt。表示子代理仍在正常等待窗口內，watchdog 只需持續觀察，不應提前視為異常。
|
||
- `suspect_delivery_failure`: dispatch receipt 已存在、目前已超過 `expectedBy`，但主流程仍未收到 completion receipt。表示尚無法證明子代理失敗或成功，只能判定為疑似 completion delivery 出問題，需進入明確的人工可見關注狀態。
|
||
- `done_but_not_forwarded`: 已有可信訊號顯示子代理工作其實做完了，但 main thread 仍沒有對應的 forwarded completion receipt。表示結果可能存在於 child session 或其他回傳路徑上，只是沒有成功 bounce 回主線。
|
||
- `completed`: completion receipt 已被主流程接收，且結果已成功進入主線回報路徑。表示此 run 的 watchdog 可視為正常閉合，不再屬於 blackhole 風險案例。
|
||
- `recovered`: 先前曾落入 `suspect_delivery_failure` 或 `done_but_not_forwarded`，之後透過後續確認或補抓，已把結果重新接回可追蹤狀態。此狀態只定義「已從異常投遞風險中恢復」的語意，不在本 task 提前定義 recovery logic。
|
||
- `blocked`: watchdog 已判定目前無法再以被動等待來解釋狀態，且該 run 需要明確升級處理或人工介入。此狀態只定義「已卡住、不可再默默等待」的語意，不在本 task 提前定義 escalation 或處置流程。
|
||
|
||
> 本節僅定義 watchdog statuses 的語意與邊界，不提前實作 recovery logic、receipt state code、scenario tests 或其他後續 task。
|
||
|
||
## Completion receipt example
|
||
|
||
```json
|
||
{
|
||
"completionReceivedAt": "2026-04-24T10:12:34+08:00",
|
||
"forwardedToMain": true,
|
||
"resultSource": "completion_push"
|
||
}
|
||
```
|