feat(llm-pi-ai): expose OpenAI-completions compat switches for hand-declared routes (branch ready)

[exposir]

Contribution: expose OpenAI-completions compat switches for hand-declared llm-pi-ai routes

This is a small, tested contribution waiting for a merge channel. PRs are currently disabled on this repository, so I'm posting it here — the branch is ready and can be opened as a PR the moment the repository accepts them.

Branch: exposir/deepseek-harness:feat/llm-pi-ai-compat-switches (3 commits, +101/−3, based on current master)

Problem

Hand-declared llm-pi-ai routes to OpenAI-completions gateways inherit compatibility behavior from pi-ai's baseURL-derived auto-detection, which only recognizes first-party endpoints. Two real gateways break because of this:

1. opencode zen (https://opencode.ai/zen/go/v1) enforces thinking replay: a later request whose thinking-mode assistant messages omit reasoning_content is rejected with INVALID_REQUEST. Auto-detection does not recognize the endpoint, so multi-turn requests fail.
2. Kimi coding API (https://api.kimi.com/coding/v1) rejects the developer message role and only accepts system. Auto-detection defaults supportsDeveloperRole to true for unknown gateways, so requests carrying a developer message fail.

Change

Expose the two existing OpenAICompletionsCompat switches through PiAiCompatProfile, mirroring the established thinkingFormat / supportsReasoningEffort pattern:

• requiresReasoningContentOnAssistantMessages
• supportsDeveloperRole

Semantics match the existing switches exactly: an entry-level value wins per field over the route-level value, an absent value keeps the catalog's own compat (then pi-ai's baseURL-derived guess), and setting the switch on a route whose api is not openai-completions fails loud.

Why configuration instead of extending auto-detection

Auto-detection can only enumerate first-party endpoints; third-party gateways with different replay/role conventions cannot be closed over. The config switch is the sustainable surface for hand-declared routes, consistent with the two compat switches already exposed.

Tests

• catalog.spec.ts: both switches reach every openai-completions model per route with entries winning per field; a thinking-replay switch on a non-completions protocol fails loud.
• config.spec.ts: both switches accept booleans and reject other values.

Verified with pnpm run gen-config-catalog / verify-config-catalog; the full llm-pi-ai catalog + config suites pass (63 tests). Happy to adapt anything per maintainer feedback.

[yannicksong0106]

Real-world validation of exactly this gap, from a deployment hitting it today:

Setup: hand-declared route amazon-bedrock (api: openai-completions, baseURL https://llmhost.net/v1, model deepseek-v4-flash) with reasoningEfforts declared (off/minimal/low/medium/high/max).

Symptom: once the model is reasoning-enabled, every request fails upstream with 400: unknown variant developer, expected one of system, user, assistant, tool, latest_reminder`` 鈥?the gateway proxies to an upstream that rejects the developer role. Root-cause chain: `model.reasoning = true` (from `reasoningEfforts`) + pi-ai`s `detectCompat` defaults `supportsDeveloperRole: true` for endpoints outside its special-case list, so `openai-completions.ts` maps the system message to `developer` (`useDeveloperRole = model.reasoning && compat.supportsDeveloperRole`). Catalog routes are fine because pi-ai`s catalog pins `supportsDeveloperRole: false` for the known gateways (e.g. opencode-go`s deepseek models); hand-declared routes have no way to opt out.

Interim local fix (until this lands upstream): patched dsh-llm-pi-ai so PiAiCompatProfile accepts supportsDeveloperRole and resolveModelCompat forwards it (schema + resolver + routeCompatDefined check + error message), then set compat: { supportsDeveloperRole: false } on the route. Verified: upstream now returns 200, reasoning_effort: max is accepted, and reasoning output comes back 鈥?same behavior as the catalog-pinned models.

This confirms the branchs premise: compat switches must be configurable on hand-declared routes. Please do include supportsDeveloperRolein the surface 鈥?and ideally the remainingOpenAICompletionsCompat fields too, so route authors dont hit the next dropped field. Happy to test the branch once a merge channel opens.

[weijiafu14]

先给 @yannicksong0106 一条今天就能解掉那个 400 的办法，然后说这对本提案意味着什么。

这两个开关在 rc.8 的 profile schema 里已经存在了

@yannicksong0106 被 unknown variant \developer`卡住的那条路，不需要等这个 PR：**在 settings 里给那个 model 声明compat.supportsDeveloperRole: false` 就能生效。**

llm-pi-ai:
  providers:
    amazon-bedrock:
      api: openai-completions
      baseURL: https://llmhost.net/v1
      apiKeyEnv: ...
      models:
        - id: deepseek-v4-flash
          reasoningEfforts: { off:, low: low, high: high }
          compat:
            supportsDeveloperRole: false     # ← 就是这一行

证据（不是读类型推的，是在真 DSH loop 上打到线上的）：我们有一个专门验这件事的 example，用的是透传录制代理——请求真发给上游、响应真流回来，中间只多存一份请求体。录到的 body 里 "role":"system" 而不是 "developer"，证明 supportsDeveloperRole: false 确实穿到了组装器。同一次还验了 max_tokens 这个非默认拼写、store 被去掉、以及推理档位的 wire 映射。

边界要说清：我验的是模型条目（entry）级的 compat。@exposir 提案里说的"entry-level 覆盖 route-level"我只验了 entry 那一半，route 级我没测过。对 @yannicksong0106 的场景来说 entry 级就够了。

对提案的意义：可能得先确认它还没被合掉

我这边有一条间接但挺硬的证据：我们做 DSH 的兼容层，需要把 Pi 侧的 compat 声明翻译成 DSH 的 profile 字段，为了防止上游加字段时我们悄悄漏掉，那张映射表钉了一个编译期门：

const DSH_COMPAT_FIELD_PROTOCOLS = {
  supportsDeveloperRole: COMPLETIONS_AND_RESPONSES,
  requiresReasoningContentOnAssistantMessages: COMPLETIONS,
  // …其余十几个
} satisfies Record<keyof PiAiCompatProfile, ReadonlySet<string>>

satisfies Record<keyof PiAiCompatProfile, …> 的含义是：PiAiCompatProfile 里每一个键都必须在这张表里出现。这段代码在我们仓库里编译通过（peer 解析到宿主装的那一代），也就是说 PiAiCompatProfile 上这两个键都已经存在了——否则这行 satisfies 会因为多出未知键而报错。

所以建议你先做一件很便宜的事：对着当前 rc.8 的 PiAiCompatProfile 确认一下这两个字段在不在。三种可能：

1. 已经合进去了（在你发帖之后）——那这帖可以结掉，顺手把上面那段配置贴给 @yannicksong0106 就是最大价值；
2. entry 级有了、route 级还没有——那你的提案还成立，但范围要收窄成"route 级继承"，篇幅小很多也更好评审；
3. 确实都还没有 —— 那说明我这边看到的是别的版本线，以你的核实为准。

不管是哪种，先确认再推进比带着一个可能已经过时的分支等 PR 通道划算。

顺带说一句：你"为什么用配置而不是扩展自动探测"那段是对的

Auto-detection can only enumerate first-party endpoints; third-party gateways with different replay/role conventions cannot be closed over.

这一点我们踩过并且立了内部规矩：翻译 provider 时显式写入 compat，不走 detectCompat 的名单——因为名单是枚举，而端点是无穷的。你这句话值得放在提案最前面，它把诉求从"多加两个开关"变成"探测这条路结构上封不住"，后者几乎无法反驳。

（@yannicksong0106 那条实测正好是这句话的注脚：目录路由没事是因为 pi-ai 的 catalog 给已知网关钉了 supportsDeveloperRole: false，手写路由落进了枚举之外。这是"名单永远追不上现实"的教科书案例，建议引进原帖。）

边界与利益相关

我们不修 DSH 自家组件——llm-pi-ai、PiAiCompatProfile、detectCompat 都在 DSH 里。

利益相关：我维护 pi2dsh（Pi 生态兼容层），上面那个录制代理和 example 是它的验收装置。这条不推销：第一节那段 YAML 是纯 DSH 官方配置，不需要装我们任何东西；我们只是因为要翻译这些字段，所以对它们在不在 schema 里格外敏感。