[Bug] llm-pi-ai/opencode-go: missing x-opencode-session header and deepseek-v4.1-flash catalog entry

[archiforge]

Environment: dsh 0.1.5-rc.2, llm-pi-ai with the opencode-go provider route (user settings), model deepseek-v4.1-flash.

Two defects on the same provider route; both are fixed in a reference branch linked below.

1. Every opencode-go request is refused with 400 MissingSessionID

OpenCode Go routes and prompt-caches per conversation on a stable x-opencode-session header and answers requests without it with:

400 {"type":"MissingSessionID","message":"Error from provider (Console Go): Request is missing x-opencode-session and cannot be routed efficiently. Please see https://opencode.ai/docs/go/#where-can-i-use-it"}

@earendil-works/pi-ai 0.85.1 never sends the header: its sessionId option maps only to the affinity headers that a model's compat flags name (sendSessionAffinityHeaders), and the opencode-go catalog entries set none of them. OpenCode's docs currently list DeepSeek Harness among clients whose session support is incomplete.

Fix approach: derive x-opencode-session from the seam's GenerateOptions.sessionId in the llm-pi-ai adapter. Main, compaction, and session-title calls all already stamp the session identity, so one conversation sends one stable value; a deployment-configured header wins case-insensitively, and a request without a session id sends none.

2. deepseek-v4.1-flash is not selectable

models.dev registered deepseek-v4.1-flash, but pi-ai 0.85.1's generated opencode-go catalog predates it, so the model is absent from every selector. Fix approach: a pnpm patch adds the flattened catalog entry (mirroring deepseek-v4-flash-vision-exp) plus a guard test that fails, naming the patch, until a pi-ai release ships the model and the patch can be dropped.

Reference implementation

Both fixes with tests are on a branch in my fork, two commits on top of current master: archiforge/deepseek-harness@master...mohamed-bashir-dev:deepseek-harness:fix/llm-pi-ai-opencode-go

The adapter spec covers sending the derived header on opencode-go, absence on another provider, the case-insensitive deployment override, and absence when the request names no session; the catalog guard spec covers the patched entry. Understood that external PRs are closed for now — happy to rework or hand this over in whatever form is useful.

[PerryLink]

Both defects verified against master (c291e79) and the vendored pi-ai 0.85.1 — they are exactly as you describe, and neither is fixed.

1. No x-opencode-session, ever. The harness forwards the session identity into pi-ai (packages/llm/llm-pi-ai/src/adapter.ts:380-388), but pi-ai 0.85.1 (declared ^0.85.1, packages/llm/llm-pi-ai/package.json:44) contains zero occurrences of x-opencode-session in its shipped dist. Its only use of sessionId is the opt-in x-session-affinity header, gated by compat.sendSessionAffinityHeaders (dist/api/openai-completions.js:557, dist/api/anthropic-messages.js:725), and the opencode-go entries in dist/providers/data/opencode-go.json set no such compat flag. OpenCode Go's 400 MissingSessionID is therefore guaranteed on this route. (The harness's own compat gates even withhold that flag for profile entries: packages/llm/llm-pi-ai/src/catalog.ts:255.)

2. deepseek-v4.1-flash is absent from dist/providers/data/opencode-go.json, and the harness builds every selector from the installed catalog (packages/llm/llm-pi-ai/src/catalog.ts:1-16), so the model cannot appear anywhere.

Workarounds without patching:

• Header: a route profile can carry arbitrary request headers (packages/llm/llm-pi-ai/src/config.ts:150-151), merged into every request (adapter.ts:386-388). A static x-opencode-session: <fixed-value> removes the 400, at the cost of one shared affinity id across all sessions (per-session prompt-cache routing is lost). A true per-session value needs the adapter change you wrote — deriving from GenerateOptions.sessionId is exactly the right seam, and a deployment header winning case-insensitively matches how requestHeaders already merges profile headers.
• Model: a profile models entry can describe a model the installed catalog does not know (catalog.ts:1-6, resolution at catalog.ts:893-930). Mirror the deepseek-v4-flash-vision-exp opencode-go entry's fields and deepseek-v4.1-flash becomes selectable today.

Your fork branch (fix/llm-pi-ai-opencode-go) is the correct upstream shape; with PRs closed on this repo, the discussion is the right channel, and I'll flag both defects for maintainer attention.

[JTropy]

Additional validation on Windows with DSH 0.1.5-rc.1 and @earendil-works/pi-ai 0.85.1:

