Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

chore: complete llm retry continuation ticket

Browse Source
This commit is contained in:
Keisuke Hirata 2026-05-26 07:22:45 +09:00
parent be753099ae
commit 66540172de
2 changed files with 0 additions and 229 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
TODO.md
View File

@ -8,8 +8,6 @@
- Pod/TUI: 手動 rollback 導線 → [tickets/manual-turn-rollback.md](tickets/manual-turn-rollback.md)
- Pod: Inbound PodEvent ハンドリングの重複を統合 → [tickets/pod-inbound-pod-event-dedup.md](tickets/pod-inbound-pod-event-dedup.md)
- SpawnPod 初回 task delivery の受理確認 → [tickets/spawnpod-initial-run-confirmation.md](tickets/spawnpod-initial-run-confirmation.md)
- llm-worker のエラー耐性
- LLM request retry / stream 中断の可視化と継続 → [tickets/llm-worker-stream-continuation.md](tickets/llm-worker-stream-continuation.md)
- E2E テストハーネス（`tests/e2e/`、opt-in） → [tickets/e2e-harness.md](tickets/e2e-harness.md)
- メモリ機構
- consolidation skip 表示と invalid staging の観測性 → [tickets/memory-consolidation-skip-observability.md](tickets/memory-consolidation-skip-observability.md)

227
tickets/llm-worker-stream-continuation.md
View File

