--- id: 20260528-001748-compact-session-log-exploration slug: compact-session-log-exploration title: Compact: session log 探索型の要約入力に変更する status: closed kind: task priority: P2 labels: [compact, session-log] created_at: 2026-05-28T00:17:48Z updated_at: 2026-05-28T03:41:42Z assignee: null legacy_ticket: null --- # Compact: session log 探索型の要約入力に変更する ## 背景 `insomnia-troubleshoot` Pod の手動 compact で、Compact Worker が入力トークン上限に到達して停止した。現行実装は `Pod::compact` で retained tail より前の `items_to_summarise` を `build_summary_input()` に渡し、`build_summary_prompt()` が user / assistant / system message と tool result summary を `## Conversation` に連結して Compact Worker の初回 input に載せている。 raw tool output や reasoning は落としているが、長い session では pruned transcript だけでも `compact_worker_max_input_tokens` を超える。Compact の目的は「全履歴を読ませる」ことではなく、次セッションに必要な構造化要約と file auto-read/reference を作ることなので、初期 input は軽量 overview に留め、必要箇所は Compact Worker が session log / workspace file を探索して確認できる形にする。 また、Compact Worker の健全性は「初期 input が小さいこと」だけでは保証できない。探索 tool の結果、assistant 出力、`write_summary` 呼び出しまでを含む Compact Worker 全体の context と、compact 後に作られる新 session 初期 context を別々に制御する必要がある。 ## 方針 Compact Worker の初期 context は、全文 transcript ではなく決定的に生成した session overview / index を渡す。LLM には探索空間を狭めた上で、必要な session log 範囲や workspace file を tool で読む権限を与える。 基本方針: - 初期 input は User / Assistant / System の継続に必要な情報を中心に、target size 内の overview として生成する。 - 初期 overview が target を超えた程度で compact を失敗させない。warning / trace に記録して続行する。 - 初期 overview deadline は通常運用の調整値ではなく、想定外の入力生成バグを検出する最悪ケースの安全網とする。deadline 超過時は、可能ならより粗い overview へ fallback し、それでも最低限の入力を作れない場合だけ失敗する。 - ToolCall / ToolResult は初期 input では本文を展開しない。 - tool 名、summary、対象 path、成否、大きな出力の有無、session log 上の位置などの index に留める。 - Compact Worker は session log の必要箇所を探索・再読できる。 - Compact Worker の探索量は、session-log/file-read 個別の総量 budget ではなく、Compact Worker session 全体の context budget で制御する。 - Compact Worker context が上限に近づいたら、`mark_read_required` とは独立に「探索を切り上げて `write_summary` へ進め」という勧告を Worker に渡し、人間にも警告を出す。 - 最終 summary と closing turn のための reserve を確保し、reserve を食い潰すほど大きい tool result は残 budget に合わせて抑制・切り詰め・再読指示にする。 - AutoRead 判断のため、workspace file は現行通り `read_file` で確認し、必要なものだけ `mark_read_required` / `add_reference` する。 - AutoRead budget は Compact Worker の探索 budget ではなく、compact 後の新 session 初期 context に注入される file content の合計上限として扱う。 - Compact Worker の出力は現行と同じく structured summary + auto-read + references を生成する。 ## Compact Worker / compaction parameters `[compaction]` 配下では `compact_` prefix を新規 parameter 名につけない。既存の `compact_*` key は、この ticket の実装時に同じ意味の prefix なし key へ整理する。 必要な parameter: - `retained_tokens` - compact 後に verbatim で残す history tail の token budget。 - `overview_target_tokens` - 初期 overview / index 生成器が目指す通常サイズ。超過しても即失敗しない。 - `overview_warning_tokens` - 初期 overview が想定より大きいことを記録・警告する閾値。compact は続行する。 - `overview_deadline_tokens` - 初期 overview の最悪ケース deadline。超過時はより粗い overview へ deterministic fallback し、それでも無理な場合だけ compact を失敗させる。 - `worker_context_max_tokens` - Compact Worker session 全体の context hard limit。system prompt、overview、assistant output、tool calls/results、session-log/file read results、`write_summary` 周辺の蓄積を含む。 - `finish_warning_remaining_tokens` - 残り context がこの値以下になったら、Compact Worker に探索切り上げと `write_summary` を促す勧告を入れる。 - `final_reserve_tokens` - 最終 summary と closing turn のために残す reserve。これを割り込みそうな tool result は full content を返さず、range 縮小や summary への移行を促す。 - `worker_max_turns` - Compact Worker の tool-loop 最大 turn 数。budget 制御とは別の runaway guard。 - `summary_target_tokens` - `write_summary` text の目標サイズ。prompt / nudge に使う。 - `summary_max_tokens` - `write_summary` text の hard validation。超過した summary は縮約を促すか compact 成功扱いにしない。 - `auto_read_budget_tokens` - `mark_read_required` によって compact 後の新 session に注入される file content の合計 token budget。 - `result_context_max_tokens` - compact 成功前に dry-run する新 session 初期 context の上限。summary、auto-read contents、references、task snapshot、retained tail を含む。 - `model` - compactor model。未指定なら main Worker の client を clone する。 Compact 発火条件の `threshold` / `request_threshold` は Compact Worker の健全性 parameter ではないが、既存の `compact_threshold` / `compact_request_threshold` を整理する場合は `[compaction]` 内の prefix なし key として扱う。 ## 要件 - `build_summary_input()` / compact 入力生成を、prefix 全体の pruned transcript 一括投入から、bounded overview + index 生成に変更する。 - overview は `overview_target_tokens` を目指して生成する。 - `overview_warning_tokens` 超過時は警告・trace を記録しつつ続行する。 - `overview_deadline_tokens` 超過時はより粗い deterministic overview に fallback する。通常ケースの user-facing hard error にしない。 - User / Assistant / System message を優先し、古い detail は落としてよい。 - Tool output content は初期 input に載せない。 - Compact Worker 用の session log 探索 tool を追加する。 - 例: `search_session_log(query, filters, range)`。 - 例: `read_session_items(range | item_ids, mode = compact/full)`。 - 必要なら large tool result を個別に読む tool を追加する。 - 探索 tool は session-store の現在 segment / compact 対象 range を正本として読む。 - Compact 対象外の future/retained tail と混ざらないよう range 境界を明示する。 - tool result full content を返す場合は Compact Worker の残り context / `final_reserve_tokens` を守る。 - session-log/file-read 個別の総量 budget を user-facing parameter として増やさず、主制御は `worker_context_max_tokens` に寄せる。 - Compact Worker の context occupancy を request 前に見積もり、`worker_context_max_tokens` を最後の hard stop として扱う。 - Compact Worker の残り context が `finish_warning_remaining_tokens` 以下になったら、追加探索を切り上げて `write_summary` に進むよう Worker に勧告し、人間向け warning も出す。 - `final_reserve_tokens` を割り込む可能性がある tool result は、full content を返さず bounded/truncated result とし、range 縮小または `write_summary` への移行を促す。 - `write_summary` 後に `summary_max_tokens` を validation する。超過時は縮約を促し、改善できない場合は compact 成功扱いにしない。 - compact 成功前に、`summary + auto-read + references + retained tail + task snapshot` の新 session 初期 context を dry-run 見積もりし、`result_context_max_tokens` を超えないことを確認する。 - `mark_read_required` / `add_reference` の意味論は維持する。 - AutoRead は session log 上の過去 tool output ではなく、現在の workspace file を `read_file` で確認してから選ぶ。 - `auto_read_budget_tokens` は新 session 初期 context への file content 注入上限であり、Compact Worker の探索 budget ではない。 - `resources/prompts/internal/compact_system.md` の summary target は `summary_target_tokens` から反映する。 - 手動 compact / auto compact の双方で同じ経路を使う。 - 巨大 session でも Compact Worker が初回 input 上限で即停止しない。 ## 完了条件 - 長い session で compact 初期 overview が transcript 全体を載せず、`overview_target_tokens` を目指して生成される unit test がある。 - `overview_warning_tokens` 超過時に compact が続行し、警告・trace が記録される test がある。 - `overview_deadline_tokens` 超過時に粗い deterministic overview へ fallback する test がある。 - Tool result content が初期 compact input に混入しないことを test で確認している。 - Compact Worker が session log overview から必要 range を tool で読み、`write_summary` まで到達できる test がある。 - `finish_warning_remaining_tokens` 到達時に Compact Worker へ探索切り上げ勧告が入り、人間向け warning も出る test がある。 - `final_reserve_tokens` を守るため、過大な tool result が bounded/truncated される test がある。 - `summary_max_tokens` 超過 summary が compact 成功扱いにならない、または縮約 nudge を受ける test がある。 - compact 後の新 session 初期 context が `result_context_max_tokens` で dry-run validation される test がある。 - `mark_read_required` / `add_reference` 既存 test が通り、auto-read budget の挙動が維持されている。 - `[compaction]` の新 parameter 名が docs / manifest schema / defaults に反映されている。 - `docs/compaction.md` と `resources/prompts/internal/compact_system.md` が新しい探索型 flow と budget/warning semantics に更新されている。 - `cargo fmt --check` と関連 crate の compact/session-store/pod/manifest tests が通る。 ## 範囲外 - Compact summary 自体を deterministic summarizer に置き換えること。 - Memory extract / consolidation の入力方式変更。 - 過去の壊れた session log の migration。 - Compact 後の retained tail token policy の再設計。 - session-log/file-read ごとの user-facing 総量 budget を増やすこと。 ## 実装メモ 現行コード上の主な起点: - `crates/pod/src/pod.rs::compact` - `crates/pod/src/pod.rs::build_summary_input` - `crates/pod/src/pod.rs::build_summary_prompt` - `crates/pod/src/compact/worker.rs` - `crates/manifest/src/lib.rs::CompactionConfig` - `crates/manifest/src/config.rs::CompactionConfigPartial` - `crates/manifest/src/defaults.rs` - `resources/prompts/internal/compact_system.md` - `docs/compaction.md`