• Inspection of the installed package confirmed that the OpenCode Go catalog lacked deepseek-v4.1-flash and the adapter did not derive x-opencode-session from the DSH session ID. We did not make a pre-fix live request to reproduce the 400 response.
• After adding the catalog entry and deriving the header from GenerateOptions.sessionId specifically for opencode-go, the model appeared in the Web UI.
• An end-to-end Web UI smoke test succeeded: the model called a terminal tool once to calculate 17 * 19, consumed the tool result, and answered 323. A second turn, without tools, correctly returned 324 when asked to add one to the previous result. Session records confirmed the route was opencode-go / deepseek-v4.1-flash and both turns completed.
• Focused header checks passed for distinct conversation IDs, no session header on another provider, omission when the session ID is absent, and preservation of an explicitly configured header with case-insensitive name matching (without adding a duplicate).

This validates a local patch of the installed release, not a build of the linked reference branch. No credentials, local configuration, or session logs are attached.

[yinsang0910-star]

Independent confirmation from a Windows box, plus a user-level interim workaround that needs no fork or build. Nothing here contradicts the reference branch — it corroborates it and flags one gap that the two-patch fix pair does not close.

Environment and validation

• dsh 0.1.5-rc.1 with @deepseek-ai/dsh-llm-pi-ai 0.1.5-rc.2 and @earendil-works/pi-ai 0.85.1, Windows 11, Node v24.16.0.
• Both defects reproduce exactly as described.
• Version check worth adding to the thread: I extracted the published @deepseek-ai/dsh-llm-pi-ai@0.1.5-rc.2 tarball and diffed it against the installed adapter — byte-identical, so the next tag carries no fix yet. @earendil-works/pi-ai 0.85.1 (npm latest) contains no x-opencode-session string at all.
• Corroborating the "send it across all adapters" framing in OpenCode's client table: the official dsh-llm-deepseek adapter does stamp the session identity (x-deepseek-harness-session-id, dist lib/index.js:1666), and the pi-ai adapter stamps nothing. So it is one adapter family away, not a missing capability.

Live before/after (not just code inspection)

Direct POST https://opencode.ai/zen/go/v1/chat/completions, model deepseek-v4.1-flash, same key, browser UA:

• no session header → 400 {"type":"MissingSessionID",…} — 3/3
• x-opencode-session: <stable per-conversation value> → 200 with a real completion — 3/3

Through the harness itself (dsh --profile headless, with that OpenCode route forced as the agent default model):

• before the patch: dsh: INVALID_REQUEST: 400: {"type":"MissingSessionID",…}
• after the patch: ok

So the header is the sole discriminator, and any stable opaque per-conversation value is accepted — no particular format is required.

Interim workaround for users on published builds

The identity is already inside the adapter: sessionId reaches the pi-ai stream options — verified at three call sites in the installed packages (dsh-agent-loop lib/index.js:1215 for the main loop, dsh-compaction-basic :298, dsh-session-title-llm :215; only dsh-session-title-first-prompt-llm omits it). So the fix can live entirely at the adapter boundary — wrap the headers object handed to streamSimple and add x-opencode-session when the route targets OpenCode, letting an explicitly configured header win case-insensitively.

Applied as a local patch to the bundled …/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-llm-pi-ai/lib/index.js (plus an idempotent re-apply script, because npm i -g @deepseek-ai/dsh rebuilds that tree), both routes work again end to end against the real gateway.

Honest costs: it is unsupported, it must be re-applied after every upgrade, and it cannot help with defect 2.

A gap the fix pair does not cover

Defect 2 is currently addressed by a pnpm patch that adds the flattened catalog entry. That works, but the reason a patch is needed at all is that model discovery never interrogates a route pi-ai ships a catalog for: packages/llm/llm-pi-ai/src/discovery.ts returns catalogModels(provider) and never calls the endpoint. So every future OpenCode model needs another catalog patch plus another guard test, while GET /zen/go/v1/models (37 models today, 27 in the catalog) is the only authority.

