feat(stream): claude→responses 空流兜底 + 首 token 前自动重试

[6Kmfi6HP]

背景

线上观察到 agent 在响应中间被 stream ended without completion 中断。定位根因（详见 commit）:上游 SSE 在整个流里既没发 response.completed / response.incomplete，也没产生任何 text/tool delta，就给了干净 EOF——典型的「prefill 阶段 tunnel 被反代（CF/nginx) 杀掉」故障形态。

参考 ParalonCloud《Stream ended without finish_reason》给的范式：重试窗口只在「向客户端写过第一个字节之前」存在；已经成功 commit 的流不能重试，必须如实告知。原代码所有流式 handler 都先 WriteHeader(200) 再看上游，架构层面没有这个窗口——这是要补的关键基建。

参考实现：new-api #3275/#4067、litellm router retry 策略。

方案（Phase A + Phase B 一次到位）

Phase A — EOF 兜底细分（原 claudeResponsesStreamHandler EOF 分支）

把「一刀切 emitError(stream ended without completion)」细分为三档：

分支	行为
已有 text/tool 产出	合成正常 stop(ParalonCloud Rule 2,不变)
仅有 thinking 无 text	reasoningFallback 兜底把思考提升为 text,agent 拿到思考不空手
完全空流	emitError("upstream ended stream before any content (empty completion)") 并 透出 retryable 信号

Phase B — 首 token 前自动重试（核心）

改动	内容
peekFirstOutput(claude_responses.go)	拿到上游 200 后先不 WriteHeader，在 stream\_first\_byte\_timeout\_ms 窗口内窥视首个完整 SSE 帧；EOF/超时/仅错误帧判 errStreamIncompleteNoCommit
claudeResponsesStreamHandler	改返回 (committed bool, err error);peek 的成功路径把消费行原样喂回主循环
claudeResponsesStreamWithRetry	forwardClaudeViaResponses / probeClaudeViaResponses 拿到 retryable 错误后，用同一份 claudeReq 经 callOpenCodeEndpoint 重发（自动切到 key_pool 下一个可用 key)，最多 stream\_empty\_retry\_max 次
streamReader.enableKeepalive	peek 窗口用零心跳避免误产 keepalive-commit;commit 后再切到常规 15s ticker

关键不变量

• peek 消费严格落在帧边界（空行或 EOF)，绝不截断中间——否则后续主循环 bufio 会把帧拼错。
• peek 的 reader 与主循环共享(bufio 已预读字节不能丢），通过 peekOutcome.reader 传递。
• 不会在已 commit 后再触发重试,agent 永远要么拿到完整的「干净成功流」，要么 502 进上层 fallback，不会看到「半截 error 然后又突然变正常」。
• prompt\_cache\_key 在重试间稳定，首次 attempt 已建立的 prefix cache 仍可命中，input tokens 接近零成本。

新增配置（config.json，默认开启，不进 admin UI)

{
  "stream_empty_retry_max": 1,
  "stream_first_byte_timeout_ms": 30000
}

• stream_empty\_retry\_max：重试次数（0=关闭）。默认 1 是「该做的兜底」而非用户选择——上游空流无毒可重试。
• stream\_first\_byte\_timeout\_ms：首字节看门狗，默认 30s（覆盖大多数 prefill 时间，<=0 关闭看门狗、仅 EOF 触发）。

测试

internal/app/claude_responses_empty_retry_test.go 加 8 个端到端回归，全部通过：

✓ TestClaudeResponsesStream_EmptyEOF_RetriesOnce              — 空流 → 重试成功
✓ TestClaudeResponsesStream_EmptyEOF_ExhaustsRetryThenErrors  — 2次空流 → fallback 502
✓ TestClaudeResponsesStream_EmptyEOF_RetryDisabled            — 关配置 → 不重试
✓ TestClaudeResponsesStream_PartialEOF_SynthesizesStopNoRetry — 半截流不重试
✓ TestClaudeResponsesStream_ThinkingOnlyEOF_PromotesReasoning — 仅thinking兜底
✓ TestClaudeResponsesStream_ErrorFrame_Retries                — response.failed → 重试
✓ TestClaudeResponsesStream_SilentUpstream_TimesOut           — 只发心跳不发data → 超时重试
✓ TestClaudeResponsesStream_HungUpstream_FirstByteWatchdogFires — 完全挂死 → 看门狗救人

外加不破坏既有用例（TestClaudeResponsesStream\_Mapping、TestClaudeStream\_PartialEOF\_NoFinish\_ErrorOnly 等）全过：make build / vet / fmt / test 全绿。

不做的事（明确边界）

• 已 commit 后的 EOF/断流:不改。仍按现有 emitError 兜底（ParalonCloud Rule 2),agent 拿到的就是已有的半截；这类只能靠 agent 框架自身重试。
• 其他流式 handler(chat→anthropic、responses→anthropic、anthropic 直通）：本次不动，先把出问题的 claude→responses 一条修好；模式稳定后再说复制。
• max\_tokens\_cap 配置：不动。它走的是 response.incomplete → stop\_reason: "max\_tokens" 的正常收尾路径，与本故障无关。
• key pool failover 计数：空流不计入 key 失败（这是协议故障不是 key 失效）。

真实运行验证

docs/CONFIGURATION.md 里附了复现脚本：用反代在 5s 时杀 tunnel，旧网关会让 agent 中断在 stream ended without completion，新网关在第一个 upstream 200 之后的空 peek 窗口里透明换 key 重试，整轮圆满完成。

🤖 Generated with Claude Code