dsh-opencode-go-catalog

A live-maintained OpenCode Go model catalog for DeepSeek Harness
(DSH). Membership is rebuilt from the live roster plus the docs endpoint table on every sync — new
models appear, retired ones drop out, no hand work. A curated snapshot stays as the offline fallback.

Status: 0.2.0 · auto membership · 33 models live (2026-10-13), incl. Cat Jam Free (cat-jam-free)

Contents

• Why
• How it works
• Installation
• Configuration
• Commands & scripts
• Fresh reasoning efforts
• The protocol oracle
• Maintaining the catalog
• Enable / disable
• Troubleshooting
• Security
• Compatibility
• License & sources

Why

The built-in opencode-go route of @deepseek-ai/dsh-llm-pi-ai serves a static catalog shipped in
@earendil-works/pi-ai (30 models at the time of writing) that never refreshes itself — new models
like Step 5 or Cat Jam are missing until upstream bumps the dependency. See
Discussion #3957.

This plugin never touches the built-in route. It manages three sibling routes through the
official settings.mutate seam:

The split is mandatory, not stylistic: some Go models are Responses-only (a chat-completions
request answers with a bare 500 or 401 "not supported for format oa-compat"), others are
Messages-only. One route = one protocol.

Why not put the extra models on the built-in route? Source-verified against dsh-llm-pi-ai:
resolveRouteModels computes a model's protocol as request.api ?? base?.api ?? routeApi — an
api field on a model entry is never read. A model the shipped catalog does not describe
therefore needs the route-level api, and setting that routes opencode-go through
createProvider() over a single protocol (the catalog provider is only reused while
spec.api === undefined), losing both the three-protocol dispatch and pi-ai's session-header
wrapper. On top of that, any models list replaces the served catalog. The built-in route stays
untouched.

How it works

1. Registry — https://models.opencode.ai/api.json (keyless, ETag cache + last-good fallback)
   supplies name, limits, input modalities, and reasoning_options per model.
2. Roster — https://opencode.ai/zen/go/v1/models (keyless) says which IDs exist right now.
3. Protocol oracle — https://opencode.ai/docs/go/ (since 2026-10-19 redirecting to
   /v2/docs/console/go/) carries an endpoint table per model ID in either path shape
   (…/go/v1/chat/completions or …/go//v1/chat/completions, plus /responses and
   /messages). See The protocol oracle.
4. Membership is then roster ∩ registry ∩ protocol-known, minus the veto list. On startup, on an
   interval (default 4 h), and on /opencode-go-sync the three sibling routes are written via
   settings.mutate.
5. Fail-safe. The auto mode refuses to write, and the curated snapshot in catalog/models.json
   is served unchanged, when
   - the roster or the oracle is unavailable (network, docs redesign), or
   - fewer than minAutoModels models resolve, or
   - fewer than minAutoRatio (default 60 %) of the last adopted set resolve — this catches a
   degraded source that would otherwise quietly empty half the picker and stamp the missing IDs
   as retired.

A single route that comes out empty is not fatal either: llm-pi-ai rejects a route with
resolves no models, and because all three routes go into one settings.mutate, one empty group
would block the healthy groups too — so that route is served from the snapshot and reported in
status.json (auto.snapshotRoutes). A network outage or a docs redesign can therefore never
empty the picker. Missing capacities are never invented — the field is omitted and needsReview
is reported, so llm-pi-ai applies its own route defaults (262144 / 32768).
6. The module never throws during boot, never edits node_modules, and never reads or writes
credentials (it only references the OPENCODE_GO_API_KEY name, same as the built-in route).

Hand-added models do not survive. settings.mutate persists into the profile's
cordis.patch.yml, and each sibling route is written as one whole object. A model you add by hand
(or via Settings → Models → Fetch available models → Add model) inside one of these three routes
is gone at the next sync — startup, interval, or /opencode-go-sync. Durable entries belong in the
snapshot (node bin/sync.mjs --adopt) or in the veto list.

Installation

Prerequisites: DSH running, an OpenCode Go subscription with a working key
(OPENCODE_GO_API_KEY already configured — if the built-in opencode-go route works, you are set).

