dsh-opencode-session
A DeepSeek Harness (DSH)
plugin that automatically sends the x-opencode-session request header on
model calls routed to OpenCode / OpenCode Go providers — one stable
session id per DSH conversation.
Why
Since 2026-09-05 OpenCode's relay requires an x-opencode-session header on
API requests (tracked upstream in
deepseek-harness discussion #5495);
without it, requests fail with 400 MissingSessionID-style errors. Requests
that share the same header value are pinned to the same upstream backend,
which is also what keeps OpenCode's prompt cache warm across the turns of one
conversation.
This plugin:
- fixes the 400 by always attaching the header to OpenCode(Go) requests,
- keeps the cache/affinity benefit by using a value that is unique per
conversation and stable across that conversation's turns (by default the
DSH session id itself, the same identity the official DeepSeek adapter
already sends as
x-deepseek-harness-session-id),
- leaves every other provider, and every request that already carries the
header, untouched.
Install
From the npm registry (once published):
dsh plugin --profile web add dsh-opencode-session
From a local checkout:
dsh plugin --profile web add ./path/to/dsh-opencode-session
Then fully restart your dsh profile (bundle layers are read at startup).
The startup log shows:
[opencode-go-session-header] active for providers [opencode, opencode-go] with mode session-id
If you run DSH from a source checkout instead, load it as an overlay:
pnpm dsh web --patch ./cordis.patch.yml.
Configuration
The plugin row lives in the bundle's cordis.patch.yml; all keys are optional:
- insert:
- id: opencode-go-session-header
name: dsh-opencode-session
config:
providers: [opencode, opencode-go] # route keys to attach the header to
mode: session-id # 'session-id' | 'uuid'
debug: false
debugFile: null # optional absolute path
providers — provider route keys whose requests get the header. The
defaults cover the pi-ai catalog ids opencode and opencode-go; add your
own route key when you serve OpenCode through a custom provider name.mode
session-id (default) — header value = the DSH session id of the model
call. Unique per conversation, stable across turns, compaction, retries
and process restarts.uuid — a random UUID derived once per DSH session id (opaque; kept in
memory, so it resets when the process restarts).
debug — log every streamed call that receives the header via
ctx.logger (the dsh process console).debugFile — optional absolute path. When set, every streamed call that
receives the header appends one JSON line
({"ts","provider","model","session","header","value"}) to that file —
handy when the dsh console is not visible.
To override configuration in a profile without editing the package, add a
row with the same id in the profile's own cordis.patch.yml (it replaces the
whole config, so restate every key).
How it works
- Listens on the
llm/stream waterfall. A call whose options.provider
names a configured OpenCode route and which carries a sessionId is
driven through an AsyncLocalStorage store holding the header value.
globalThis.fetch is patched once. While such a store is active, the
outgoing request receives x-opencode-session: <value> (unless it already
carries the header — an existing value always wins).- Both registrations are fiber-scoped ctx effects: stopping / updating /
unloading the plugin restores the original
fetch and removes the
listener.
Non-OpenCode providers, requests without a sessionId (some auxiliary
hand-built calls), and model discovery requests pass through untouched.
Notes / limitations
- The header is attached to chat/streaming requests inside an
llm/stream
call. The one-shot model listing used by the Models page
(GET <baseURL>/models) is a separate flow and does not receive the
header; if your OpenCode endpoint also rejects that listing, open an issue.
- The plugin relies on DSH outbound LLM requests going through the Node
global
fetch. If a future DSH version swaps its network stack, the
plugin stops injecting (symptom: the 400 comes back) — uninstall then.
Development
node --check lib/index.js
npm test # local behavior tests against an echo server
Publishing (for maintainers)
The package is plain ESM JavaScript with zero dependencies; npm test runs
automatically via prepublishOnly.
npm login # once, with your npm account
npm pack --dry-run # preview exactly what lands in the tarball
npm publish # files = lib/, cordis.patch.yml, README.md
Before publishing, double-check the name is free on the npm registry and fill
in author, homepage, and repository in package.json if you like.
License
MIT
