diff --git a/TODO.md b/TODO.md index b8888ffe..490435af 100644 --- a/TODO.md +++ b/TODO.md @@ -5,6 +5,7 @@ - Pod CLI: マニフェスト関連フラグの整理 → [tickets/pod-cli-manifest-flags.md](tickets/pod-cli-manifest-flags.md) - Pod: 空応答ターン (Submit 後 AI 応答ゼロで Pause/Cancel) を自動巻き戻し → [tickets/pod-empty-turn-rollback.md](tickets/pod-empty-turn-rollback.md) - Pod: 任意ターンからの Fork(複数ターン巻き戻しを汎用化) → [tickets/pod-session-fork.md](tickets/pod-session-fork.md) +- Pod: 子→親の TurnEnded/Errored callback を親由来ターンのみに絞る → [tickets/pod-parent-turn-callback.md](tickets/pod-parent-turn-callback.md) - llm-worker のエラー耐性 - HTTP transient リトライ → [tickets/llm-worker-transient-retry.md](tickets/llm-worker-transient-retry.md) - ストリーム途中失敗時の継続 → [tickets/llm-worker-stream-continuation.md](tickets/llm-worker-stream-continuation.md) @@ -15,6 +16,7 @@ - spawn 失敗時に Pod の stderr が TUI に表示されない → [tickets/tui-spawn-error-surface.md](tickets/tui-spawn-error-surface.md) - role:system の system message を TUI に表示する仕組み → [tickets/tui-system-message-render.md](tickets/tui-system-message-render.md) - 巻き戻されたターンの入力テキストを編集領域に復元 → [tickets/tui-empty-turn-restore.md](tickets/tui-empty-turn-restore.md) + - ステータスライン `↑` をキャッシュ控除後の純アップロード量に → [tickets/tui-upload-tokens-net.md](tickets/tui-upload-tokens-net.md) - Manifest: Tool Output / File Upload 上限の分離とデフォルト緩和 → [tickets/manifest-output-upload-limits.md](tickets/manifest-output-upload-limits.md) - メモリ機構 - 使用頻度メトリクス + Knowledge 化候補レポート → [tickets/memory-usage-metrics.md](tickets/memory-usage-metrics.md) diff --git a/tickets/pod-parent-turn-callback.md b/tickets/pod-parent-turn-callback.md new file mode 100644 index 00000000..7c639b90 --- /dev/null +++ b/tickets/pod-parent-turn-callback.md @@ -0,0 +1,39 @@ +# 親が投げたターンのみを子→親 callback の対象にする + +## 背景 + +子 Pod は `controller.rs` の `run_with_cancel_support` で turn 終了時に `PodEvent::TurnEnded` / `PodEvent::Errored` を `parent_socket` 宛に fire-and-forget している。現状この発火条件は「`pod_future` が `Finished` / 失敗で抜けたら」であり、その turn が何起点かを区別していない。 + +子 Pod のターンは複数の経路で開始しうる: + +- 親からの `Method::Run`(`SpawnPod` の初回起動 / `SendToPod`) +- 子内部での `Method::Notify` 起点の auto-kick(`run_for_notification`)。Notify の出どころは孫 Pod からの `PodEvent`、system reminder、外部 Notify など多岐にわたる +- 将来的に増える可能性のある自走経路 + +入れ子 Pod を本格的に使い始めると、子の Notify 起点 turn が頻発する。これらが完了するたびに親へ `TurnEnded` が飛ぶと、親の `NotifyBuffer` には「自分が投げていないターンの完了」が積まれ、`pending_history_appends` で history に system message として commit され、親まで auto-kick される。親の history は「自分が把握していない子の内部活動」のノイズで埋まり、auto-kick の連鎖も意味的に正当化しづらい。 + +子→親の callback は、親が投げた仕事の消化境界を伝えるための信号に絞りたい。 + +## 要件 + +- 子 Pod が parent へ送る `PodEvent::TurnEnded` は、親由来の `Method::Run` を起点とする turn が `Finished` で完了した場合に限る。 + - 「親由来」の判定は「`Method::Run` で開始された turn」とする。SpawnPod 初回起動 / SendToPod はどちらも `Method::Run` 経由なので両方対象になる。 + - `run_for_notification` 起点の turn は完了しても `TurnEnded` を上げない。 + - `Method::Resume` 起点の turn は親由来として扱う(親が再開を指示した turn のため)。 +- `PodEvent::Errored` も同じスコープに揃える。Notify 起点 turn の worker 失敗は `parent_socket` への報告対象外とする(親が知らない指示の失敗報告になるため)。`Event::Error` でローカルに通知される経路は維持。 +- `PodEvent::ShutDown` は turn とは独立した Pod プロセス終了通知なので、本チケットの対象外(従来通り常に発火)。 +- `ScopeSubDelegated` も turn とは独立しているので対象外。 +- 親側の受信処理(`apply_event_side_effects` / `NotifyBuffer` への投入 / history への append)は変更しない。発火源を絞ることで自然にノイズが減る前提。 + +## 完了条件 + +- 子 Pod を spawn して `SpawnPod` の初回 Run または `SendToPod` で投げた turn が `Finished` で完了すると、親の history に当該 `TurnEnded` 由来の system message が 1 件 append される。 +- 子 Pod が孫 Pod からの `PodEvent::TurnEnded`(または他の Notify)で auto-kick された turn が完了しても、親の history には何も append されない。 +- 親由来 turn が worker エラーで失敗すると親に `Errored` が届く。Notify 起点 turn の worker エラーは親に届かない。 +- ユニットテストで「`Method::Run` 完了 → 親に届く」「`run_for_notification` 完了 → 親に届かない」「`Method::Resume` 完了 → 親に届く」「Notify 起点 turn の Errored → 親に届かない」を最低限カバーする。 + +## 範囲外 + +- Pod プロセス自体の永続化/復元(別途検討) +- `ShutDown` / `ScopeSubDelegated` の発火条件変更 +- 親が投げた個々の Run を ID で識別して相関させる仕組み(現状は「届いた / 届かない」で十分なので導入しない) diff --git a/tickets/tui-upload-tokens-net.md b/tickets/tui-upload-tokens-net.md new file mode 100644 index 00000000..2e4725f8 --- /dev/null +++ b/tickets/tui-upload-tokens-net.md @@ -0,0 +1,41 @@ +# TUI: ステータスライン `↑` をキャッシュ控除後の純アップロード量にする + +## 背景 + +TUI ステータスラインと `Block::TurnStats` で表示している `↑{input}/↓{output}` の `↑` が、tool ループの長いターンで現実離れした大きな値になる。 + +原因は2つ重なっている: + +1. **累積範囲**: `crates/tui/src/app.rs:469-470` で `Event::Usage` ごとに `run_input_tokens += input_tokens` を加算し、`RunEnd` で 0 リセット。1ターン内の全リクエストの input_tokens を単純合計している。 +2. **`input_tokens` の規約**: `crates/llm-worker/src/llm_client/event.rs:61-66` のコメント通り、`input_tokens` は「送信した prompt prefix 全体(cache_read + cache_creation 込み)」の占有量で、Anthropic scheme でも `convert_usage` で cache 込みに正規化済み。tool ループでは各リクエストが直前までの history 全体を prefix として送る → そのほとんどが cache hit → cache_read 分が毎リクエスト重複加算される。 + +結果として `↑` が「このターンで新たにアップロードしたトークン数」として読めず、ユーザー体験が悪い。 + +## 方針 + +**ターン内累積は維持**しつつ、各リクエストの加算値を `input_tokens - cache_read_input_tokens`(= cache_creation + 非キャッシュ入力 = 「このリクエストで full price で送った分」)に変える。 + +そのために protocol-level `Event::Usage` に cache 内訳を追加し、pod が worker UsageEvent から passthrough する。llm-worker 内部 (`UsageEvent`) と session-store (`LogEntry::LlmUsage`) には既に cache_read / cache_creation が載っているので、protocol の穴埋めだけで済む。 + +cache_creation は「このリクエストで新たにキャッシュに書いた分」で実質アップロードに含めて良い扱いとする(料金的にも full price 側)。よって表示式は `input_tokens - cache_read_input_tokens`。 + +## 要件 + +- protocol `Event::Usage` (`crates/protocol/src/lib.rs:284`) に `cache_read_input_tokens: Option`(最低限これ。cache_creation も載せるかは実装時に判断)を追加。 +- pod controller (`crates/pod/src/controller.rs:228-233`) が worker の `UsageEvent` から cache_read を passthrough する。 +- TUI 側 (`app.rs:469`, `block.rs:44-48`, `ui.rs:407-422 / 778-793`) は `input_tokens - cache_read_input_tokens` を累積・表示する。`Block::TurnStats` のフィールド意味も同方向に揃える(純アップロード量)。 +- `pod/examples/pod_protocol.rs:76` のサンプルプリントも整合させる。 +- 既存テスト・session-store 側ログ(`LogEntry::LlmUsage` は cache 内訳を既に持っているので変更不要)が壊れないこと。 + +## 完了条件 + +- TUI で tool ループの長いターンを回しても、`↑` が同じ history を毎回再カウントせず、現実的なオーダーに収まる。 +- `Block::TurnStats` の `↑` も同じ意味(純アップロード)で揃う。 +- protocol / pod / TUI が cache_read 情報を受け渡せる経路ができている。 + +## 範囲外 + +- TUI 以外のクライアント(pod_cli 等)の表示変更。 +- 料金計算・課金表示の追加(あくまで「アップロード量」の意味付け修正)。 +- セッション全体(複数ターン)の累積表示。 +- cache hit 率のような追加指標の表示。