Via Plugin Market (once listed): Settings → Plugin Market → search
dsh-opencode-go-catalog → one-click install → restart → open the model picker.
Expect three new groups (OpenCode Go extras / responses / messages) next to the built-in one.

Manual: copy this folder to /node_modules/dsh-opencode-go-catalog, add
"dsh-opencode-go-catalog" to dsh.profile.bundles in the profile package.json (keep a backup
first), restart DSH.

Without the plugin (static, no auto-refresh): generate the snippet and replace your
llm-pi-ai row with it — see INSTALL.md and weg-a-schnellstart.yml:

node bin/snippet.mjs > snippet.yml

Configuration

Bundle row (cordis.patch.yml, replaces the whole row — no deep merge):

- id: opencode-go-catalog
name: dsh-opencode-go-catalog
config:
enabled: true            # false → sibling routes are removed again
autoMembership: true     # false → curated snapshot only, no roster/oracle
minAutoModels: 8         # safety belt: below this the snapshot is served
minProtocolRows: 10      # safety belt against a docs redesign
minAutoRatio: 0.6        # safety belt against a degraded (not dead) source; 0 disables it
refreshReasoning: true   # false → snapshot values only, no network (this also disables auto mode)
sessionHeaderValue: 'dsh-opencode-go-catalog'  # false → no static session header (400 risk)
intervalMinutes: 240     # 0 → startup only
startupDelaySeconds: 10
refreshTimeoutMs: 120000
catalogPath: ./catalog/models.json
managedRoutes:
- opencode-go-extras
- opencode-go-responses
- opencode-go-messages

Commands & scripts

Fresh reasoning efforts

reasoning_options in the live registry are structured (effort values, toggle, budget_tokens)
— Models.dev serves the same data. Mapping rules (lib/reasoning.mjs):

Live examples: Cat Jam Free → {low, medium, high, xhigh, max}; GPT-5.6 Luna →
{off: none, low…max}; Muse Spark → {minimal…xhigh} (no max!); LongCat-2.0 /
MiniMax M3 (toggle-only) → no menu.

The protocol oracle

No JSON endpoint discloses the wire endpoint per model, but the registry names the lane per
model in the top-level opencode-go section, models[].provider.api
(…/inference/go/openai/v1, …/inference/go/anthropic/v1 or …/inference/go/google/v1beta;
33/33 entries on 2026-10-19, 0 contradictions with the table below). The lane settles anthropic and
google on its own but is ambiguous inside the OpenAI lane (chat/completions vs responses), so
the docs table stays the oracle for that split. Using the lane as a second, path-independent oracle
is tracked in #10.

lib/protocols.mjs parses the table (htmlToText + one row regex) and filters every hit against
the live roster, so a regex false positive can never invent a model ID. The row regex anchors on a
Go inference path, not a host, and accepts both documented URL shapes. It also reads the SDK
column (@ai-sdk/openai-compatible / openai / anthropic) as a cross-check: @ai-sdk/openai
serves both OpenAI endpoints, so only a statement that excludes the parsed endpoint counts as a
contradiction — then that ID leaves the oracle and is reported under auto.conflicts. An unknown
endpoint suffix is never rescued by the SDK column: a new endpoint type (e.g. /embeddings) must not
land in a chat route. An ID without a table row is not guessed — it is reported as unresolved
in status.json and stays out. Current examples: qwen3.6-plus, qwen3.7-max, glm-5.1,
omen-alpha, gemini-4-argon-contributor (live, undocumented).

Row dropped from the docs (carry-over, 2026-10-19). The v2 table no longer lists every live ID
(minimax-m2.7 is the example). For such an ID the protocol already verified in the snapshot applies
again — no heuristic, but second-hand, so it is reported under auto.carried. The committed snapshot
is the evidence source on purpose; the cache keeps only rows a live read actually produced. A rejected
ID is excluded from the carry-over as well: a contradiction is not a gap.

