[Bug][0.2.1-alpha.2] server_error still bypasses retry on current master; validated narrow SERVER fix

[jghwwnq]

Summary

This remains reproducible on current master (d743267388641bc76f17c45ce8b4c231aed1d32c, package version 0.2.1-alpha.2) as of 2026-10-12.

An OpenAI Responses-compatible provider can return a terminal error such as:

server_error: Our servers are currently overloaded. Please try again later.

@deepseek-ai/dsh-llm-pi-ai classifies it as PI_AI_ERROR, so the normal retry policy does not retry it. This is a fresh current-master verification of the issue previously reported in #3407; the upstream source still contains the numeric-5xx-only classifier.

Runtime evidence

A real Desktop session showed both paths in the same session:

• bodyless OpenAI API 503 failures entered the configured retry path;
• the later textual server_error failure ended the turn immediately as PI_AI_ERROR, with no llm/retry or llm/retry-started event for that failure.

This rules out a missing retry plugin or exhausted global retry mechanism. The classification result is the deciding difference.

Root cause

Current classifyPiAiError() recognizes numeric 5xx text only:

if (/\b5\d\d\b/.test(message)) return 'SERVER'

The provider's stable server_error marker carries no HTTP status, falls through to PI_AI_ERROR, and is therefore excluded from the default retryable set (EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT).

Minimal fix

-  if (/\b5\d\d\b/.test(message)) return 'SERVER'
+  if (/\b5\d\d\b|\bserver_error\b/i.test(message)) return 'SERVER'

The branch order should stay unchanged so authentication, quota, rate-limit, and invalid-request classifications keep precedence.

This is intentionally narrower than adding PI_AI_ERROR to retryableCodes: terminal pending, deferred, and unknown permanent provider failures should remain non-retryable. The patch preserves the original message and lets the existing bounded retry policy handle only the newly recognized server failure.

Regression coverage added locally

1. Two mapStopReason() cases cover the complete error text and bare server_error, asserting both SERVER and exact message preservation.
2. A loopback OpenAI Responses SSE test emits a real response.failed event with { code: "server_error" } through LlmPiAi and asserts SERVER.
3. A keyless server-error-retry session snapshot records SERVER → llm/retry → llm/retry-started → completed.

All three new assertions fail against the unmodified classifier (PI_AI_ERROR) and pass after the one-line mapping change.

Validation

• focused pi-ai suites: 140/140 passed;
• focused keyless session snapshot: 1 passed;
• package TypeScript build check: passed;
• pnpm run test:docs: 21 passed, 0 failed;
• pnpm run doc-sync: 43 passed, 0 failed;
• repository lint: passed;
• git diff --check: passed.

The local change also updates the pi-ai English/Chinese package README and translation-pairing record. It remains uncommitted and unpushed.

Suggested upstream action

Please land the narrow server_error → SERVER mapping and the adapter/session regressions. Longer term, preserving the provider's structured error code/status through pi-ai into DSH would remove the need to infer transient classes from display text.

[PerryLink]

这条也成立，而且我能补上你没解释的那个不对称：为什么同样是 5xx 级故障，一条走重试、另一条不走。

1. 那一行就是问题所在

packages/llm/llm-pi-ai/src/stream.ts:50：

if (/\b5\d\d\b/.test(message)) return 'SERVER'

server_error 里没有任何数字 ⇒ 必然落到 :67 的 return 'PI_AI_ERROR'。

我把前面几个分支逐条核了一遍，确认不会误吞 server_error: Our servers are currently overloaded. Please try again later.：

• :43 /\b(?:401|403)\b/ —— 无数字
• :44 isQuotaExceededError(message) —— 无 quota/balance/credits/out of budget 字样
• :45 /\b429\b|rate.?limit/i —— 无
• :48 /\b413\b|failed to buffer the request body…|payload too large|request body too large/i —— 无
• :49 /\b400\b|invalid.?request/i —— 无

SERVER 在 retry-policy.ts:21 的表里，PI_AI_ERROR 不在 ⇒ llm-retry/src/index.ts:215 直接放行。你的定位准确。

2. ⭐ 那个不对称的原因：两条 pi-ai 路线生成的字符串形状不同

你注意到"同一会话里 503 走重试、文本 server_error 不走"，但没解释。机制是：

• 其它协议走 pi-ai 的 dist/utils/error-body.js:110-117 的 formatProviderError，输出形状是 `<status>: <body>`（例如 503: {"error":{…}}）—— 带数字状态码 ⇒ 能被 /\b5\d\d\b/ 抓到
• Responses 路线走 dist/api/openai-responses-shared.js:651 的 `${error.code || "unknown"}: ${error.message || "no message"}` —— 不含 status ⇒ 数字分支永远不可能命中

⇒ 所以"同一个 5xx 级故障，分类结果不同"不是随机的，而是由 pi-ai 用哪条路线格式化错误决定的。这一条建议写进报告 —— 它把一个看起来像巧合的现象变成了确定机制。

（我拉了 origin/master lock 钉的 @earendil-works/pi-ai@1.0.2 核对；⚠️ 本机 node_modules 里是 0.87.1 旧版，别用它验证。）

3. 一处措辞要收窄

你写 "the upstream source still contains the numeric-5xx-only classifier" —— classifyPiAiError 整体有 8 个分支（401/403、quota、429、413、400、5xx、timeout、stream-ended、transport 兜底），只有 SERVER 这一支是按数字 5xx 判的。

⇒ 建议改成"SERVER 这一支只认数字 5xx"。原样引用会显得不准，而你的 diff 定位本身是对的 —— 别让措辞拖累它。

4. 你的克制是对的，我确认一遍

你明确说不要图省事把 PI_AI_ERROR 整体加进 retryableCodes —— 这个判断正确：stream.ts:111-118 的 pending / deferred 状态也发 PI_AI_ERROR，放宽会把永久失败变成无限重试。

分支顺序必须保持在其后（:43-49 的优先级），这一点你也说对了。⇒ 修法就是 stream.ts:50 扩成 /\b5\d\d\b|\bserver_error\b/i。

5. 建议与 #9508 合并成一份通用修法

你的 server_error（本贴）与 upstream_http2_stream_error（#9508）同作者、同一天、同一族，共享同一条闸门（llm-retry/src/index.ts:215）与同一个上游字符串生成点。

既然 pi-ai 生成的形状是 `${code}: ${message}`（openai-responses-shared.js:651），DSH 现在就能从 message 开头解析出 code，不必等 pi-ai 把 code 独立暴露。

⇒ 建议把两帖合成一份修法：解析 ^(code): 前缀 + 一张已知瞬时码表（server_error、upstream_http2_stream_error、upstream_http2_* 整族…）。这样一次覆盖两帖，而且保持白名单结构、不会扩大兜底。维护者的评审成本会低很多。

6. 版本

你标 0.2.1-alpha.2 / commit d743267388 —— 独立复核 git rev-list --count d743267388..origin/master = 0，就是当前 master，未过期。

7. 一条边界

你本机的 140/140 测试数字属于私有改动，我没有核实；不影响上面的源码结论，建议标注为"本机测试"。

8. 一个可以直接引用的旁证

stream.ts:34-41 有一条 XXX(pi-ai upstream) 注释，说明 pi-ai 会把错误压成 error.message、丢掉原始 Error 与 cause 链。⇒ 维护者知道这一层只能做文本分类，所以你的补丁形态正合现状，不需要先解决上游丢 cause 的问题。这一点能让补丁立刻可接受。