dsh-opencode-session-header
Per-conversation x-opencode-session header injection for DeepSeek Harness (DSH) → OpenCode Go.
It fixes the 400 MissingSessionID rejection and keeps OpenCode's per-conversation routing / prompt-cache optimization working — scoped strictly to opencode.ai, runtime-switchable without restart, zero dependencies.
中文文档
The problem
Since 2026-09-05, OpenCode Go requires a stable x-opencode-session header on every inference request (used for routing and prompt caching). DeepSeek Harness ≤ 0.1.2-rc.1 sends no such header on any adapter path, so every opencode-go model call fails:
400: {"type":"MissingSessionID","message":"Error from provider (Console Go): Request is missing x-opencode-session ..."}
Upstream fix is tracked in deepseek-harness discussion #5495 but has not shipped yet. This plugin fills the gap locally.
Why not the common workarounds?
| Static headers in settings.yaml | Global opencode_zen profile (dsh-custom-header) | This plugin |
|---|
| Fixes the 400 | ✅ | ✅ | ✅ |
| Per-conversation id (cache / routing optimal) | ❌ one shared id → cache misses, slower & pricier | ✅ | ✅ real DSH session id |
| Other providers untouched | ✅ | ❌ rewrites UA + x-opencode-* on every host | ✅ opencode.ai only |
| Toggle without restart | — | — | ✅ JSON file flip |
| Extra dependencies | — | third-party plugin, client bundle | none |
Install
dsh plugin --profile web add dsh-opencode-session-header
or from a local clone / checkout:
dsh plugin --profile web add "file:C:\path\to\dsh-opencode-session-header"
Then restart dsh web once — plugins load at boot. The startup log should show:
[dsh-opencode-session-header] loaded: header=x-opencode-session hosts=opencode.ai fallback=dsh-default
[dsh-opencode-session-header] runtime switch: <DSH_HOME>\plugins\dsh-opencode-session-header.json ({"enabled":false} disables; missing file = enabled)
Runtime switch (no restart needed)
State file: <DSH_HOME>/plugins/dsh-opencode-session-header.json (defaults to ~/.dsh):
{ "enabled": false }
false → injection off (all requests pass through untouched);true or file missing → injection on;- the file is re-read on every LLM request, so toggling takes effect immediately.
How it works
Two seams, both proven inside DSH 0.1.2-rc.1:
llm/stream waterfall observer — wraps every adapter stream iteration in an AsyncLocalStorage carrying GenerateOptions.sessionId (stable per DSH conversation across turns, compaction and retries; fresh per conversation / fork / subagent).- Fetch transport middleware — stamps
x-opencode-session only when the request host matches the allowlist (default: opencode.ai + subdomains). Value = the current session id, or the fallback id (dsh-default) outside any LLM context (e.g. model discovery). Every other host passes through byte-for-byte untouched.
The fetch pipeline runs under this plugin's own Symbol.for key (mechanics vendored from @aizigao/pi-fetch-pipeline, MIT), so it coexists with other fetch-patching plugins instead of clobbering them. Header merging follows the fetch spec: whichever of init.headers / Request.headers would reach the wire is used as the merge base.
Testing
npm test # 13 assertions: injection, fallback, allowlist, runtime switch,
# concurrent-session isolation, llm/stream propagation, subdomains
Compatibility & retirement
- Built and verified against DSH
0.1.2-rc.1 (npm latest at release time).
- Depends on DSH outbound LLM traffic using the process-global
fetch. If a future DSH build switches its network stack, the plugin silently stops injecting — the symptom is simply the 400 returning; uninstall then.
- Once upstream ships native per-conversation session headers (discussion #5495), retire this plugin:
dsh plugin --profile web remove dsh-opencode-session-header
then restart dsh web (optionally delete the switch file).
Credits
License
MIT
