Make pi-ai's inferred supportsDeveloperRole configurable on hand-declared llm-pi-ai routes

[lyccol]

CONTRIBUTING.md says external pull requests cannot be accepted right now, so this is filed here instead. A working patch exists on a fork if it is useful; otherwise the report alone should be enough to reproduce.

The gap

llm-pi-ai lets a profile configure compat.thinkingFormat and compat.supportsReasoningEffort for a hand-declared route, but not the third switch pi-ai infers the same way. In @earendil-works/pi-ai, openai-completions.js:1148 computes:

supportsDeveloperRole: isOpenRouterDeveloperRoleModel || (!isNonStandard && !isOpenRouter)

isNonStandard matches only a short host list (nvidia, cerebras, xai, together, chutes, deepseek.com, zai, moonshot, opencode, cloudflare, ant-ling). A private gateway is never on it, so the switch infers true, and openai-completions.js:787-788 then sends the system prompt under the developer message role for any model whose descriptor has reasoning.

An OpenAI-compatible gateway whose backend accepts only user/assistant — a Bedrock-fronting corporate gateway, for one — therefore rejects every request with Unexpected role "developer" as soon as a model on that route declares any reasoningEfforts. The only way to keep the route usable today is reasoningEfforts: false, which forfeits all selectable thinking levels for a reason unrelated to what the model can do: the same gateway accepts reasoning_effort, and accepts it alongside function tools.

Worth noting for anyone trying to reproduce: a curl probe against such a gateway passes. The role is chosen inside pi-ai from the model's reasoning flag and the endpoint URL, not by any field in a hand-written request, so only an assembled run shows the failure.

The patch

A third switch, supportsDeveloperRole, on PiAiCompatProfile, resolving on exactly the path the two existing switches use — model entry → route → installed catalog entry → pi-ai's URL-derived guess — and under the same openai-completions-only rule. false keeps system prompts on system.

The rest of pi-ai's compat surface (supportsStore, maxTokensField, …) stays auto-detected and unconfigurable, per the evidence bar in packages/AGENTS.md: a switch is exposed only where a private gateway's URL provably misleads the inference.

One vocabulary change comes with it. The block holds compat switches, not "reasoning-dispatch switches" — a message role is not reasoning dispatch — so the two rejection diagnostics now say compat switches instead of enumerating field names, and definesCompatSwitch collapses the condition that the model-level and route-level refusals each spelled out separately. Those two diagnostic strings change text; they are load-time only, with no wire or durable role.

Touched: packages/llm/llm-pi-ai/src/catalog.ts, src/config.ts, tests/catalog.spec.ts, tests/adapter.spec.ts, both READMEs, regenerated docs/config-catalog{,.zh}.md plus i18n pairing records, and an Agent Note triplet at .agents/notes/implemented/feature/2026-08-14-pi-ai-developer-role-compat-switch.md.

Verification: vitest run packages/llm/llm-pi-ai (215 passing), 100% statements/branches/functions/lines for the package, typecheck, lint, and doc-sync (28/28). The adapter tests pin both wire outcomes against the mock server — pi-ai's inferred developer role on an unrecognized host, and system under supportsDeveloperRole: false while reasoning_effort still goes out — so the switch is proven not to be a no-op. Full test:coverage and the snapshot suite were not run: the adapter mounts dormant in shipped compositions, so compat is off the default path.

Real-gateway check: with the route declaring six reasoningEfforts levels for a reasoning model, a headless task with a bash tool call at reasoningEffort: high succeeded — the exact combination that previously failed on Unexpected role "developer". That gateway is on a private network, so it cannot back a CI assertion and no e2e test claims it.

Branch: https://github.com/lyccol/deepseek-harness/tree/feat/pi-ai-developer-role-compat
Diff against master: master...lyccol:feat/pi-ai-developer-role-compat

Take it, rewrite it, or ignore it — the report is the part that matters.

---

中文

CONTRIBUTING.md 写明目前不接受外部 PR,故发在这里。补丁已在 fork 上,可用则取,不可用的话仅凭上面的复现说明也足够。

问题:llm-pi-ai 允许手工声明的路由配置 compat.thinkingFormat 与 compat.supportsReasoningEffort,但 pi-ai 以同样方式推断的第三个开关不可配置。openai-completions.js:1148 对不在其非标准主机名单(nvidia、cerebras、xai、together、deepseek.com 等)内的主机一律推断 supportsDeveloperRole: true,于是 :787-788 会把任何具备 reasoning 的模型的系统提示放到 developer 角色下发送。私有网关永远不在名单里,因此一个与 OpenAI 兼容、但后端只允许 user/assistant 的网关(例如前置 Bedrock 的公司网关),只要路由上的模型声明了任何 reasoningEfforts,每次请求都会以 Unexpected role "developer" 被拒。当前唯一可用姿态是 reasoningEfforts: false——为一个与模型能力无关的原因放弃全部可选思考档位,而该网关本身既接受 reasoning_effort,也接受它与 function tools 同时出现。用 curl 探测会通过:角色是 pi-ai 依据模型 reasoning 标志与 URL 在内部选定的,只有装配完成的真实运行才暴露。

