[Bug] llm-pi-ai 将上游重试缓冲错误归为 PI_AI_ERROR，跳过自动重试

[Anonymousnake]

问题

在 GPT / openai-codex 会话中，上游返回以下错误时，DSH 将它归类为 PI_AI_ERROR，直接结束当前请求，没有进入正常退避重试：

exceeded request buffer limit while retrying upstream
PI_AI_ERROR

环境与观测

• DSH / dsh-llm-pi-ai：0.2.0-rc.2
• pi-ai：0.87.1
• Windows，Node v24.19.0，dsh web，openai-codex 路由。
• 在同一实际会话中确认了两次该错误；失败的 assistant/attempt 记录均为 PI_AI_ERROR，对应失败之后没有 llm/retry / llm/retry-started，随后 turn/end 以错误结束。
• 该会话其他请求存在正常重试记录，说明恢复插件已经加载，而不是完全没有启用重试。

原因

当前 master 的 classifyPiAiError 仅通过数字 5xx 识别 SERVER。上述纯文本没有状态码，也未命中其他分类，因此落入 PI_AI_ERROR。

Harness 给 pi-ai 设置 maxRetries: 0，交由 dsh-llm-retry 统一恢复。默认重试集合包含 SERVER，但不包含兜底的 PI_AI_ERROR；因此这一分类遗漏使正常重试被跳过。

pi-ai 0.87.1 的 utils/retry.js 已将这句完整文本列为可重试错误。该文本也与 Envoy 的上游重试缓冲溢出分支一致，该分支返回 HTTP 507。当状态码包含在消息中时，DSH 已会归类为 SERVER；仅因状态码没有保留，恢复行为就发生了变化。

这里报告的是文本分类缺口，并非已确认远端使用哪一跳代理或其缓冲阈值。它应区别于既有 HTTP 413 / Failed to buffer the request body: length limit exceeded 请求正文大小错误。

最小修正建议

只扩展现有 SERVER 分支，保持所有更高优先级分类、重试次数和错误消息不变：

-  if (/\b5\d\d\b/.test(message)) return 'SERVER'
+  if (/\b5\d\d\b|exceeded request buffer limit while retrying upstream/i.test(message)) return 'SERVER'

不建议把所有 PI_AI_ERROR 加入默认重试集合，也不建议重新开启 SDK 内部重试或泛化匹配所有 buffer / request-too-large 消息。本建议不附回归测试补丁。

本地验证范围

已在安装的发布包上用模拟 pi-ai 终止事件复现旧分类与跳过重试的行为。通过窄范围本地兼容补丁将该消息映射为 SERVER 后，现有恢复插件会安排重试；后续成功、默认 5 次重试上限及取消行为均已验证。未对真实远端网关主动注入缓冲故障，未在官方源码树执行完整测试套件。

持续的上游故障仍可能在重试耗尽后结束；这项修正仅恢复已有的有界重试路径，不宣称消除远端容量限制。

相关分类缺口讨论：#8844、#3407。本报告聚焦没有状态码的上游重试缓冲错误。

[argszero]

Confirmed at source on origin/master, and the finding is wider than the one wording.

The chain, in order

packages/llm/llm-pi-ai/src/stream.ts::classifyPiAiError: 401|403 → quota → 429/rate-limit → 413 / Failed to buffer the request body: length limit exceeded / payload too large / request body too large → 400/invalid → 5xx → timeout → stream truncated → transport → PI_AI_ERROR.

Your message matches none of them: isQuotaExceededError (packages/llm/llm/src/error.ts:97) requires quota/balance/credit/budget wording, and /\b5\d\d\b/ needs the digits that were lost. So it lands on the catch-all, exactly as you measured — the assistant/attempt carries PI_AI_ERROR, DEFAULT_RETRYABLE_CODES does not, and dsh-llm-retry declines the step.

Note what the 413 branch is doing above the 5xx branch — its own comment:

