llm-pi-ai: a mixed-protocol catalog route cannot serve a model the installed catalog has not shipped

[24kHandsome1201]

What happens

Configuring an installed-catalog route with a model id the bundled catalog does not carry is rejected:

llm-pi-ai: provider "opencode-go" model "deepseek-v4.1-flash" needs an api;
the installed catalog does not describe it, so set the route's api to the wire
protocol its endpoint speaks

Concrete case: opencode-go + deepseek-v4.1-flash. The model exists upstream (https://opencode.ai/zen/go/v1/models lists it), but @earendil-works/pi-ai@0.85.1's bundled dist/providers/data/opencode-go.json ships only deepseek-v4-flash, deepseek-v4-flash-vision-exp, deepseek-v4-pro.

Why

Resolution has three sources of a wire protocol, and all three are empty here (packages/llm/llm-pi-ai/src/catalog.ts):

const api = request.api ?? base?.api ?? routeApi            // :888
if (api === undefined) invalid(provider, '...needs an api...')  // :889

• request.api — not configured;
• base?.api — the catalog has no entry with this id;
• routeApi — sharedCatalogApi() (:659) returns the protocol only when the route's shipped models agree, and opencode-go spans three (anthropic-messages, openai-completions, openai-responses), so it returns undefined.

The part I think is a real gap

Following the error's advice (set the route's api) is not side-effect-free on a mixed route:

1. models replaces the route's catalog wholesale (:868);
2. modelOverrides refuses ids the catalog does not describe (:853);
3. a models entry has no api field (src/config.ts:299);
4. request.api outranks each entry's base?.api (:888), and setting it also switches the route off the catalog provider onto the protocol table (src/provider.ts:172).

So on a mixed-protocol catalog route there is no configuration that serves the new model and keeps the sibling models on their own protocols. The only working shape is a second route:

llm-pi-ai:
  providers:
    opencode-go:                # unchanged, keeps the 30 shipped models
      apiKeyEnv: OPENCODE_GO_API_KEY
    opencode-go-deepseek:       # the undescribed id, on its own route
      apiKeyEnv: OPENCODE_GO_API_KEY
      api: openai-completions
      baseURL: https://opencode.ai/zen/go/v1
      models:
        - id: deepseek-v4.1-flash
          contextWindow: 1000000
          maxTokens: 384000
          input: [text, image]

This also contradicts the intent recorded at catalog.ts:653 ("add a model the installed catalog has not caught up with ... without restating the protocol its siblings already use"), which holds only for single-protocol routes. opencode is affected the same way, so this is not specific to one provider.

Suggested fixes

1. Allow api on a models entry (entry.api ?? request.api ?? base?.api ?? routeApi). Most-specific-wins matches how compat already layers per model over the route. Purely additive.
2. Fix the diagnostic. When routeApi is undefined because the route is mixed, say so and point at the second-route workaround instead of set the route's api, which narrows every sibling model.

Not urgent for me — a second route works — but the current error leads users to the destructive option first.

---

中文版

配置内置目录路由时，若模型 id 不在打包的目录里，会被拒绝：

llm-pi-ai: provider "opencode-go" model "deepseek-v4.1-flash" needs an api;
the installed catalog does not describe it, so set the route's api to the wire
protocol its endpoint speaks

具体场景：opencode-go + deepseek-v4.1-flash。该模型上游确实存在（https://opencode.ai/zen/go/v1/models 里有），但 @earendil-works/pi-ai@0.85.1 打包的 dist/providers/data/opencode-go.json 只有 deepseek-v4-flash、deepseek-v4-flash-vision-exp、deepseek-v4-pro。

原因。 协议只有三个来源（packages/llm/llm-pi-ai/src/catalog.ts:888），此处三者全空：路由未配 api；目录无同 id 条目；sharedCatalogApi()（:659）仅在该路由所有内置模型协议一致时才返回协议，而 opencode-go 横跨三种协议，故返回 undefined。

我认为真正的缺口。 按报错提示去设置路由 api 在混合协议路由上有副作用：models 会整体替换目录（:868）；modelOverrides 拒绝目录未收录的 id（:853）；models 条目没有 api 字段（src/config.ts:299）；而 request.api 优先级高于每个条目的 base?.api（:888），设置后该路由还会从 catalog provider 切到协议表重建（src/provider.ts:172）。

因此在混合协议路由上，不存在既能服务新模型、又能保住兄弟模型原生协议的配置，只能另开一条路由（示例见上）。这与 catalog.ts:653 注释宣称的意图相矛盾——那句话只在单协议路由上成立。opencode 同样受影响。

建议修法。 ①允许 models 条目声明 api（最具体者优先，与 compat 的按模型覆盖语义一致，纯增量）；②改进报错文案：当 routeApi 因混合协议而为 undefined 时明说，并指向「另开路由」这一无副作用方案。

对我而言不紧急（另开路由可用），但现有报错会先把人引向有副作用的那条路。

---

Environment. @deepseek-ai/dsh 0.1.5-rc.2, @earendil-works/pi-ai 0.85.1 (npm latest), macOS; code references from ddefc45 (2026-09-17). Verified upstream: GET https://opencode.ai/zen/go/v1/models lists deepseek-v4.1-flash.

[24kHandsome1201]

Update (after checking pi's main). Part of this is likely to be resolved by the next @earendil-works/pi-ai release, so let me be precise about what remains.

pi's Unreleased changelog carries two relevant entries: OpenCode / OpenCode Go now send x-opencode-session from sessionId across all adapters (#9326), and the DeepSeek catalog was corrected for V4.1 Flash (#9423). The generated opencode-go data is not committed to that repo, so I cannot confirm from source whether the next release also carries deepseek-v4.1-flash for this route — but since the registry lists it, this specific id may simply start resolving after a version bump, with no configuration.

That would remove this report's trigger, not its subject. The next model a provider publishes — or the next id whose spelling differs from the bundled catalog — hits the same wall, and the error's suggested remedy is still the destructive one. Both suggestions above are about that path, not about this one model.