第 42 章：Agent のタイムアウトと Watchdog
Watchdog が測るべきなのは既知 Phase での進展欠如であり、単なる経過時間ではありません。
公開ソースのスナップショット：実装例は 2026-07-27 に確認した Kocoro 公開
origin/mainのコミット4ec6772に基づきます。学ぶべき対象は不変条件であり、定数は最新ソースで再確認してください。
42.1 解くべき問題
「Agent がタイムアウトした」は、Provider chunk が来ない、正当に遅いツール、ローカル圧縮中、フェーズ所有権喪失などを含みます。単一 Timer では正常作業を殺すか、死んだ要求を待ちすぎます。
42.2 設計原則
明示的な Phase を追跡し、無活動が異常となる場所だけ Timer を有効化します。Soft Idle は状態を通知し復旧余地を与え、Hard Idle は transport 期限前の清掃時間を残して cancel し、Stream Idle は chunk 間隔を独立監視します。Phase 所有権を失ったときの挙動は意識して選びます。スナップショットの Runtime は、信用できない計時データで動くくらいならと、以降の実行で Watchdog を静かに無効化し、同時に「tracker はこの実行中は無効」という警告を stderr に出します。テストや strict モードではこの警告が panic に格上げされます。これは「ハングしうる」ことと引き換えに「不正なデータで正当な作業を取り消さない」を取る判断です。逆を好むなら、事故ではなく明示的な選択にしてください。
42.3 スナップショットの根拠
| ソーススナップショット | 観測 |
|---|---|
4ec6772 | スナップショット既定値：Soft Idle 90 秒、Hard Idle 540 秒 |
4ec6772 | Stream Idle gap：90 秒 |
4ec6772 | Phase Tracker は LLM 待機・Tool 実行・圧縮・終端処理を区別 |
上記の値は特定時点の実装例であり、普遍的な契約ではありません。
42.4 実装チェックリスト
- Fake clock で時間境界をテストする。
- タイムアウト計測に active phase を含める。
- cancel が Provider・tool・永続層・caller へ届くことを検証する。
42.5 まとめ
Watchdog が測るべきなのは既知 Phase での進展欠如であり、単なる経過時間ではありません。
各章は一つのシステムとして読んでください。コンテキスト、Tool Schema、永続化、ステアリング、時間規律、ループ検出、並列性は相互に影響します。