dsh-custom-header

dsh-custom-header

Outbound LLM request modification for DeepSeek Harness (DSH), at the fetch transport layer.

One globalThis.fetch middleware chain (keyed by a DSH-scoped symbol, Symbol.for("dsh-custom-header.fetch.pipeline.v1")) that every provider — whatever plugin owns it — streams through:

• injects client-identity headers (User-Agent, Originator,

X-Claude-Code-Session-Id, x-opencode-*, …) from presets that mirror real Codex / Claude Code / opencode clients

• strips X-Stainless-* runtime fingerprint headers
• rewrites the request URL (path matching + appendQuery)
• patches request bodies: the Anthropic Messages identity / billing system

block + metadata.user_id, and the opencode Zen free-tier tool stubs

For servers you administer or are authorized to use. Cloudflare TLS/Bot

edge blocks need a different API entry, an admin allowlist, or a local

forward proxy.

Why fetch, not a provider-owning adapter

The 0.2/0.3 line rewrote this plugin as provider-owning LlmAdapters registered through ctx.llm.registerAdapter(routes, adapter). That extension point is per-route exclusive: registering a route another plugin already owns (say the ziyong/moonshotai providers that llm-pi-ai registers) throws DUPLICATE_ADAPTER, and the host exposes no way to graft onto someone else's adapter. The point of this plugin is exactly "make requests to *my* gateway look like client X" — whatever plugin those requests come from — so it needs a seat that owns no routes at all. The fetch layer is that seat: it intercepts the transport every adapter already uses.

The cost of the fetch seat is that only the request URL identifies a request (never the owning provider). So the gatewayHosts allowlist is the single safety boundary: every profile — fixed ones included — touches only requests whose host matches, and an empty allowlist is a safe no-op.

How it works

apply registers four middlewares into the shared pipeline, each re-reading a snapshot that loader/volatile-update refreshes (a settings save therefore lands in the next request — no restart):

priority · middleware · what it does 5 · url-rewrite · path matching + appendQuery / replacement, host-gated 6 · header-strip · X-Stainless-* and runtime fingerprint removal, on profiles that ask for it 7 · header-inject · the resolved profile's identity headers + extraHeaders 8 · body-patch · Anthropic identity body patch; opencode Zen /zen → /inference + bash/read tool stubs (free models only)

The chain mechanics: an accessor fetch on globalThis whose setter keeps the underlying fetch in sync; middlewares compose on every (re)install, priority ascending; each receives { input, init, next } and may call next with rewritten input. The pipeline is vendored from (MIT), re-keyed for DSH so multiple plugins can coexist without clobbering each other's chains.

Session-scoped ids (x-opencode-session, X-Claude-Code-Session-Id, metadata.user_id) cannot be read from a URL, so the plugin wraps the llm/stream waterfall: every adapter stream iteration — including the fetch it issues — runs inside an AsyncLocalStorage carrying GenerateOptions.sessionId. That is what keeps concurrent DSH conversations from sharing one process-wide id. The same observer logs a 403 hint distinguishing Cloudflare HTML edge blocks from JSON client-restriction rejections.

Configuration is a schemastery Config schema on the plugin, validated by the Loader against cordis.yml. Every field is `.volatile()`, which is what makes dsh-settings publish a writable namespace for the entry at all: its describe() collects only entries carrying a volatile field, and its writer rejects any other path. A volatile-only change is committed into the running fiber rather than remounting it — the host half re-reads its refs on loader/volatile-update instead of snapshotting at mount.

The page itself is the plugin's own browser half (src/client/*). It registers as a section of the Settings panel (settings.section) and, as a second seat, on the bundle's own row in the Plugins page (plugins.row.config) — see Configuration page below.

concern · where middleware registration + diagnostics · index.ts fetch pipeline (vendored, symbol-keyed) · fetch-pipeline.ts header injection / stripping · header-inject.ts profile resolution + presets · profiles.ts Anthropic body patch + Zen free tier wiring · body-patch.ts opencode Zen helpers · opencode-zen.ts URL rewrite · url-rewrite.ts per-conversation session ids · session-context.ts (AsyncLocalStorage) 403 diagnostics · index.ts + response-hints.ts settings schema (all volatile) · config.ts (ConfigSchema, schemastery) configuration page · client/index.tsx (settings.section + plugins.row.config) scenario tabs → staged profile · client/scenarios.ts page copy (zh / en) · client/locales.ts page controls + field specs · client/fields.tsx page stylesheet · client/styles.ts

Safe default: profile: "off", or an empty gatewayHosts — either way nothing is injected, stripped, rewritten or patched.

Profiles

Each fixed profile is a complete client-identity header set:

