llm-pi-ai should expose supportsDeveloperRole for custom OpenAI-compatible gateways

[Loner1024]

Summary

@deepseek-ai/dsh-llm-pi-ai cannot configure supportsDeveloperRole for a custom OpenAI-compatible gateway. For reasoning-capable models the adapter sends the system prompt with the developer role; several OpenAI-compatible gateways only accept system, so every request fails before reaching the model.

Environment

• @deepseek-ai/dsh: 0.1.0-rc.7
• @deepseek-ai/dsh-llm-pi-ai: 0.1.0-rc.7
• Adapter: llm-pi-ai, protocol openai-completions

Configuration used

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/api/v1
      reasoning: max
      models:
        - id: some-model
          reasoningEfforts:
            off:
            high: high
            max: max

Error

The gateway rejects the request with:

{
  "error": {
    "type": "invalid_request_error",
    "code": "400001",
    "message": "Failed to deserialize the JSON body into the target type: messages[0].role: unknown variant `developer`, expected one of `system`, `user`, `assistant`, `tool`, `latest_reminder`"
  }
}

Cause

pi-ai uses the developer role when model.reasoning && compat.supportsDeveloperRole. For an unrecognized custom base URL, supportsDeveloperRole defaults to true. The harness adapter's PiAiCompatProfile only exposes thinkingFormat and supportsReasoningEffort, so a profile cannot set compat.supportsDeveloperRole: false; the field is dropped by the config schema.

Suggested change

Expose supportsDeveloperRole (and ideally the remaining provider-neutral OpenAICompletionsCompat switches that affect request acceptance) in PiAiCompatProfile/compatProfile, with the same model → route → installed-catalog → URL-detection resolution order already used for thinkingFormat and supportsReasoningEffort.

Current local workaround

Patching the installed dsh-llm-pi-ai bundle to accept and forward supportsDeveloperRole fixes it immediately; the same change should live upstream so custom OpenAI-compatible gateways that only support system roles can use reasoning models without code patches.

[weijiafu14]

This can be worked around today without patching the installed Harness files or placing a role-rewrite proxy in front of the gateway.

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add <Pi provider package for the gateway>

pi2dsh registers a transport-carrying Pi provider as a native DSH LLM route through llm.registerAdapter. The request is assembled from the provider model descriptor, so its complete compat does not pass through PiAiCompatProfile.

A passthrough recorder verified the actual wire behavior: supportsDeveloperRole: false produced a system message, and the reasoning effort selected in DSH reached the provider stream. This is an alternate route, not a claim that the hand-declared settings schema is fixed.

[argszero]

Verified against rc.7 (99f6f02fec) — confirmed still unfixed at source, and this thread is the newest of a 10+ report cluster on the exact same gap. Converging them here so maintainers get one PR-sized picture.

1. Source confirmation (rc.7). PiAiCompatProfile (packages/llm/llm-pi-ai/src/catalog.ts:196-198, schema at config.ts:188-191) exposes exactly two compat fields: thinkingFormat and supportsReasoningEffort. resolveModelCompat (catalog.ts:388-419) passes through only those two (:395-396, :415-416); there is no supportsDeveloperRole anywhere in dsh-llm-pi-ai's source. pi-ai itself defaults supportsDeveloperRole = true for standard-looking OpenAI-compatible URLs (!isNonStandard && !isOpenRouter), so a reasoning model (model.reasoning = true) sends the system prompt with the developer role → gateways that only accept system 400 every request, exactly as your error shows (unknown variant 'developer'). The reasoning: max in your config makes it deterministic — every reasoning-capable call.

2. This cluster is 10+ threads, same root cause. #3076 / #2637 / #2587 / #1643 / #843 / #636 / #551 / #473 / #280 / #2489 / #2388 / #2023 / #2007 / #614 — all "custom OpenAI-compatible gateway rejects developer role / can't disable thinking via compat". That's a strong maintainer signal in itself.

3. A verified fix already exists — from the community. lidao2026-Coding's #551 reply contains a working-tree patch, tested end-to-end against a CodeBuddy/tencent compatibility gateway with deepseek-v4-flash: add supportsDeveloperRole: z.boolean() to compatProfile, thread it through resolveModelCompat (entry.compat?.supportsDeveloperRole ?? route?.supportsDeveloperRole, join the :395-397 early-return and the :399 non-openai guard, spread at :416), and set supportsDeveloperRole: false on the route's compat. Their before/after table is the cleanest evidence in the cluster: default URL-detection → developer role → gateway content_filter short-circuit with usage=0; explicit false → system role → normal stream. That's a PR-ready patch — the npx-cache-loss caveat they note is exactly why it needs to land upstream instead of staying a working-tree edit.

4. Immediate workarounds (until it lands):

• pi2dsh (weijiafu14, 自定义 OpenAI 兼容服务商无法使用 DeepSeek 思考强度：supportsDeveloperRole 被丢弃且 UI 缺少档位控件 #2637/llm-pi-ai: expose `supportsDeveloperRole` in `PiAiCompatProfile` (reasoning models break on endpoints that reject the `developer` role) #551): register the gateway's native Pi provider package as a DSH LLM adapter — provider-owned transport carries its own compat + thinking-level map, verified to send system with supportsDeveloperRole: false. This is the zero-patch path for gateways that have a Pi provider (LiteLLM, CodeBuddy, …).
• Or apply llm-pi-ai: expose `supportsDeveloperRole` in `PiAiCompatProfile` (reasoning models break on endpoints that reject the `developer` role) #551's patch to your installed lib/index.js (remember it's lost on npx cache refresh).

5. What the fix should look like upstream (one PR):

• Add supportsDeveloperRole?: boolean to PiAiCompatProfile + schema (config.ts:188-191), mirroring supportsReasoningEffort exactly.
• Thread it through resolveModelCompat (catalog.ts:395-397, :399, :416) — including the non-openai-completions guard (:399-402: it only exists on openai-completions, same as the siblings).
• Default nuance worth deciding: pi-ai's URL-detection default (true for standard-looking URLs) is what makes this explode silently on gateways that look standard. An explicit dsh-side default of undefined (inherit pi-ai) preserves current behavior for official/OpenRouter routes while letting every custom route opt out; alternatively route-level compat.supportsDeveloperRole: false as documented default for hand-declared custom gateways. llm-pi-ai: expose `supportsDeveloperRole` in `PiAiCompatProfile` (reasoning models break on endpoints that reject the `developer` role) #551's data shows false is the safe default for anything not verified-OpenAI.
• Regression test: feed the cluster's three verified samples (your unknown variant developer gateway, llm-pi-ai: expose `supportsDeveloperRole` in `PiAiCompatProfile` (reasoning models break on endpoints that reject the `developer` role) #551's CodeBuddy/tencent content_filter short-circuit, and an official-route control) asserting the request role flips developer→system when supportsDeveloperRole: false.

10+ reports, one root cause, verified patch, zero upstream movement on rc.7 — this is the highest-leverage small PR in the repo right now. Happy to consolidate the patch + tests if the contribution channel opens.