Silent-staleness guard. If the page stops yielding at least minProtocolRows rows, the last-good
cached table is used and auto.degraded is set with auto.degradedReason: "shape"; the host logs a
warning naming the redirect target, because in this state new Go models silently stay out of the
picker. This is exactly what happened between the v2 docs redesign (/go/v1/… →
/go//v1/…) and the regex fix on 2026-10-19. A network failure keeps the same cache but is
reported as degradedReason: "network" — it is not a docs-format problem. A row that contradicts
another row for the same ID takes that ID out of the oracle entirely (keeping the first would be a
guess) and is reported under auto.conflicts in status.json.

Maintaining the catalog

Normally nothing: the auto mode is the maintenance. The snapshot only needs attention when you want
to pin something or keep the fallback current:

1. node bin/sync.mjs --auto — see what the live sources currently produce.
2. node bin/sync.mjs --adopt — take the live membership into catalog/models.json (also moves
   vanished IDs into retired). Run it after a model appears or disappears, so an offline start
   serves the same list.
3. To keep a live model out of the picker, list it in excluded with a reason.
4. node verify.mjs → /opencode-go-sync.

Enable / disable

• Siblings off, plugin stays loaded: add your own - id: opencode-go-catalog row
  (with the FULL config — patches replace, never merge; copy
  cordis.patch.yml as the template) to your profile patch with
  enabled: false. The three routes are removed again via unset ops; the built-in
  opencode-go route keeps running untouched.
• Auto mode off, curated snapshot on: autoMembership: false.
• Whole plugin off: disabled: true on the bundle row (or the market's disable
  list), restart. Nothing needs deleting.

Session header (MissingSessionID-400)

OpenCode Go requires x-opencode-session (stable per-conversation ID) since 09/05 —
see Discussion #5495.

Refined 2026-10-13, source-verified: dsh-llm-pi-ai does forward a per-conversation id
(…options.sessionId === void 0 ? {} : { sessionId: String(options.sessionId) }), and pi-ai's
catalog provider wraps its APIs with withOpenCodeSessionHeader, which reads exactly that
sessionId. The gap is narrower than "the adapter has no sessionHeader": hand-declared routes
never pass through that wrapper, because createProvider calls the raw protocol factory. So a
sibling route still needs the static header below.

Until a declared route can opt into the wrapper, this plugin sets a static header on every
sibling route (sessionHeaderValue, default 'dsh-opencode-go-catalog', off with false).
Trade-off, stated plainly: one fixed ID across all conversations means fewer cache hits — slower and
pricier than a proper per-conversation ID (user-verified). It beats a hard 400. The built-in
opencode-go route is never touched (it gets the real per-conversation header from pi-ai itself).
Upstream: earendil-works/pi#9326 — the ask is "apply withOpenCodeSessionHeader to declared
routes too", not "add sessionId to the adapter".

Diagnostics

After every sync attempt the plugin writes status.json next to package.json (time, ok, via,
changed, command, fetch, error, and for auto mode: roster/protocols source, members,
perRoute, added, removed, unresolved, vetoed, needsReview). Open it in any editor — no
log access needed. If the picker stays empty, send this file's content with your report.

Troubleshooting

Never hand-edit node_modules/…/pi-ai/dist/providers/data/opencode-go.json — the next DSH
update discards it silently. This snapshot is the place.

Security

• No secrets: the plugin never reads, writes, logs, or ships credentials. OPENCODE_GO_API_KEY
  appears only as a name reference, exactly like the built-in route. Verified by pre-commit sweep.
• Network: only three public, keyless endpoints (models.opencode.ai/api.json,
  opencode.ai/zen/go/v1/models, opencode.ai/docs/go/), each with timeout + cache + offline
  fallback to snapshot values.
• Zero dependencies, no @deepseek-ai/dsh* peers (the install gate cannot refuse it),
  no shell hooks, fail-safe boot.

Compatibility

Built against DSH 0.2.0-rc.2 behavior (static pi-ai catalog, settings.mutate seam, optional
command registry). Pure ESM, Node ≥ 18.

License & sources

MIT — see LICENSE.

• Go | OpenCode (model list + endpoint table)
• OpenCode Go on Models.dev (context/output/pricing)
• Step 5 Preview · Step 5 API docs
• Discussion #3957 (stale-catalog root cause)
• Discussion #5495 (session header)
• Plugin authoring (dsh.pub) · Config & publishing
• Live roster: https://opencode.ai/zen/go/v1/models · Registry: https://models.opencode.ai/api.json