pi-ai adapter: third-party "server_error"/overload responses are not classified as SERVER and never retried

[YangZiCong2503416920]

Environment / 环境
DSH version: 0.1.0-rc.5 (commit 47f9438, 2026-08-13)
Surface: Web GUI (dsh web), agent run / model request
Provider path: third-party OpenAI-compatible API via pi-ai adapter (@deepseek-ai/dsh-llm-pi-ai)
Retry plugin: llm-retry present in base bundle (packages/bundle/base/cordis.patch.yml)

Describe the bug / 问题描述
第三方 provider 过载时返回标准错误体：
Error Code server_error: Our servers are currently overloaded. Please try again later.
DSH 直接显示“本轮运行失败”，一次重试都不发生；默认重试策略本应覆盖这类瞬时故障（SERVER/RATE_LIMIT/TIMEOUT/TRANSPORT），每次重试都立刻再次失败。

Steps to reproduce / 复现步骤
配置一个会返回 server_error/overload 文案（文本中无 5xx 数字）的第三方 OpenAI 兼容 provider
发送消息触发上游过载错误
观察：本轮立即失败，会话日志无 llm/retry 事件——完全没有退避重试

Expected / Actual
期望：归类为可重试 SERVER，按默认退避重试 2 次（500ms→10s，10% 抖动）后才失败
实际：首次请求即失败，直接把上游原文展示给用户

Root cause / 根因分析
pi-ai 将捕获异常扁平化为 error.message，丢失原始 Error/cause（stream.ts 已有注释），只能文本分类
classifyPiAiError 只把含 5xx 数字的文案（如 HTTP 500）归为 SERVER；server_error: ... 无数字 → 落入兜底 PI_AI_ERROR
PI_AI_ERROR 不在默认重试码白名单（packages/llm/llm/src/retry-policy.ts）→ llm-retry 直接放行 → 本轮以错误终结

Relevant code / 相关位置
packages/llm/llm-pi-ai/src/stream.ts（修复点）· packages/llm/llm-pi-ai/tests/convert.spec.ts · packages/llm/llm/src/retry-policy.ts · packages/llm/llm-retry/src/index.ts · packages/extensions/ui-cordis/src/client/locales.ts

[GCSimba]

Thanks @YangZiCong2503416920 for the report and the original diagnosis.

I reproduced this on master at 141eb6fef83422698aef7a981029e843e8161534. The reported provider text reaches pi-ai as a flattened errorMessage, but classifyPiAiError() recognizes numeric 5xx status text and not the explicit server_error marker. It therefore falls through to PI_AI_ERROR; the normal provider retry policy includes SERVER but deliberately excludes that catch-all.

I prepared a narrow patch that:

• maps a case-insensitive, word-bounded server_error marker to the existing SERVER code;
• preserves the higher-priority authentication, quota, rate-limit, and request-size classifications;
• keeps generic server prose and client_error in PI_AI_ERROR;
• adds the reported wording plus negative lookalikes to the adapter regression suite; and
• documents the classifier and retry-policy boundary in the package README and an Agent Note.

Fork commit: 736420c68e99ad690f1ccec4a81f00391f3d2825

Branch: codex/fix-pi-ai-server-error-classification

Validation:

• pnpm exec vitest run packages/llm/llm-pi-ai/tests/convert.spec.ts --coverage --coverage.include='packages/llm/llm-pi-ai/src/stream.ts' — 73/73 tests passed; stream.ts reached 100% statements, branches, functions, and lines.
• pnpm run build — passed.
• pnpm run lint — passed.
• pnpm run doc-sync — 27 of 28 checks passed; only the symlink verifier was blocked on this Windows checkout by EPERM while inspecting existing repository symlinks.
• Repository commit and pre-push hooks completed successfully.

The patch does not add PI_AI_ERROR to the retryable set, change error text or schemas, alter retry limits, or make direct ctx.llm.stream() calls multi-attempt. I left it as a fork commit because the project's contribution guide currently does not accept external pull requests.

AI-assisted repository audit and implementation; I reviewed the source, reproduced the failure, and ran every validation listed above. The commit records Codex <noreply@openai.com> as a co-author.

[denial123789]

I consolidated this into a source-backed operator runbook: https://sandbaseai.github.io/deepseek-harness-handbook/pi-ai-server-error-retry.html

One version-sensitive correction is useful for operators: at rc.8 (141eb6f), omitted provider policy resolves to five retries after the initial request, not two. The default eligible codes are EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, and TRANSPORT, with 500ms–10s bounded exponential backoff and 10% jitter. A textual server_error still falls through to PI_AI_ERROR, so those defaults never execute.

The guide separates four proofs: upstream transient evidence, ordered adapter classification, the selected route policy, and the durable executor. For one turn/step, llm/retry proves scheduling was appended before the wait, while the paired llm/retry-started proves another request actually began. A scheduled-only event can mean cancellation or disposal; no events can mean classification, policy, exhaustion, an excessive provider delay, or a direct ctx.llm.stream() call.

It also explains why adding the catch-all PI_AI_ERROR to retryableCodes is unsafe, and pins the narrow word-bounded source fix plus positive, negative, and precedence-collision tests.

Canonical guide: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/pi-ai-server-error-not-retried.md