For reference, my local patch skips that short-circuit for OpenCode routes only: query {baseURL}/models (listing sent over openai-completions; take the baseUrl from a catalog entry whose api is openai-completions, not the first entry — an anthropic-protocol entry's base lacks /v1 and 404s), keep catalog capacities for ids the catalog knows, fall back to the catalog list when the endpoint is unreachable, and leave every other provider untouched. Verified merged result: 37 ids, deepseek-v4.1-flash present, deepseek-v4-flash keeps 1000000 / 384000.

And even with live discovery there is a structural blocker to "discovered ⇒ usable": in resolveRouteModels() the route-level api wins over every model's own protocol (request.api ?? base?.api ?? routeApi), so declaring a catalog-unknown model on the multi-protocol opencode-go route would re-protocol its anthropic-messages and openai-responses models as well. A per-model api in the profile schema — or letting a catalog route carry extra entries — is what would let a user adopt a newly discovered model directly instead of creating a second route.

Cross-referencing the discovery side in #5654.

[PerryLink]

Thanks to both of you — two independent live validations (JTropy's Web UI smoke test, and the 3/3 before/after against the real gateway) plus the tarball check that 0.1.5-rc.2 still ships the unfixed adapter is exactly the evidence this thread needed. The header being the sole discriminator — any stable opaque per-conversation value accepted — also confirms the fix doesn't depend on a particular format.

The gap you flagged is real; I verified both halves against source at c291e79:

1. Discovery short-circuit: discoverModels returns catalogModels(provider) immediately when the route has an installed catalog and never reaches the network (packages/llm/llm-pi-ai/src/discovery.ts:273-285). For opencode-go, GET {baseURL}/models is never consulted, so every future OpenCode model needs another catalog patch — as you say.
2. The protocol blocker: in resolveRouteModels each entry's wire api resolves as request.api ?? base?.api ?? routeApi (packages/llm/llm-pi-ai/src/catalog.ts:888), and a catalog-unknown id without a route api fails with "needs an api" (:889-892). A catalog-unknown model on the multi-protocol opencode-go route therefore needs the route api pinned (re-protocoling the catalog's anthropic/openai-responses entries) or a separate route. Per-model api in the profile schema — or letting a catalog route carry extra entries — is the seam that would make "discovered ⇒ usable" actually close.

Your local patch's shape (skip the short-circuit for OpenCode routes only, take the baseUrl from an openai-completions catalog entry, fall back to the catalog list when the endpoint is unreachable, leave other providers untouched) is the right scoped form of that. I also fetched GET https://opencode.ai/zen/go/v1/models just now: 37 ids, deepseek-v4.1-flash present — your count is exact.

This thread now carries: verified defects, a reference branch (fix/llm-pi-ai-opencode-go), two independent user-level workarounds, and the discovery-side gap. That's a complete package for maintainers to pick up; I'll keep flagging it.

---

[danslamer]

Confirmed independently on Windows (dsh 0.1.5-rc.1, dsh-llm-pi-ai 0.1.5-rc.2, @earendil-works/pi-ai 0.85.1, model route opencode-go / model deepseek-v4.1-flash). Both defects reproduce exactly as described, and both can be worked around without a fork or a local build:

1. 400 MissingSessionID — the profile can carry the header itself.
dsh-llm-pi-ai forwards a route profile's headers verbatim into the pi-ai stream options (compiled lib/index.js:1873), and pi-ai merges them into the client's default headers, so declaring them on the route unblocks requests immediately:

llm-pi-ai:
  providers:
    opencode-go:
      apiKeyEnv: OPENCODE_GO_API_KEY
      headers:
        x-opencode-session: <one stable uuid per install>
        x-deepseek-harness-session-id: <same uuid>   # DSH's native header

One caveat for whoever applies this: src/providers/opencode-headers.ts on pi main (withOpenCodeSessionHeader) uses a hasHeader() short-circuit, so once a pi-ai release carries it, the static x-opencode-session must be removed — otherwise the hard-coded value suppresses the real per-conversation id and you lose the routing/caching benefit that motivated the header.

2. Missing deepseek-v4.1-flash catalog entry — patch the installed catalog, do not split the route.
Declaring a second provider route (opencode-go-v41) with a route-level api does work, but it is the wrong shape: the provider route id is the key for accounting and settings. Observed side effects during the split — 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 a plugin that probes the OpenCode Go plan by exact id (@linxin666/dsh-usage, ids: ['opencode-go']) shows no quota row for the second route even though the quota is account-level. Adding the entry to the installed catalog keeps one route and one bucket:

node_modules/@earendil-works/pi-ai/dist/providers/data/opencode-go.json → add under openai-completions a clone of the deepseek-v4-flash entry with id/name/cost adjusted (api openai-completions, baseUrl https://opencode.ai/zen/go/v1, reasoning: true, thinking levels low/high/max, deepseek thinking format, 1M context / 384k output). Note the file is UTF-8 without BOM; a BOM makes the JSON module fail to parse.

Status of the upstream data (good news): pi-ai regenerates that catalog from models.dev at publish time, and models.dev's opencode-go provider already lists deepseek-v4.1-flash (tool_call: true, reasoning: true, context 1000000, output 384000, provider.npm unset ⇒ openai-completions, last_updated 2026-09-10). So the next @earendil-works/pi-ai release is expected to ship the entry automatically — the local catalog patch is a stopgap. (The pi-side report for this is earendil-works/pi#9737, auto-closed under that repo's new-contributor policy but eligible for daily maintainer review.)

Verified after applying both parts and restarting dsh: a single opencode-go route serves deepseek-v4.1-flash alongside its existing 27 models (12 calls, 252k input / 17k output / 2.7M cache read on the first stretch, i.e. prompt caching healthy), and the OpenCode Go plan probe still reports its rolling/weekly/monthly windows on that route.