A rejected request body (gateway or provider size cap): resending the same request cannot succeed, so it is invalid, not transient.

That is the opposite classification for a message sharing two words with yours, which is why your warning against generalising ("don't match every buffer / request-too-large message") is the load-bearing part of the fix and not a footnote.

Corroborated on pi-ai's side

dist/utils/retry.js in 0.87.1 lists the phrase verbatim in RETRYABLE_PROVIDER_ERROR_PATTERN, as you said. It is still there in 1.1.0 — which is the line packages/llm/llm-pi-ai/package.json on master actually pins ("@earendil-works/pi-ai": "^1.0.2"), so this is not a fix that arrived upstream while nobody looked.

The finding is wider than one phrase

I compared pi-ai's retryable pattern list against the classifier (transcribed with a guard that each regex source appears verbatim in the upstream file — 20/20 hold). Counting only pattern sources that are pure literals (no regex metacharacter, so the comparison is exact):

	0.87.1	1.1.0
literal retryable patterns	36	42
the classifier places them (code already retryable)	19	19
the classifier cannot place them → PI_AI_ERROR	17	23

The unplaceable set on the pinned line: overloaded, server_busy, servers are currently busy, currently experiencing high demand, model is at capacity, too many requests, Provider returned error, your phrase, upstream connect, reset before headers, getaddrinfo, ENOTFOUND, EAI_AGAIN, ended without, pending stream has been canceled, retry delay, you can retry your request, try your request again, please retry your request, ResourceExhausted, subscription_sharing_usage_unavailable, subscription_sharing_user_unavailable.

Caveats on that table, stated so the numbers are not read as more than they are: a few entries are fragments rather than whole messages (ended without), and where a source contains an optional character I rendered the readable sample by expanding it — so read the counts as pattern sources the classifier cannot place, not as distinct real-world messages. What the table does establish is the shape: roughly half of pi-ai's own retryable wording set is invisible to the harness's retry executor, and the phrase you hit is one member.

Why that is a bug and not a policy

The two halves are in the same repository and pull in opposite directions:

• packages/llm/llm-pi-ai/src/adapter.ts:140-141 — // The agent recovery layer owns visible attempts; one adapter call is one SDK attempt. → maxRetries: 0.
• packages/llm/llm-pi-ai/src/config.ts:380-383 refuses the field outright: maxRetries or maxRetryDelayMs, which were removed; compose agent recovery with dsh-llm-retry.
• packages/llm/llm/src/retry-policy.ts:19-25 — DEFAULT_RETRYABLE_CODES = [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT].

Recovery was deliberately moved off pi-ai's wording-driven retry and onto a name-driven policy — but the two sets are not the same set, and every wording above is a transient failure pi-ai would have retried and the harness will not. That is the argument against "the SDK just gave up": it was told to.

Plugin-form remedy, for deployments that cannot change the dependency

This family already has an asset: @argszero/cordis-plugin-empty-response-retry observes the public llm/stream waterfall and rewrites the failure.code of an unnamed failure so the retry executor accepts the step on its own unchanged code gate.

It does not cover your case, for two reasons worth separating:

• Its gate is the attempt produced nothing at all. A buffer failure while the upstream was being retried is a condition of the gateway, not of how much content came back — and the attempt can have started streaming.
• Its target is EMPTY_RESPONSE, which would assert "the model produced nothing" as the diagnosis. The honest name here is SERVER (the Envoy 507 branch you linked is a server-side transient), which is what your one-line widening writes too.

So I am adding a third recognition to that package: transientMessages → SERVER, only for the catch-all code, phrase-exact from pi-ai's own retryable table, with pi-ai's non-retryable quota/billing table as a veto and the classifier's 413 wording explicitly out of scope (a test pins that Failed to buffer the request body: length limit exceeded is never widened). That will be 0.3.0.

