网关 finish_reason: network_error 未被重试（根因 + 已测试修复 + 过渡插件）

[fan56]

问题现象

在 OpenAI 兼容网关（如 OpenCode Zen）后面，turn 会直接硬失败，错误串恒定：

Provider finish_reason: network_error

网关把自身上游连接的瞬时失败作为流的 finish_reason 上报；立即重试几乎总能成功（同类报告见 anomalyco/opencode#41236）。dsh 把该失败归类为不可重试，于是整个 turn 硬失败而不是重试——一次真实会话中，subagent 通道连续 8 次都挂在这个串上。

根因

两个 adapter 把线上 finish_reason 翻译成错误码，都漏掉了 network 变体：

1. llm-pi-ai — pi-ai 0.82 把未知 finish_reason 映射为 stopReason: 'error'，errorMessage 为 Provider finish_reason: network_error（@earendil-works/pi-ai api/openai-completions.js 的 mapStopReason）。随后 classifyPiAiError（packages/llm/llm-pi-ai/src/stream.ts）用 /\b(?:network|connection|socket|fetch)\b/ 匹配——但 \b 在 k 与 _ 之间不成立（下划线是 word 字符），network_error 落到 PI_AI_ERROR，而它不在 DEFAULT_RETRYABLE_CODES 里。llm-retry 放行，turn 失败。
2. llm-deepseek — mapFinishReason（packages/llm/llm-deepseek/src/translate.ts）把未知 reason 大写化为失败码：network_error → NETWORK_ERROR，同样不在 DEFAULT_RETRYABLE_CODES。

参照

opencode 在 2026-08-21 修复了同样的网关行为：

• anomalyco/opencode@40282c1 — 可重试正则从 network error 扩为 network[-_\s]error，覆盖连字符/下划线变体。
• anomalyco/opencode@e0b9e68 — finish-step 事件 rawFinishReason === "network_error" 时按失败处理，进入既有重试管线（测试断言第 2 次尝试成功）。

修复（已备好，已测试）

由于仓库当前不接受外部 PR，修复已在 fork 分支上完成并充分测试：

https://github.com/fan56/deepseek-harness/tree/fix/network-error-retryable

• llm-pi-ai：classifyPiAiError 在既有 alternation 之前增加显式的 /network[-_ ]error/i 分支，三种拼写都归 TRANSPORT。既有匹配（AUTH/quota/429/4xx/5xx/timeout/流截断/ECONN*/terminated/premature close）全部不动。
• llm-deepseek：mapFinishReason 把 network_error / network-error 映射为 {kind:'error', failure:{message:'model stopped: <reason>', code:'TRANSPORT'}}。

TRANSPORT 已在 DEFAULT_RETRYABLE_CODES 中，无需改动 retry policy。

测试：llm-pi-ai/tests/convert.spec.ts 扩展了 transport wording 表；llm-deepseek/tests/translate.spec.ts 增加 mapFinishReason 用例。vitest run packages/llm/llm-pi-ai packages/llm/llm-deepseek → 608 全过；pnpm run typecheck → 干净。如果团队愿意合入，我可以随时 rebase/调整。

已发布版本的过渡插件

给已发布版本用户的插件（在 agent/request-error waterfall 末端重试这类失败，仅当所有下游 listener 都弃权时才行动）：

• 仓库：https://github.com/fan56/dsh-llm-net-retry
• npm：@aiwayds/dsh-llm-net-retry@0.1.0（dsh plugin --profile tui add @aiwayds/dsh-llm-net-retry）

它的 e2e 用真实 agent loop + llm-pi-ai openai-completions adapter 打一个脚本化网关（前两次请求回 finish_reason: network_error），断言第三次完成 turn。基础修复合入后该插件自然无害：它只在整个 waterfall 弃权时行动，且绝不触碰 llm-retry 自身的计数。已在真实 dsh 0.1.0-rc.8 TUI 宿主上验证——见下方更新评论。

效果

修复后，网关 network_error 在两条 adapter 路径上都归为 TRANSPORT，落入默认可重试码，llm-retry 以标准有界指数退避自动重试（5 次，500 ms→10 s）。既有 llm/retry 事件消费者（TUI）无需任何改动即可展示重试。

English version

Problem

Behind OpenAI-compatible gateways (e.g. OpenCode Zen), a turn fails outright with:

Provider finish_reason: network_error

The gateway reports its own transient upstream connection failure as the stream's finish_reason; retrying immediately usually succeeds (same class of reports as anomalyco/opencode#41236). dsh classifies this failure as non-retryable, so the whole turn hard-fails instead of retrying — in one real session the subagent channel hit this string 8 times in a row.

Root cause

Two adapters turn the wire finish_reason into an error code, and both miss the network variant:

1. llm-pi-ai — pi-ai 0.82 maps an unknown finish_reason to stopReason: 'error' with errorMessage: 'Provider finish_reason: network_error' (@earendil-works/pi-ai api/openai-completions.js, mapStopReason). classifyPiAiError (packages/llm/llm-pi-ai/src/stream.ts) then tests /\b(?:network|connection|socket|fetch)\b/ — but \b does not hold between k and _ (underscore is a word character), so network_error falls through to PI_AI_ERROR, which DEFAULT_RETRYABLE_CODES does not include. llm-retry passes the failure through and the turn fails.
2. llm-deepseek — mapFinishReason (packages/llm/llm-deepseek/src/translate.ts) uppercases unknown reasons into the failure code: network_error → NETWORK_ERROR, also not in DEFAULT_RETRYABLE_CODES.

Reference