Profile · Headers sent codex_desktop · codex_app/1.2026.0628 (Windows NT 10.0; Win64; x64) + Originator: codex_app codex_official · codex_cli_rs/0.147.0 (Windows 10.0.19045; x86_64) WindowsTerminal + Originator: codex_cli_rs codex_tui · codex-tui/0.147.0 (…; x86_64) WindowsTerminal + Originator: codex-tui codex_claude_plugin · Claude Code/0.5.0 (Macos 15.5; arm64) iTerm2.app + Originator: Claude Code pi_agent · pi-coding-agent/1.0 + Originator: pi (needs the server to accept this identity too) claude_code_messages · claude-cli/2.1.220 (external, sdk-cli) + X-Claude-Code-Session-Id + full anthropic-beta + body (metadata.user_id JSON / system block) opencode_zen · opencode/1.19.0 ai-sdk/... UA + x-opencode-client/project/session/session-id/request (descending ses_ id) auto · on a matching host: Anthropic /v1/messages paths → Claude set; anything else → codexFallback off · nothing

All profiles — fixed ones included — are gated by gatewayHosts. The Codex header values are verified against openai/codex source (see "Truthfulness verification"); the opencode Identifier id scheme (msg_ ascending / ses_ descending, hex12 + base62) and the Claude Code 2.1.220 header set are re-implemented from their real-world formats.

Truthfulness verification (Codex presets)

Codex identity fields were checked against primary sources:

• `Originator: codex_cli_rs` — openai/codex

codex-rs/login/src/auth/default_client.rs: DEFAULT_ORIGINATOR = "codex_cli_rs".

• codex_official UA shape — same file, get_codex_user_agent():

{originator}/{CARGO_PKG_VERSION} ({os_type} {os_version}; {arch}) {terminal}, with the terminal token from codex-rs/terminal-detection/src/lib.rs (WindowsTerminal for Windows Terminal, xterm-256color from TERM, …). A literal terminal tail matches no real build and was replaced. 0.147.0 is the current release (rust-v0.147.0, 2026-08-07).

• codex_cli_rs vs codex-tui — the CLI has several first-party front-ends.

default_client.rs sets DEFAULT_ORIGINATOR = "codex_cli_rs" and builds the UA from the process originator, but is_first_party_originator also whitelists codex-tui and codex_vscode, and the TUI self-identifies as client_name: "codex-tui" (tui/src/lib.rs). Interactive codex sessions therefore actually send codex-tui/… UA + Originator: codex-tui. Profiles codex_official (headless/default) and codex_tui (interactive TUI) cover both.

• `codex_app/` + `Originator: codex_app` — the desktop shell is

closed-source; codex_app is the client family's own identity string. The full UA is a measured capture; override via codexDesktopVersion.

• codex_claude_plugin UA — Claude Code UA format

(Claude Code/x.y.z (OS; arch) Terminal); 0.5.0 is an old but real version. Server checks only match the prefix, so the value is kept conservative.

Install

dsh plugin --profile web add file:$(pwd)     # or: dsh plugin add dsh-custom-header

Verify: look for the dsh-custom-header loaded: ... diagnostics in the server log, or inspect ctx.dshCustomHeader.status().

Config (cordis.yml)

dsh-custom-header:
  profile: auto             # auto | off | codex_desktop | codex_official | codex_tui | codex_claude_plugin | pi_agent | claude_code_messages | opencode_zen
  gatewayHosts:
    - gateway.example.com   # the allowlist: EVERY profile only touches these hosts; subdomains match; empty = no-op
  codexFallback: codex_desktop
  codexCliVersion: 0.147.0
  codexDesktopVersion: 1.2026.0628
  claudeCliVersion: 2.1.220
  # anthropicBeta: "claude-code-20250219,interleaved-thinking-2025-05-14,…"  # anthropic-beta header (claude_code_messages)
  opencodeVersion: 1.19.0
  opencodeClient: cli
  opencodeProject: global
  # opencode Zen free tier (needs profile: opencode_zen and a free model):
  opencodeZenFree: false        # /zen → /inference + bash/read tool stubs
  claudeSystemBlock: identity    # identity | billing
  extraHeaders: {}              # merged onto every profile
  urlRewrites:
    /v1/messages:
      appendQuery: beta=true    # servers that strictly check ?beta=true

Point your provider's own base URL at the gateway as usual — this plugin never touches provider configuration; it intercepts the requests that provider makes.

Configuration page

The page is a section of the Settings panel: *Settings → Custom header*, a nav row of its own beside General / Models / Plugins, registered into the settings.section slot.

