dsh-opencode-session-id
dsh session IDs for opencode, zero config.
English | 简体中文
A DeepSeek Harness (dsh) plugin: when you use an opencode model (providers such as opencode / opencode-go that point at the opencode.ai gateway), it makes the actual outgoing HTTP requests carry a session id — the same way the opencode client itself does.
Usage
Add the plugin to a dsh profile (install by package name once published to npm):
dsh plugin --profile web add "@gausszhou/dsh-opencode-session-id"
After installing, restart dsh web (systemctl --user restart dsh-web) so the bundle takes effect. The default configuration works out of the box: requests to opencode.ai automatically get x-opencode-session (the session header used by the opencode gateway) plus x-session-affinity / x-client-request-id / x-session-id. The header value defaults to a pure-alphanumeric nanoid(8) derived from the uuid portion of the session id (e.g. 0RpJJnxJ — the session- prefix does not participate in the hash; the token is deterministically derived from the uuid via SHA-256). With verbose: true, the journal logs the mapping between the original id and the wire token:
journalctl --user -u dsh-web -f | grep opencode-session-id
How it works
The opencode gateway branch uses x-opencode-session to carry the session id; this plugin listens on the llm/stream scope, wraps fetch, and adds that header at the wire layer. By default it hashes the uuid portion of session-<uuid> (the session- prefix is excluded) into an alphanumeric nanoid(8) before it goes on the wire. Only request headers are touched — the request body, URL, method, and everything else pass through unchanged. See docs/design.md for the full design rationale.
Configuration
Zero configuration needed by default (the install command above is all you need). To enable injection logging through the patch layer:
- id: opencode-session-id
config:
verbose: true
All options (each optional, defaults shown):
| Key | Default | Description |
|---|
providers | [opencode, opencode-go] | llm-pi-ai route names whose sessionId should be tagged |
hosts | [opencode.ai] | URL host suffixes (including subdomains) that get session headers |
baseURLs | [] | Additional exact URL prefixes to match (custom gateways) |
headers | [x-opencode-session, x-session-affinity, x-client-request-id, x-session-id] | Request header names to inject |
extraHeaders | {} | Optional static extra headers (e.g. opencode fingerprint family x-opencode-client: native / x-opencode-request: dsh) |
userAgent | empty | Override User-Agent (opencode itself sends opencode/<version>; untouched by default) |
sessionIdEnv | empty | Environment variable name to fall back on for the session id |
verbose | false | Log every injection (including the original id → wire token mapping) |
seedSessionId | false | Seed options.sessionId for opencode routes |
nanoidSessionId | true | Hash session-<uuid> to a nanoid(8) before sending; false sends the raw id |
nanoidLength | 8 | Token length (4–32) |
nanoidAlphabet | alphanumeric | alphanumeric (pure A-Za-z0-9, no _/-) or urlsafe (classic 64-character set) |
disableFetchInjection | false | When true, keep only the waterfall session scoping |
Verification
node test/verify.mjs # 10 checks: unit tests + real pi-ai wire request + concurrent isolation + headers-only guarantee
node test/smoke-apply.mjs # apply() wiring: listener registration, scoped fetch, mount/dispose lifecycle
verify.mjs fires a real opencode-go request through the pi-ai bundled with the dsh CLI, asserting that the wire request headers really carry the session id; it also verifies concurrent-session isolation and that non-opencode endpoints are unaffected.
Notes & limitations
- The session id comes from
options.sessionId (agent-loop fills it in per session); without a session context, the fallback chain is sessionIdEnv > DSH_SESSION_ID (the process's startup session in web deployments) > an in-process random id.
- Covers protocols that go through
fetch, such as openai-completions / openai-responses / anthropic-messages; transport: websocket does not use fetch and is out of scope.
- The global fetch wrapper only appends request headers when an opencode endpoint is matched — nothing else is changed. The wire token is a one-way SHA-256 hash of the uuid portion of
session-<uuid> (the session- prefix excluded, e.g. 0RpJJnxJ), so the backend cannot reverse it to the original id; changing nanoidAlphabet / nanoidLength changes every token, breaking association with old records.
