[Bug/UX] Cannot add a new model to a multi-protocol catalog route (opencode) from the GUI — "needs an api" with no way to set it

[alanzhao0128]

[Bug/UX] Cannot add a new model to a multi-protocol catalog route (opencode) from the GUI — "needs an api" with no way to set it

Summary

On opencode (a pi-ai installed-catalog provider), fetching the model list from the GUI returns only the models in pi-ai's static catalog snapshot, not the live GET /models result. New models opencode ships after the snapshot (e.g. x-preview-f-free, gemini-3.7-flash, grok-4.6, kimi-k3, …) never appear.

Trying to add such a model by hand in the GUI fails with:

llm-pi-ai: provider "opencode" model "x-preview-f-free" needs an api;
the installed catalog does not describe it, so set the route's api
to the wire protocol its endpoint speaks

…but the GUI offers no way to set an api for that model: the add-provider form collects only the API key and a base URL (no protocol field), and on a catalog route there is no route-level protocol control either. api is route-level only, not per-model. So the action the GUI exposes (add a model) is un-completable for any model outside the snapshot on a multi-protocol catalog route — the only workaround is hand-editing settings.yaml.

Repro

1. Settings → Models → add provider opencode (the form only asks for the API key and a base URL).
2. "Fetch available models" → lists 58 models (the pi-ai snapshot), while curl https://opencode.ai/zen/v1/models returns 64.
3. In the live list but absent from the snapshot (so missing from the GUI):
   gemini-3.7-flash, gpt-5.3-codex-spark, grok-4.6, hy3-free, kimi-k3, muse-spark-1.2, muse-spark-1.2-contributor-free, nemotron-3.5-lightning-free, x-preview-f-free
4. Manually adding x-preview-f-free in the GUI → the needs an api error above.

Root cause (three layers)

1. Snapshot vs live: llm-pi-ai answers a catalog route's model list from the installed pi-ai snapshot with no network call (by design — it carries contextWindow/price/thinking metadata the listing endpoint does not provide). The snapshot lags the live /models.

2. api is route-level, not model-level: PiAiModelProfile has no api field; only PiAiProviderProfile.api exists. For a catalog route the GUI deliberately does not offer a route-level protocol ("a catalog route's models each carry theirs, so a route-level protocol there could only override every one of them"). opencode is exactly such a multi-protocol catalog — its snapshot spans anthropic-messages, google-generative-ai, openai-completions, and openai-responses.

3. The live endpoint does not disclose the protocol: opencode's GET /models returns only {id, object, created, owned_by} — no protocol/modality info. So even fetching the live list would not let the harness infer which wire protocol x-preview-f-free speaks.

Net effect: a new model on a multi-protocol catalog route is un-addable from the GUI and requires hand-editing settings.yaml.

Suggested fixes (any combination)

• GUI: in the model editor for a catalog route, expose an api (protocol) selector for a model the catalog does not describe — or let the add-model flow accept a protocol choice.
• Harness config: allow a per-model api override on a model entry, or an explicit "hand-declared extra model" list on a catalog route that carries its own protocol.
• Endpoint (upstream opencode): have /models return protocol/modality metadata per model, so a live fetch could route a new model correctly.
• Alternatively: refresh the snapshot on a schedule, and surface "new models from the live listing need a protocol — pick one" in the GUI instead of failing the write.

Environment

• @deepseek-ai/dsh 0.1.0-rc.7, @deepseek-ai/dsh-llm-pi-ai 0.1.0-rc.8
• @earendil-works/pi-ai 0.82.1
• Provider opencode, base URL https://opencode.ai/zen/v1 (form collects key + base URL only, no per-model protocol)

[danslamer]

Same wall here, and worth noting it is not only a GUI gap: the profile schema itself cannot express a per-model protocol. dsh-llm-pi-ai's modelFields is { name, contextWindow, maxTokens, input, reasoningEfforts, compat } — api exists only at the route level — and resolution is

const api = request.api ?? base?.api ?? routeApi;   // lib/index.js:666

where routeApi = sharedCatalogApi(installed catalog) is only defined when every catalog model of that route shares one protocol (lib/index.js:540). For opencode / opencode-go the catalog spans anthropic-messages + openai-completions + openai-responses, so a model the installed snapshot has not caught up with has nothing to resolve and is refused — hand-editing settings.yaml cannot fix it either, which matches what the GUI shows.

Declaring the protocol at the route level, as the error message suggests, is destructive on such a route: request.api wins for every model on it, so api: openai-completions silently repoints minimax-m3 / qwen3.8-flash (anthropic-messages, catalog baseUrl https://opencode.ai/zen/go) to POST https://opencode.ai/zen/go/chat/completions instead of /v1/messages, and does the same to the openai-responses models (grok-4.6, gpt-5.6-luna, muse-spark-*). One added model breaks the other 20+ on the route.

Declaring a second route (e.g. opencode-go-v41) with its own api/baseURL is the only thing that works today, but the provider route id is the key for accounting, settings and references, so it scatters them: the usage ledger recorded the same model under two provider buckets (opencode-go-v41/deepseek-v4.1-flash: 21 calls / 177k input tokens, separate from opencode-go/*), and an OpenCode Go plan probe that matches the provider id exactly (@linxin666/dsh-usage, ids: ['opencode-go']) shows no quota row for the new route even though the quota is account-level.

Proposal — add an optional per-model api (and optionally baseURL), keeping everything else as is:

const api = entry.api ?? request.api ?? base?.api ?? routeApi;
const baseUrl = entry.baseURL ?? request.baseURL ?? base?.baseUrl ?? providerBaseUrl;

• validation stays supportedProtocols() (openai-completions / openai-responses / anthropic-messages), and the existing per-model compat check already validates against the resolved protocol;
• a route-level api remains the fallback, so single-protocol routes behave exactly as today;
• optionally warn when a route-level api would override catalog models whose own protocol differs — that is the path the current error message steers users onto;
• optionally surface the field in the Models editor for rows whose model is not in the installed catalog (today the "API 协议" select renders only for hand-declared routes, since ownsIdentity = family === "pi-ai" && props.declared === true).

Concrete trigger, if a reproduction is useful: opencode-go + OpenCode Go's deepseek-v4.1-flash before the pi-ai snapshot catches up — the profile is rejected with 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.