@ -1,227 +0,0 @@
# llm-worker: LLM request retry / stream continuation を可視化しつつ安全に継続する
## 背景
`Read` などの tool 実行が完了した後、本来は tool result を含めた次の LLM request が走り、assistant 応答が続く。実運用ではこの次 request が provider / upstream gateway から HTTP 504 を返すことがあり、LLM response stream を開く前の transient failure として retry する必要がある。
現在の問題は、retry / backoff 中であることが TUI に表示されず、「tool は終わったのに、その後の LLM 応答がハングした」ように見えることにある。
また、SSE stream が開始した後に途中で切れた場合、単純に同じ request を再送すると既に受け取った assistant 出力を二重生成させる可能性がある。stream 開始後の interruption では、安全に確定できる assistant output だけを history に積み、次 request で続きを生成する必要がある。
この ticket では、以下を一つの機能として扱う。
- HTTP transient retry / backoff の user-visible 化
- stream 開始後 interruption からの安全な continuation
- どちらの場合も TUI に「何を待っているか」を表示する経路
## 設計方針
LLM request が待っている理由は user-visible operational state として扱う。history / LLM context には入れない。
retry / continuation から protocol / TUI に直接依存させず、Worker の lifecycle event として下から上へ typed event を渡す。`HttpTransport` は 1 回の HTTP request と response classification を担当し、retry / backoff / cancellation / TUI 通知は Worker が管理する。
```text
HttpTransport
-> ClientError { status, retry_after, ... }
-> Worker retry / continuation state
-> llm-worker callback
-> Pod controller bridge
-> protocol::Event
-> TUI transient status / actionbar
```
正常系の制御フローは崩さない。過去実装のように continuation のために worker の共通 turn loop を大きく組み替えない。
正常 stream 完了時は、現行の成功経路をそのまま通す。
```text
stream_response
-> handle_completed_response
-> execute_and_commit_tools
```
continuation は `Worker::stream_response` の error branch 周辺に閉じ込める。
## Phase 1: HTTP transient retry を TUI に表示する
### 対象
`client.stream(request).await` が SSE stream を返す前に、HTTP response status / connect / timeout などで retryable error になったケース。
例:
- HTTP 504 gateway timeout
- HTTP 429 rate limit
- HTTP 500 / 502 / 503
- connect timeout
### 実装方針
1. `llm_client::client::LlmClient::stream(request)` は単発 request として維持する。
- 成功時は `ResponseStream` を返す。
- stream open 前の失敗は `ClientError` として返す。
- retry observer 付き entrypoint は作らない。
2. `llm_client::transport::HttpTransport::stream` は retry しない。
- HTTP status / connect / timeout を `ClientError` に分類する。
- `Retry-After` がある場合は `ClientError` の metadata として保持する。
3. `Worker` に `open_stream_with_retry` 相当の helper を置く。
- `RetryPolicy` と `is_retryable(&ClientError)` に従って `client.stream(request.clone())` を再試行する。
- backoff sleep は cancel / abort より低優先にする。
- sleep 前に `on_llm_retry` callback を発火する。
4. `Pod` の `wire_event_bridges_on_worker` で protocol event に変換する。
5. `TUI` は retry state を transient に表示する。
### protocol event
名称は実装時に最終決定してよいが、意味は以下を満たす typed event にする。
```rust
Event::LlmRetry {
llm_call: usize,
failed_attempt: u32,
max_attempts: u32,
wait_ms: u64,
elapsed_ms: u64,
status: Option<u16>,
error: String,
}
```
- `failed_attempt` は「直近で失敗した attempt 番号」として扱う。TUI 表示では次に実行される attempt を `failed_attempt + 1` として表示してよい。
- `status` は HTTP status が取れる場合のみ入れる。504 の場合は `Some(504)`。
- `error` は user-visible になり得るので、API key / Authorization header / request body を含めない。
- retry exhausted は既存の final error 経路で表示する。初期実装では sleep 前の retry notice に絞る。
### TUI 表示要件
- ToolResult 表示後、次 LLM request が retry に入った場合、TUI 上で待っている理由が分かること。
- status line または actionbar に少なくとも以下が出ること。
- retry 中であること
- HTTP status または error kind
- attempt / max_attempts
- 次 retry までの wait 秒数
- 例: `retrying LLM request after HTTP 504 (attempt 2/4 in 1.2s)`
- 表示は transient とする。次の `LlmCallStart` / `TextDelta` / `ToolCallStart` / `RunEnd` / `Status(Idle|Paused)` など、明確な進行イベントで消える。
- `Event::Alert` のように履歴 block として毎回積み上げない。retry が複数回起きると履歴がノイズで埋まるため。
## Phase 2: stream 開始後 interruption から continuation する
### 対象
`client.stream(request).await` が stream を返した後、stream event を読む途中で error / unexpected EOF が起きるケース。
HTTP status 504 のような stream 開始前 error は Phase 1 の retry 表示対象であり、partial history commit はしない。
### 実装方針
差し込み位置は `Worker::stream_response` の error branch に限定する。
- 正常に stream が完了した場合:
- 現行と同じ `TimelineDispatch` / collector の結果を使う。
- 現行と同じ assistant history commit 経路を使う。
- 現行と同じ tool execution 経路を使う。
- continuation 用の別 collector / 別 result type で正常系を包み直さない。
- stream 開始前の error の場合:
- HTTP retry / final error の扱いに任せる。
- partial history commit はしない。
- stream 開始後の error の場合:
- それまで `TimelineDispatch` が受け取った block のうち、安全に閉じているものだけを partial assistant message として history に commit する。
- 未完成の text block / reasoning item / tool_use は commit しない。
- partial commit 後、同じ turn loop 内で次の LLM request を発行する。
- cancel / abort / user interrupt は continuation より優先する。
### 設計上の制約
- `run_turn_loop` 全体を新しい generation sequence abstraction で置き換えない。
- 正常系の `stream_response -> handle_completed_response -> execute_and_commit_tools` の流れを維持する。
- continuation 用 state は error branch の局所 state として扱う。
- completed tool_use を stream interruption から復元して即 tool execution へ流すような特殊経路は初期実装では入れない。
- tool_use は protocol 上の境界が壊れると危険なので、stream が最後まで完了した場合だけ通常 collector から実行する。
- continuation の進行も TUI に user-visible event として表示する。
- continuation のための system reminder を history に積まず context だけへ差し込む実装は禁止。
### 推奨する差し込み形
`stream_response` の成功 result は保ちつつ、stream が途中で切れたことだけを表せる型にする。
```rust
enum StreamCompletion {
Complete,
Interrupted { reason: String },
}
```
`Complete` は現行成功経路へ進むだけで、成功時の assistant item / tool call を別 result type へ包み直さない。`Interrupted` には continuation notice と partial commit 判断に必要な理由だけを入れる。
`TimelineDispatch` / collector に partial drain API を追加し、途中中断時に安全に history 化できるものだけを取り出す。
- 完了済み text block
- 完了済み reasoning item
- 必要なら完了済み assistant metadata
未完成 block は破棄する。`abort_current_block` 相当の既存処理があるなら、それを明示的に使う。
擬似コード:
```rust
match self.stream_response(request).await? {
StreamCompletion::Complete => {
self.handle_completed_response().await?;
if self.execute_and_commit_tools(...).await? {
continue;
}
break;
}
StreamCompletion::Interrupted { reason } => {
if continuation_budget.exhausted() {
return Err(...);
}
self.commit_partial_assistant(...).await?;
self.emit_continuation_notice(reason);
continue;
}
}
```
この形なら、正常系は completed branch に留まり、途中中断時だけ continuation branch に入る。
## 要件
- HTTP 504 / 429 / 500 など retryable API status で backoff に入る前に retry notice が発火する。
- retry notice は worker callback として Pod 層に届く。
- Pod は retry notice を protocol event として TUI / socket clients に broadcast する。
- TUI は retry 中の状態を user-visible に表示する。
- retry notice は worker history / LLM context / session log の会話 item には入らない。
- API key / Authorization header / request body / tool output full content を retry event に含めない。
- stream が正常完了した場合、既存の成功経路と同じ挙動になる。
- tool call が含まれる正常 response では、既存と同じ collector 由来の tool calls だけが実行される。
- stream 開始前の HTTP error では partial history が増えない。
- stream 開始後に中断した場合、安全に完了済みの assistant item だけを history に commit する。
- 未完成 tool_use は commit / execute しない。
- continuation は最大回数で打ち切る。
- cancel / abort / user interrupt は continuation より優先される。
- continuation 中であることが TUI に表示される。
## 完了条件
- `HttpTransport` の unit test で retryable 504/503 が transport 内部では retry されず、`ClientError` として返る。
- `HttpTransport` の unit test で `Retry-After` が `ClientError` metadata として保持される。
- `Worker` の test で stream open 前の retryable error に対して `on_llm_retry` callback が呼ばれる。
- `protocol::Event` の retry / continuation event の serde roundtrip test がある。
- Pod controller bridge の test、または既存 bridge test への追加で retry / continuation event が流れることを確認する。
- TUI app test で retry / continuation event が transient state を更新し、進行イベントで clear されることを確認する。
- 正常 stream 完了 + text response の既存テストが通る。
- 正常 stream 完了 + tool_use response の既存テストが通る。
- stream 開始前 error で partial history が増えない test がある。
- stream 開始後 interruption で完了済み text だけが history に commit される test がある。
- incomplete tool_use が commit / execute されない test がある。
- continuation 回数上限の test がある。
- `cargo check` と関連 crate の test が通る。
## 範囲外
- retry policy の manifest 設定化。
- retry 回数や timeout の調整。
- provider 504 自体の削減。
- context pruning / compaction threshold の調整。
- E2E 実プロセス test。