dsh-session-header

English | 中文

A DeepSeek Harness plugin that injects an x-session-id HTTP header onto every LLM provider request the harness sends, carrying the harness session id of that exact call.

Why

The harness has no per-request header seam — GenerateOptions has no headers field and every adapter builds its own wire headers internally. If your model gateway (or an intermediary proxy) keys routing, caching, or auditing on a session header, the harness cannot send one by itself.

This plugin closes that gap with the two official interception points composed together:

• the llm/stream waterfall names the calls that are LLM calls and carries options.sessionId;
• a globalThis.fetch patch adds the header, so every fetch-based adapter (llm-deepseek, llm-pi-ai, and any SDK whose transport bottoms out in global fetch) is covered without touching adapter code.

Context propagation uses AsyncLocalStorage: only fetches that happen inside an LLM call's stream are touched; unrelated fetches (web RPC, telemetry, tool traffic) pass through untouched. A header anyone else already set is never overwritten (case-insensitive, per HTTP semantics). Unloading the plugin restores the original fetch.

Semantics of the value:

• default: GenerateOptions.sessionId of the call in flight, with the harness's session- branding prefix stripped (a plain UUID is sent) — main-session turns, compaction/title helper calls, and in-process subagent children each report their own session id (subagents get their own child session ids);
• value config: a fixed value for every call instead (sent verbatim, no prefix stripping);
• calls with neither get no header.

Install

Requires the dsh CLI and Node ≥ 22.

As a bundle (recommended)

dsh plugin --profile <name> add github:homily707/dsh-session-header

This package is plain JavaScript with no build scripts, so the pnpm ≥ 10 build allowance is not needed. Verify the layer and boot:

dsh --profile <name> --dump-config   # look for the "# == dsh-session-header" layer
dsh --profile <name>

As a --patch overlay from a local checkout

# my-overlay.yml — plugin rows need an absolute module path here
- insert:
    - id: session-header
      name: /absolute/path/to/dsh-session-header/index.js
      config:
        header: x-session-id
        # value: my-fixed-session-id

dsh --patch ./my-overlay.yml

Configuration

field	type	default	meaning
header	string	x-session-id	header name to inject; case-insensitive on the wire
value	string	—	fixed value; unset = the harness session id of the call in flight
toolEndpoints	string[]	[]	URL prefixes matched during tool execution. When non-empty, fetches inside a tools/execute waterfall — e.g. a gateway web-search Messages API called from a tool — get the header only when their URL starts with one of these prefixes; third-party tool targets (web_fetch of arbitrary pages, GitHub, MCP servers) stay untouched. Empty (default) keeps the upstream LLM-only injection.
overwriteHeaders	string[]	[]	Header names this plugin may overwrite when they already carry a value. Everything else keeps the "never overwrite" rule. Some official providers hard-code placeholder values (e.g. dsh-web-search-deepseek sends x-opencode-session: dsh-web-search), which gateways reject as missing; list the header here (overwriteHeaders: [x-opencode-session]) so the live session id replaces that placeholder. Case-insensitive.

Verify it

Point a provider's baseURL at a logging gateway (or any endpoint that echoes request headers) and start a session:

x-session-id: ba104306-a748-4052-a6e3-ab60be2e4c1f

Every request of the same conversation carries the same id; a spawned subagent's requests carry the child session id.

Notes

• The llm-deepseek adapter already sends its own x-deepseek-harness-session-id on every request; this plugin is provider-neutral and intentional about not overwriting existing headers.
• attributionHeaders() (the harness User-Agent attribution contract) is never touched.
• Concurrent sessions are handled correctly: the header value is resolved per call through AsyncLocalStorage, not through shared mutable state.

License

MIT