# llm-worker: ストリーム途中失敗時の継続

## 背景

LLM 応答の SSE ストリームを読んでいる途中で upstream が切れると、
`crates/llm-worker/src/llm_client/transport.rs:231` で
`ClientError::Sse(...)`（中身は `eventsource_stream::Error::Transport`、
さらに reqwest の `error decoding response body`）として上に投げられ、
`worker.rs:933 stream_response` が `WorkerError` に変換して Run 全体が中断する。

実例: セッション `019de419-6f8b-71a0-9e56-f0b9a6c7098b.jsonl:236`。
直前まで text / tool_use を Timeline に積み続けていたが、
最後の SSE フレームが届く前に接続が切れ、Run が落ちた。

ここで重要な点:

- 出力トークンは upstream 側で既に発生しており、課金済み。
  単純に同じ request を再送すると二重出力 + 二重課金。
- Anthropic / OpenAI のいずれの API も、途切れた SSE を
  resume するエンドポイントは持たない。継続したい場合は
  「assistant turn として部分出力を history に置いた状態で再リクエスト」
  という形を自作する必要がある。
- 部分出力の質は内容依存:
  - 完成した text ブロックは原則そのまま history に置ける
  - 未完成の通常 text ブロックも、LLM の仕様上は assistant partial として置けば続きを生成させられる
  - tool_use の `input_json` が途中で切れたブロックは破損 JSON で、そのままは置けない
  - reasoning / thinking ブロックも provider 依存の扱いが要る

このため、これは「リトライ」ではなく「継続 (continuation)」。
`history` を編集する責務であり、`transport.rs` には収まらず、
`worker.rs` 層（または上位）の機能になる。
`feedback_llm_worker_scope.md` の方針（llm-worker は低レベル基盤に留める）にも合致する。

なお `worker.rs:973` 付近で部分 `flush_usage()` だけは既に行っており、
半分くらいは継続を意識した作りになっている。あとは
「壊れていないブロックの確定」と「次 call の起動条件」を足す形。

## 決定した方針

stream 開始後に transport / SSE error で落ちた場合、同じ request をそのまま再送しない。
Timeline に積まれた部分生成を安全な範囲で assistant history として確定し、その history を前提に continuation call を起動する。

- 通常 text は partial でも残す。
  - 完成済み text block はそのまま確定する。
  - 未完成 text block も text として確定し、次の LLMCall で続きを生成させる。
- tool_use は壊れていないものだけ残す。
  - 完成済み tool_use は通常通り確定する。
  - 未完成 tool_use / partial JSON は history に入れず破棄する。
  - 破棄した事実は structured diagnostic event として記録する。
- reasoning / thinking block は初期実装では保守的に扱う。
  - provider が history に安全に戻せる完成 block として扱えるものだけ残す。
  - 未完成または復元不能な thinking/reasoning は破棄し、diagnostic event に残す。
- continuation は自動で最大 5 回試す。
  - backoff は attempt ごとに伸ばす。例: 1s, 2s, 4s, 8s, 16s。
  - 5 回失敗したら turn を中断し、通常の失敗として上位へ返す。
- `Cancelled` / `Aborted` / interceptor `Yield` は continuation より優先する。
  - 明示的な user cancel や上位制御を transport error retry で覆さない。
- 明示的な safety / content filter stop reason が provider event として返る場合は retry 対象外にする。
  - transport / SSE error としてしか見えない場合は continuation 対象にする。
  - 同じ箇所で繰り返し切られる場合は最大 5 回で exhausted する。

## 失敗ログ / 統計

この機能は実運用での発生頻度と回復率を見たいので、continuation lifecycle を structured log として残す。
ログは統計・デバッグ用であり、通常の LLM context へ暗黙注入しない。

最低限記録する event:

- `llm_stream_interrupted`
  - provider / model
  - run_id / turn_id 相当
  - original attempt / continuation attempt
  - error kind: `sse_transport`, `sse_parse`, `body_decode`, `unknown` 等
  - error message
  - committed text block count
  - committed partial text の有無
  - discarded partial tool_use count
  - discarded thinking/reasoning count
  - usage flush の有無
- `llm_stream_continuation_started`
  - continuation attempt
  - backoff duration
  - history に確定した block summary
- `llm_stream_continuation_completed`
  - continuation attempt
  - completion reason
- `llm_stream_continuation_failed`
  - continuation attempt
  - error kind / message
- `llm_stream_continuation_exhausted`
  - attempts
  - final reason

未完成 tool_use を破棄した場合は、可能な範囲で以下も残す。

```json
{
  "event": "discarded_partial_tool_use",
  "tool_name": "Bash",
  "partial_input_bytes": 1234,
  "reason": "sse_transport_error"
}
```

## 要件

- ストリーム開始後の transport / SSE error を `worker.rs` 層で捕捉し、continuation 対象か判定する。
  - pre-stream の transient retry とは別枠にする。
  - 同じ request の単純再送はしない。
- Timeline に積まれた安全な block を assistant history として確定する。
  - 完成済み text block を残す。
  - 未完成 text block も残す。
  - 完成済み tool_use を残す。
  - 未完成 tool_use / partial JSON は破棄し、diagnostic event を記録する。
  - 未完成または復元不能な thinking/reasoning は破棄し、diagnostic event を記録する。
- continuation call を最大 5 回まで自動実行する。
  - attempt ごとに backoff を伸ばす。
  - 成功したら通常の LLMCall 完了として扱う。
  - exhausted したら turn を中断する。
- `Cancelled` / `Aborted` / interceptor `Yield` がある場合は continuation しない。
- provider が明示的な safety / content filter stop reason を正常 event として返した場合は continuation しない。
- continuation lifecycle と破棄した partial block の概要を structured log に残す。
  - 統計として provider/model 別の失敗頻度、回復率、partial tool_use 発生有無を後から集計できること。
- continuation のために context へ一時的な system message を暗黙注入しない。
  - もし LLM に中断事実を知らせる必要が出た場合は、history に残る明示 event/message として設計する。
  - 初期実装では壊れた tool_use は LLM に知らせず、ログにだけ残す。

## 完了条件

- stream 途中で transport / SSE error を起こすモック integration test がある。
- text-only partial response では、未完成 text が history に残り、continuation call が続きを生成する。
- partial tool_use response では、壊れた tool_use が history に入らず、discard diagnostic が記録される。
- completed tool_use は破棄されず、通常通り history に残る。
- continuation が最大 5 回で exhausted し、turn が中断される test がある。
- `Cancelled` / `Aborted` / `Yield` が continuation より優先される test がある。
- structured log から interrupted / started / completed / failed / exhausted が確認できる。
- 課金重複が起きないこと（過去ターンの単純再生成ではなく partial assistant history からの continuation であること）が test または手動手順で確認されている。
- `cargo check` / `cargo test` が `llm-worker` で通る。

## 範囲外

- pre-stream の transient リトライ → `llm-worker-transient-retry`
- ストリーム resume API の実装（プロバイダ側に存在しないので不可能）
- 課金額の自動上限制御
- 壊れた partial tool_use を system message 等で LLM に説明して復旧させる高度な戦略