补丁:PiAiCompatProfile 增加 supportsDeveloperRole,解析顺序与前两个开关完全一致(模型条目 → 路由 → 已安装 catalog 条目 → pi-ai 按 URL 的猜测),同受「仅 openai-completions」约束;compat 面其余部分保持自动检测且仍不开放,符合 packages/AGENTS.md 的证据门槛。随之把该块措辞从「reasoning-dispatch switches」泛化为「compat switches」(消息角色不属于推理分派),两条加载期诊断不再逐个列出字段名,definesCompatSwitch 收拢了模型级与路由级此前各写一遍的同一条件。

按分类,这在上游应是 kind/feature + area/llm。

🤖 Generated with Claude Code

[Electricitysheep]

让推断的 supportsDeveloperRole 可配置很合理——手写 provider 路由时开发者应该能显式声明，而不是靠推断。

developer role 兼容问题我们 FAQ 记录过（#280/#614 同族：网关不认 developer role 时配 compat.supportsDeveloperRole: false）：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/faq.md

[lyccol]

谢谢线索。顺着 FAQ 里的编号往下看之后,我得更正自己开帖时的说法——这件事社区已经有人做过,而且早于本帖,在先的工作应该记在他们名下:

• [BUG] llm-pi-ai 应支持配置 compat.supportsDeveloperRole #280(8-13,7 赞)是这件事最早、最对题的诉求帖,同一个根因,场景比我这份更宽(火山 Coding Plan、newapi/Opencode Go,以及 DashScope 百炼官方 OpenAI 兼容端点——所以受影响的不只是私有网关,我开帖时把影响面写窄了)。本帖应视为它的补充,而不是另起一个诉求。
• 任意第三方 OpenAI 兼容网关在 DeepSeek Harness 中开箱即用：思考强度自动测定 + 方言自动修复（附插件与增强 fork） #559 公布的 Menger-8/deepseek-harness(分支 feature/third-party-gateway-compat,8-14 00:04Z)已经把 compat 面从 2 个开关扩到 9 个,并且不止于配置:添加模型时用最小请求实测每个模型的档位、系统角色、推理方言与输出上限字段并自动写入,外加按主机名钉住实测事实的 dsh-gateway-presets 插件。就 supportsDeveloperRole 而言,本帖的补丁是其严格子集。
• 0reki/deepseek-harness-desktop 也带这个字段,但默认值不同:手工声明的模型默认 false。这其实是个真问题——手工声明的路由是否还应该继承 pi-ai 按 URL 得出的猜测。本帖选的是"不改默认、必须显式声明",任意第三方 OpenAI 兼容网关在 DeepSeek Harness 中开箱即用：思考强度自动测定 + 方言自动修复（附插件与增强 fork） #559 选的是"不要猜,去实测",两者的取舍值得维护者一并看。

那本帖还剩什么:形态。它只加一个开关而非九个,理由按 packages/AGENTS.md 对公开配置字段的证据门槛给出(仅当私有网关的 URL 确实误导推断时才开放),诊断留在加载期,并带包内每文件 100% 覆盖、双语 README、docs/config-catalog 重出与 Agent Note。也就是一份按上游自己的规矩写好的最小补丁,而那两个 fork 是产品。哪种更合口味由维护者定。

另外一个善意提醒:那份 FAQ 目前写的"网关不认 developer role 时配 compat.supportsDeveloperRole: false"在上游还配不出效果——该字段尚未存在(在 deepseek-ai/deepseek-harness 里搜 supportsDeveloperRole 返回 0 条),#614 问"正确格式是什么"大概正是撞在这里。建议标注一下"需 fork 或等上游合入",可以少几个同类提问。

---

Correcting my own opening post: this was done in the community before I filed it, and the credit belongs upstream of this thread. #280 (2026-08-13, 7 upvotes) is the earlier and better-scoped request — its reports cover Volcano Coding Plan, newapi/Opencode Go, and DashScope's official OpenAI-compatible endpoint, so the blast radius is wider than the "private gateway" framing I used. Menger-8/deepseek-harness (branch feature/third-party-gateway-compat, announced in #559, 2026-08-14T00:04Z) already extends the compat surface from 2 switches to 9 and adds per-model endpoint probing plus a hostname-keyed presets plugin; on supportsDeveloperRole this patch is a strict subset of it. 0reki/deepseek-harness-desktop carries the same field but defaults hand-declared models to false — a genuine design split worth deciding deliberately: keep pi-ai's URL-derived guess and require an explicit opt-out (this patch), flip the default for hand-declared routes (that fork), or stop guessing and measure (#559).

What remains here is shape: one switch rather than nine, justified against the evidence bar packages/AGENTS.md sets for public configuration fields, diagnostics kept at load time, with per-file 100% coverage, bilingual READMEs, a regenerated docs/config-catalog, and an Agent Note. Maintainers' call which shape they want.