The page is a nav rail plus three stable pages (the shell follows dsh-any-background's settings section). Every field has exactly one home, and switching pages never reclassifies a row — a field that relocated while being edited was the exact weirdness this layout removed:

page · fields Identity & gateway · gatewayHosts, codexFallback, claudeSystemBlock Version headers · claudeCliVersion, codexCliVersion, codexDesktopVersion, anthropicBeta, opencodeVersion, opencodeClient, opencodeProject, opencodeZenFree Advanced · extraHeaders, urlRewrites

The identity page opens on a scenario picker, not on a list of fields. Accurate field names describe the *config*; they do not describe the *job*. Nobody arrives wanting to set gatewayHosts — they arrive wanting Codex, or Claude Code, or opencode, or the pi agent, to reach their own gateway. Each tab is one of those intents, and picking it stages the profile that makes the intent real:

scenario · stages profile Auto · auto Codex · codex_official / codex_tui / codex_desktop / codex_claude_plugin (a second-level choice) Claude · claude_code_messages pi · pi_agent opencode · opencode_zen Off · off

Only the active page's fields are rendered, so one field is mounted exactly once and each control's DOM id stays unique.

Controls

Each field is drawn with the host control its shape calls for:

field shape · control · one-line text · SettingsValueField · draws its own label, overridden badge, reset, invalid copy and help region 2–4 fixed values · SegmentedControl · claudeSystemBlock, codexFallback, the Codex variant boolean · Switch · opencodeZenFree string list / JSON object · textarea · the page's own — the host ships no multiline row

The long explanations live behind each row's ? button rather than under it, which is what lets the always-visible hint stay one line.

The same form is registered a second time on the Plugins page, on the bundle's own row (*Plugins → dsh-custom-header*, the row's Configure control), through plugins.row.config. That is where the host's slot contract puts a third party *bundle*'s configuration; the Settings section is where a user actually goes looking for it.

Nothing is written as you type: the page stages a draft and Save is the only thing that mutates the settings document, revision-fenced against a concurrent change elsewhere. Picking a scenario is one more staged edit and follows the same rule — it lands on Save and Discard undoes it. A save lands in the profile patch and takes effect on the next request — no restart.

Four consequences of the host contract are worth knowing if you touch this code:

• The host half must export names only — never `export default`. The loader

picks a plugin module off with unwrapExports (cordis-plugin-loader/lib/index.js), which prefers default over the namespace:

exports = exports.default ?? exports      // default REPLACES the namespace
  if (!exports.__esModule) return exports
  return exports.default ?? exports

so export default apply hands the registry a bare function: fiber.runtime *is* that function, therefore fiber.runtime.Config is undefined. dsh-settings reads the schema from exactly there (schema(entry) { const schema = entry.fiber?.runtime?.Config; … }) and bails out with return [] when it is missing — so no settings namespace is ever published. The symptom is maximally misleading: the plugin loads, its client half still registers the nav row, every log line is clean, and only the page body says *"this host does not serve this configuration"* — which reads like a client bug. Every shipped host half exports named only (dsh-client-ui-settings → export { Config, apply }; dsh-ops likewise); so does this one. build.mjs asserts the absence of a default export after every build.

• The plugin needed no plugins.item entry. That slot is occupied by the

official settings pages; a bundle's configuration belongs in plugins.bundle.config or plugins.row.config, keyed by the bundle's package name (here # = dsh-custom-header#dsh-custom-header).

• A settings.section registration carries the nav identity in its options:

id (required — a fresh id is added beside the shipped rows, reusing theirs replaces that row), order (ascending position; the shipped rows sit at −10/0/10/15/20 and dsh-market at 40, so this one takes 50) and label (a thunk, re-read on every projection so it follows the locale). The Settings content column draws no heading for a section, so the page renders its own.

• A .volatile() field is what makes the entry appear in the settings plane at

all. Removing the marker removes the page, silently.

ctx.dshCustomHeader.setProfile('codex_desktop')   // programmatic runtime switch
ctx.dshCustomHeader.status()                      // diagnostics snapshot

Known residuals & limits

• `accept-language` / `sec-fetch-mode` — injected by Node undici below

fetch, outside the interceptor. Most servers only check UA + custom headers; terminate the rest at a local reverse proxy if needed.

• `?beta=true` for Anthropic — solved via urlRewrites.appendQuery, no

proxy needed.

• Cloudflare blocks — HTML edge responses cannot be fixed by header

modification; switch API entry, ask for an allowlist, or forward locally. The llm/stream observer logs a 403 hint distinguishing CF HTML from JSON client-restriction rejections.

• opencode Zen free tier — header spoofing alone no longer passes. With

profile: opencode_zen, opencodeZenFree: true and a free model (*-free / big-pickle / grok-code), the body-patch middleware rewrites /zen → /inference and offers the bash/read tool stubs Zen now requires. The model id is read from the request body, which is why the URL rewrite lives in that middleware rather than in url-rewrite.ts.

• Request body patches require a re-readable body — the body-patch

middleware buffers JSON request bodies (content-length is re-computed); non-JSON or streamed request bodies are passed through untouched.