To be clear about what that is and is not: it is the same remedy you propose, applied at the one seam a plugin owns, for deployments that cannot patch classifyPiAiError — it is not a substitute for widening the SERVER branch, which remains a one-line change in stream.ts.

Honest boundary: I have not run your suite or the repository's tests, and I have not injected a real buffer overflow at a gateway. The evidence above is a source-level comparison plus pi-ai's own published tables, read from the installed distributions.

[argszero]

Following the analysis above, this gap now has a shipped plugin form — and the
plugin turned out to be the smaller half of the finding.

@argszero/cordis-plugin-empty-response-retry@0.3.0 — npm:
https://www.npmjs.com/package/@argszero/cordis-plugin-empty-response-retry —
source: https://github.com/argszero/cordis-plugin-empty-response-retry

plugins:
  empty-response-retry:
    module: '@argszero/cordis-plugin-empty-response-retry'

What the third report actually exposed

The proposal in the report is one more alternative in the SERVER rule, and the
reason the match must stay literal (the neighbouring 413 rule shares both words
with failed to buffer the request body: length limit exceeded and means the
opposite) is exactly right.

But the sentence in question is already in pi-ai's own retry table, and that is
the part worth generalizing. dsh-llm-pi-ai removed the provider-side retries
(maxRetries: 0 in the adapter) so the harness owns them; the harness's
DEFAULT_RETRYABLE_CODES is then a decision table, and pi-ai's
isRetryableAssistantError is another. The adapter's classifyPiAiError is a
second, partial transcription of the second one:

	pi-ai retryable alternatives	the chain places	it cannot place
0.87.1 (this report's version)	49	25	24
1.1.0	55	25	30

exceeded request buffer limit while retrying upstream is one row of that gap,
next to overloaded, service unavailable, too many requests, getaddrinfo,
ENOTFOUND, reset before headers and the rest. Every unplaceable wording takes
the catch-all, and the catch-all is the one code no retry table carries — so the
step is never repeated. (test/packaging.spec.mjs in the plugin holds this
measurement as an assertion against the installed pi-ai, so a future upstream
release that closes the gap shows up as a red test rather than as a stale
default.)

What the plugin does about it

A third recognition, in the same llm/stream seam as the earlier two: a failure
whose code is PI_AI_ERROR and whose message is a wording pi-ai's own table
retries is rewritten to SERVER — the name the chain would have written had the
wording carried the status number the gateway dropped. pi-ai's
NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN (quota, billing, subscription
limits) is consulted first, exactly as isRetryableAssistantError consults it,
so a limit that resets in hours is never repeated. Unlike the two earlier
recognitions it does not require the attempt to have produced nothing, because
SERVER is a claim about the route, not about output — and the harness's own
executor agrees: dsh-llm-retry gates on policy.retryableCodes.includes(code)
and nothing else, so a SERVER the adapter reports for a real 503 is repeated
whether or not a token arrived first.

The shipped default list is deliberately the server-shaped half of pi-ai's
table only; the transport-shaped (getaddrinfo, reset before headers,
websocket …) and throttle-shaped (too many requests, ResourceExhausted)
alternatives are left out, because SERVER would be the wrong name for them and
a wrong name in a durable log is the thing this plugin exists to stop writing.
transientMessages / transientTargetCode are the knobs for an operator who
wants them.

The honest limit of this form

This is a plugin, so it can only restore the decision at the boundary — it cannot
make the adapter read pi-ai's table. The core-shaped takeaway is that
classifyPiAiError (and mapStopReason) could consult the retryability judgement
the SDK already exposes instead of re-deriving a subset of it in a rule chain
that has since accumulated five separate wording additions (#4361, #6595, #7691,
#8321, #9352). The plugin is what a user can mount today; the direction is
upstream's.

Also addressed here, from the same seam: the empty-response case (#8321) and the
bodyless 400 status line (#9352) — one missing evidence, three reports.