opencode hit and fixed the same gateway behavior on 2026-08-21:

• anomalyco/opencode@40282c1 — widen the retryable regex from network error to network[-_\s]error, covering the hyphen/underscore variants.
• anomalyco/opencode@e0b9e68 — fail the finish-step event when rawFinishReason === "network_error" so the existing retry pipeline handles it (test asserts the 2nd attempt succeeds).

Fix (prepared, tested)

Since the repository does not accept external PRs at the moment, the fix is prepared and fully tested on a fork branch:

https://github.com/fan56/deepseek-harness/tree/fix/network-error-retryable

• llm-pi-ai: classifyPiAiError gains an explicit /network[-_ ]error/i arm ahead of the existing alternation, classifying all three spellings as TRANSPORT. The existing matches (AUTH/quota/429/4xx/5xx/timeout/stream-truncation/ECONN*/terminated/premature close) are untouched.
• llm-deepseek: mapFinishReason maps network_error/network-error to {kind:'error', failure:{message:'model stopped: <reason>', code:'TRANSPORT'}}.

TRANSPORT is already in DEFAULT_RETRYABLE_CODES, so no retry-policy change is needed.

Tests: transport-wording table extended in llm-pi-ai/tests/convert.spec.ts; mapFinishReason cases in llm-deepseek/tests/translate.spec.ts. vitest run packages/llm/llm-pi-ai packages/llm/llm-deepseek → 608 passed; pnpm run typecheck → clean. Happy to rebase/adjust if the team wants to land it.

Workaround plugin for released versions

A plugin for users on released versions (retries these failures at the end of the agent/request-error waterfall, only when every downstream listener declined):

https://github.com/fan56/dsh-llm-net-retry — also on npm as @aiwayds/dsh-llm-net-retry@0.1.0 (dsh plugin --profile tui add @aiwayds/dsh-llm-net-retry).

Its e2e drives the real agent loop + llm-pi-ai openai-completions adapter against a scripted gateway failing the first two requests with finish_reason: network_error and asserts the turn completes on the third. The plugin stays harmless once the base fix lands: it only acts when the whole waterfall declined and never touches llm-retry's own counting. Now also validated on a real dsh 0.1.0-rc.8 TUI host — see the update comment below.

Result

With the fix, a gateway network_error classifies as TRANSPORT on both adapter paths, falls inside the default retryable codes, and llm-retry retries it with the standard bounded exponential backoff (5 attempts, 500 ms→10 s). Existing llm/retry event consumers (TUI) surface the retries with no changes.

[fan56]

更新——已在真实 dsh 宿主（TUI）上验证

上面的过渡插件已在真实 dsh --profile tui 启动（dsh 0.1.0-rc.8）中完成端到端验证：

• 环境：插件通过 dsh plugin --profile tui add … 装入 tui profile；默认模型经 --patch 覆盖 + 临时 settings 文件指向脚本化的本地 OpenAI 兼容网关（真实 settings 文档零触碰）。网关前两次请求回 finish_reason: "network_error"，之后回普通文本。
• 观察：默认 policy 对这个被误分类的失败弃权，插件调度有界重试，turn 在第三次请求完成、网关文本渲染在 TUI 中。持久化 session 日志在插件自己的 policy key 下记录了完整链条——llm/retry retry 1（延迟 ≈524 ms）→ llm/retry-started → llm/retry retry 2（延迟 ≈1056 ms）→ llm/retry-started → 成功：指数退避 + 对称抖动，整条链共用一个 retryId。
• TUI 零改动：它本来就渲染 llm/retry 事件，这些重试与原生 dsh-llm-retry 的重试展示完全一致。

仓库还带完整自动化套件：单测（匹配表、注入随机数的退避计算、配置校验、真实 cordis context 上的决策链）+ agent-loop e2e（真实 llm-pi-ai openai-completions adapter 打同样的脚本化网关），并有负向对照证明无插件时一次请求后 turn 即硬失败。

English version

Update — validated on a real dsh host (TUI)

The workaround plugin above is now verified end-to-end on a live dsh --profile tui boot (dsh 0.1.0-rc.8):

• Setup: the plugin was installed into the tui profile with dsh plugin --profile tui add …, and the default model was routed to a scripted local OpenAI-compatible gateway through a --patch overlay plus a temporary settings file (the real settings document untouched). The gateway answers the first two requests with finish_reason: "network_error" and every later one with plain text.
• Observed: the stock policy declined the misclassified failure, the plugin scheduled its bounded retry, and the turn completed on the third request with the gateway's text rendered in the TUI. The durable session log shows the full chain under the plugin's own policy key — llm/retry retry 1 (delay ≈524 ms) → llm/retry-started → llm/retry retry 2 (delay ≈1056 ms) → llm/retry-started → success: exponential backoff with symmetric jitter and one stable retryId across the chain.
• The TUI needed no changes: it already renders llm/retry events, so these retries surface exactly like stock dsh-llm-retry retries.

The repo also carries the automated suite: unit tests (matcher table, backoff math with injected randomness, config validation, and the decision chain on a real cordis context with a real session store) plus an agent-loop e2e that drives the real llm-pi-ai openai-completions adapter against the same scripted gateway behavior, with a negative control proving the turn hard-fails after a single request without the plugin.

[weijiafu14]

这帖已有两条可用产物：上游窄修复和真实 rc.8 TUI 验证过的过渡插件 @aiwayds/dsh-llm-net-retry，无需 pi2dsh 重复实现。后续固定验收：finish_reason: network_error 映射为可重试失败、发生一次受控重试、取消停止、永久错误不循环。