56 lines
6.2 KiB
Markdown
56 lines
6.2 KiB
Markdown
# Memory: extract worker のサーキットブレーカーを占有量ベースに統一
|
||
|
||
## 背景
|
||
|
||
`compact-worker-occupancy-cap` で compact worker のサーキットブレーカーを `UsageTracker` + `llm_worker::token_counter::total_tokens` ベースに切り替えたが、同じ設計上のバグを抱えた `MemoryExtractWorkerInterceptor` が `crates/pod/src/pod.rs:2180-2199` に残っている。実装コメントには `Mirror of compact::worker::CompactWorkerInterceptor;` と書かれており、compact 側が直った今、コメントも事実と乖離している。
|
||
|
||
具体的には:
|
||
|
||
- `MemoryExtractWorkerInterceptor` は `input_so_far: AtomicU64` に `UsageEvent.input_tokens` を `fetch_add` し、`pre_llm_request` で累積値が `max_input_tokens` を超えたら `Cancel` する (`pod.rs:1930-1942` で配線、`pod.rs:2186-2198` で判定)。
|
||
- `UsageEvent.input_tokens` は cache hit を含む prompt prefix 全体の占有量 (`crates/llm-worker/src/llm_client/event.rs:76-94`)。同じ prefix を毎ターンフルカウントするため、cache が 99% ヒットしても累積値は context size × ターン数で増える。
|
||
- 結果は compact と同じ：cap が「現在占有量」ではなく「累積（≒ context × turns）」を測っており、設計と整合しない。
|
||
|
||
extract worker は compact ほどツールループが深くない（`extract.write_extracted_tool` のみ、ファイル探索なし）ため誤発火頻度は compact より低いものの、構造的な誤りは同じであり、放置すると今後ツールが増えた瞬間に再発する。
|
||
|
||
メイン Pod のしきい値群と compact worker (修正済み) はどちらも `Pod::total_tokens()` (`pod.rs:146-149`) 経由で「現在の占有量」を見ており、extract worker だけ別ロジックという歪みも残っている。
|
||
|
||
## 方針
|
||
|
||
`MemoryExtractWorkerInterceptor` を、compact 側と同じ `UsageTracker` + `llm_worker::token_counter::total_tokens` 機構に乗せ替える。累積メトリックは廃止する。compact と対称に `extract_worker_max_turns` を新設し、`Worker::set_max_turns` 経由で extract worker に伝える。
|
||
|
||
## 要件
|
||
|
||
- `MemoryExtractWorkerInterceptor` の `pre_llm_request` を `llm_worker::token_counter::total_tokens(context, &records).tokens > max_input_tokens` ベースに置き換える。`input_so_far: AtomicU64` の累積パスは廃止。
|
||
- Extract worker にも `UsageTracker` を持たせ、`pre_llm_request` で `note_request(context.len())`、`on_usage` で `record_usage(event)` する。compact worker (`pod.rs:1535-1547` 周辺) と同じ配線パターン。
|
||
- `extract_worker_max_input_tokens` の意味を「extract worker 側の現在占有量しきい値」に変更し、ドキュメント (`crates/manifest/src/lib.rs:111-115`, `crates/manifest/src/defaults.rs:54-56`, 関連 `docs/`) を更新する。デフォルト値 30000 は新セマンティクスで再評価可能だが、変更必須ではない。
|
||
- `MemoryConfig` に `extract_worker_max_turns: Option<u32>` を追加し、cascade (`crates/manifest/src/config.rs`) に通したうえで extract worker 構築箇所 (`pod.rs:1924-1942`) で `extract_worker.set_max_turns` に渡す。デフォルトは要検討（仮: `Some(8)` — extract は本来 1-2 ターンで終わる軽量 worker のため compact より小さく）。
|
||
- compact 側で消した「Mirror of `CompactWorkerInterceptor`」というコメントを削除し、独立した interceptor として doc を整える（実体はほぼ同じだが、ロジック共有のための共通化はやらない: subsystem ごとにメッセージとしきい値が異なる前提を維持）。
|
||
- 後方互換 shim は入れない。`extract_worker_max_input_tokens` はフィールド名を維持しつつセマンティクスだけ差し替える。
|
||
|
||
## 完了条件
|
||
|
||
- 通常の extract 実行で、cache hit 込みの prefix がフルカウントされなくなり、現実的な extract 入力 (compaction 区間の skeleton) で cap に当たらない。
|
||
- extract worker のループが暴走するケースで、`extract_worker_max_turns` により打ち切られる。
|
||
- `Pod::total_tokens()` / `CompactWorkerInterceptor` / `MemoryExtractWorkerInterceptor` の 3 者が同じ算出経路 (`llm_worker::token_counter::total_tokens`) を使っている。
|
||
- `MemoryExtractWorkerInterceptor` のユニットテストで「累積では落ちる量でも occupancy では通る」「占有量が cap を超えたら cancel」の 2 パターンが covered されている。
|
||
|
||
## 範囲外
|
||
|
||
- `extract_threshold`（extract 発火条件）のセマンティクス変更。これは「ポインタ以降の cumulative input tokens」で別概念。
|
||
- Consolidation 側の同等変更（consolidation worker は別の lock + iteration 機構で動いており、interceptor 設計が異なる。必要なら別チケット）。
|
||
- `compact_threshold` / `compact_request_threshold` 自体のセマンティクス変更。
|
||
- 共通 `OccupancyInterceptor` を新設して compact / extract で共有する抽象化。サブシステム個別のメッセージ・cap・将来の挙動分岐を残せるよう、現状の重複構造を維持。
|
||
|
||
## 影響範囲
|
||
|
||
- `crates/pod/src/pod.rs`:
|
||
- `MemoryExtractWorkerInterceptor` 定義 (`pod.rs:2180-2199`) を occupancy ベースに書き換え、`input_so_far` フィールドを `usage_tracker: Arc<UsageTracker>` に置換。
|
||
- extract worker 構築箇所 (`pod.rs:1924-1942`) で `UsageTracker` 配線、`set_max_turns` 呼び出し追加。
|
||
- `crates/manifest/src/lib.rs`:
|
||
- `MemoryConfig::extract_worker_max_input_tokens` の doc を新セマンティクスに更新。
|
||
- `extract_worker_max_turns: Option<u32>` フィールド追加 + デフォルト値関数。
|
||
- `crates/manifest/src/config.rs`: `MemoryConfigPartial` への追加と cascade 解決。
|
||
- `crates/manifest/src/defaults.rs`: `MEMORY_EXTRACT_WORKER_MAX_INPUT_TOKENS` の doc 更新、`MEMORY_EXTRACT_WORKER_MAX_TURNS` 定数の追加。
|
||
- `docs/manifest.toml` 等の memory 設定例: 新フィールドと意味の更新。
|
||
- `crates/pod/src/pod.rs` 周辺もしくは新規モジュールでのユニットテスト（compact 側で追加した 2 パターンを extract 用に）。
|