dsh-opencode-go-x-session 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pengpenglele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# dsh-opencode-go-x-session
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Host-only DeepSeek Harness bundle that adds OpenCode Go's required
+`x-opencode-session` request header to the model requests of the configured
+OpenCode provider routes, and nowhere else.
+
+## Why
+
+OpenCode Go / Zen requires `x-opencode-session`: a stable identifier for one
+conversation, used for routing and prompt-cache affinity. Since 2026-09-05 the
+gateway rejects inference requests without it:
+
+```
+400 {"type":"MissingSessionID","message":"... Request is missing x-opencode-session ..."}
+```
+
+Inside DSH two request shapes reach OpenCode without the header:
+
+1. **Auto-review (and other hand-built calls).** pi-ai's catalog provider
+   `opencode-go` adds the header from `GenerateOptions.sessionId`, and
+   `dsh-llm-pi-ai` forwards that field — so ordinary main-model requests are
+   fine. The auto-review reviewer calls `ctx.llm.stream()` with **no**
+   `sessionId`, so the catalog provider has nothing to write and the review
+   fails closed (`Auto review of tool "..." failed`).
+2. **Hand-declared OpenCode routes.** A provider key pi-ai's installed catalog
+   does not ship, or one that spells out `api`/`baseURL` (such as
+   `opencode-go-free-none` / `opencode-go-audit-free-none`), is built by
+   `dsh-llm-pi-ai` itself over the plain protocol implementation. That path
+   never applies pi-ai's OpenCode session-header wrapper, so even ordinary
+   main-model requests lack the header.
+
+`llm-pi-ai` has no per-request header hook: its per-route `headers` field is a
+static `Record<string, string>` from config, and the adapter rebuilds pi-ai's
+header object on every call. This plugin bridges the gap at the transport both
+paths actually use, scoped to the configured routes and hosts.
+
+It changes no model-visible content: no prompt text, no session event, no
+transcript entry.
+
+## How it works
+
+1. It listens on the supported `llm/stream` waterfall. When the request's
+   provider is one of the configured routes, it resolves the conversation id in
+   this order: the request's own `sessionId`; the enclosing model-call scope
+   (nested calls); the initiator Agent's session through
+   `ctx.agents.currentInitiator()` — this is what gives an auto-review request,
+   which runs inside the reviewed Agent's driver chain, the conversation id it
+   is reviewing; finally the configured stable `fallbackSessionId`. The
+   downstream chunk stream is wrapped so every pull runs inside an
+   `AsyncLocalStorage` scope carrying that id.
+2. It wraps `globalThis.fetch` (the `openai` SDK's default transport, resolved
+   per request when `options.fetch` is not set). Inside a captured scope the
+   wrapper adds the header when it is absent and the URL host is allowlisted;
+   every other request gets the original arguments untouched, and the wrapper is
+   removed when the plugin unloads or is switched off.
+
+The value is the Harness session id (`GenerateOptions.sessionId`), so it is
+stable across the turns of one session and distinct between concurrent
+sessions. Requests for any other provider never enter the scope, so built-in
+routes and every other model configuration behave exactly as before.
+
+## Config
+
+All fields are optional; every field is `volatile()`, so this table is also the
+plugin's settings page.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Master switch (the unified plugin switch); `false` removes the fetch patch immediately and leaves every request untouched |
+| `providers` | `['opencode-go*']` | Provider routes that receive the header; an entry may be a trailing-`*` prefix pattern. The default pattern covers the `opencode-go` catalog route and every `opencode-go-*` variant, so a new variant needs no config change; an empty list disables injection |
+| `hosts` | `['opencode.ai']` | Host allowlist, each entry also covering its subdomains; an empty list removes the host check (for a proxy endpoint) |
+| `fallbackSessionId` | `dsh-auto-review` | Stable id used only when no request, scope, or initiator session id is available |
+| `debug` | `false` | Log each injection through the Host logger |
+
+Edit them in the plugin's settings page (Settings → Plugins), or override the
+inserted row in the profile's `cordis.patch.yml`:
+
+```yaml
+- id: opencode-session-header
+  config:
+    enabled: true
+    providers:
+      - 'opencode-go*'
+    hosts:
+      - opencode.ai
+    fallbackSessionId: dsh-auto-review
+    debug: false
+```
+
+## Install
+
+From npm (recommended):
+
+```sh
+dsh plugin --profile desktop add dsh-opencode-go-x-session
+```
+
+From this repository — clone it, then install the directory as a bundle through
+the Harness plugin manager (Web: Plugins → Install bundle; tool:
+`install_bundle` with this directory's absolute path as the target):
+
+```sh
+git clone https://github.com/pengpenglele/dsh-opencode-go-x-session-code.git
+```
+
+Either way the bundle patch inserts one Host row, `opencode-session-header`; the
+change applies to every session in the profile.
+
+For a `link:`/local installation the package directory needs its own
+`node_modules` for the `schemastery` dependency (`pnpm install
+--ignore-workspace` in this directory), because a `link:` installation resolves
+the plugin's dependencies from its real path.
+
+## Turning it off (three equivalent ways)
+
+- **Settings switch** — set `enabled: false` on the plugin's settings page; the
+  fetch patch is removed at the next settings commit and every request passes
+  through untouched. No restart.
+- **Plugin row** — disable the `opencode-session-header` row in the Plugin
+  Manager; the whole fiber unloads and the original `fetch` is restored.
+- **Profile patch** — add `- id: opencode-session-header` with
+  `disabled: true` under your patch layer.
+
+## Verify
+
+- Plugin inventory shows **OpenCode Session Header / OpenCode 会话头注入** with
+  this icon and the description above (en/zh).
+- The plugin settings page shows the five fields above with their defaults.
+- `npm test` (plain Node, no Host) asserts against a mocked `fetch`:
+  injection for the default `opencode-go*` pattern (the catalog route and every
+  declared variant) with the request's own session id; the
+  auto-review shape (no `sessionId`) resolving through `currentInitiator`; the
+  stable fallback when no context exists; existing headers, other providers
+  (including the sibling `opencode` route), other hosts, and the disabled
+  switch all passing through untouched; concurrent session isolation; live
+  switching; fetch restoration on dispose.
+- In the Host, activate the row and confirm the log line
+  `opencode-session-header: active (providers ..., hosts ...)`; with
+  `debug: true` each injected request logs
+  `[opencode-session-header] x-opencode-session: <id> -> <url>`. A live
+  provider round-trip cannot be proven from inside the plugin's own tests.
+
+## Notes and limits
+
+- The wrapper is installed process-wide but inert outside a captured stream
+  scope; it is reference-counted so HMR reloads and concurrent activations share
+  one patch, and it is removed when the last activation unloads.
+- It relies on the `openai` SDK defaulting to `globalThis.fetch` per request,
+  which the installed SDK does. If a future SDK pins a transport instance at
+  import time, the header would not be added and the route would fail as before.
+- Model discovery (`llm.discoverModels`) is a plain fetch outside a model call
+  and is left untouched.
+- The routes still need their own credential (`apiKeyEnv`) and `baseURL`; this
+  plugin only adds the header.

package/README.zh.md

@@ -0,0 +1,124 @@
+# dsh-opencode-go-x-session（OpenCode 会话头注入）
+
+Host-only 的 DeepSeek Harness 插件：为配置的 OpenCode provider 路由上的模型请求补上
+OpenCode Go 必需的 `x-opencode-session` 头，其他路由、其他主机、其他 provider 一概不碰。
+
+## 为什么需要
+
+OpenCode Go / Zen 要求每个推理请求携带 `x-opencode-session`（一条会话一个稳定标识，
+用于路由与提示词缓存亲和）。自 2026-09-05 起，缺这个头的请求会被拒绝：
+
+```
+400 {"type":"MissingSessionID","message":"... Request is missing x-opencode-session ..."}
+```
+
+在 DSH 里，有两类请求到达 OpenCode 时没有这个头：
+
+1. **自动审查（auto-review）及其他手写调用。** pi-ai 的目录 provider `opencode-go` 会从
+   `GenerateOptions.sessionId` 生成该头，`dsh-llm-pi-ai` 也会转发该字段，所以普通主模型
+   请求没问题。但自动审查的审查器调用 `ctx.llm.stream()` 时**不传** `sessionId`，目录
+   provider 没有值可写，于是审查请求 400、自动审查失败（`Auto review of tool "..." failed`）。
+2. **手写的 OpenCode 路由。** pi-ai 目录里没有的 provider key，或者写死 `api`/`baseURL`
+   的路由（例如 `opencode-go-free-none` / `opencode-go-audit-free-none`），由
+   `dsh-llm-pi-ai` 自己基于裸协议实现构建，不会套用 pi-ai 的 OpenCode 会话头包装，因此
+   连普通主模型请求也缺头。
+
+`llm-pi-ai` 没有按请求改头的入口：provider 的 `headers` 字段是配置里的静态字符串表，
+且适配器每次请求都会重建 pi-ai 的头对象。本插件在两条路径实际都经过的传输层补上这个头，
+并把作用范围限制在配置的路由与主机内。
+
+插件不改任何模型可见内容：不增提示词、不写会话事件、不改对话记录。
+
+## 工作原理
+
+1. 监听官方支持的 `llm/stream` 瀑布。请求的 provider 命中 `providers` 时，按以下顺序确定
+   会话 id：请求自身的 `sessionId`；外层模型调用作用域（嵌套调用）；通过
+   `ctx.agents.currentInitiator()` 取发起 Agent 的会话 id —— 自动审查的请求跑在被审查
+   Agent 的驱动链内，正是靠这一步拿到被审查会话的 id；最后才用配置的稳定
+   `fallbackSessionId`。随后把下游 chunk 流的每次拉取都放进携带该 id 的
+   `AsyncLocalStorage` 作用域。
+2. 包装 `globalThis.fetch`（`openai` SDK 在未传 `options.fetch` 时按请求解析的默认传输）。
+   只有当上面那种作用域生效、且 URL 主机命中 `hosts`、且请求尚无该头时才加头；其余请求
+   原参数放行。插件卸载或开关关闭时恢复原始 `fetch`。
+
+头里的值是 Harness 会话 id（`GenerateOptions.sessionId`）：同一会话跨轮次稳定、并发
+会话之间互不相同。其他 provider 的请求根本不进入作用域，因此内置路由和所有其他模型配置
+行为完全不变。
+
+## 配置项
+
+全部可选；每个字段都是 `volatile()`，这张表同时就是插件设置页。
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 总开关（统一插件开关）；`false` 立即移除 fetch 补丁，所有请求原样放行 |
+| `providers` | `['opencode-go*']` | 需要补头的 provider 路由；条目支持尾部 `*` 前缀匹配。默认一条 `opencode-go*`，覆盖目录路由 `opencode-go` 与所有 `opencode-go-*` 变体（新增变体无需改配置）；空数组 = 不生效 |
+| `hosts` | `['opencode.ai']` | 主机白名单（各条目含其子域）；空数组 = 不检查主机（路由指向代理端点时用） |
+| `fallbackSessionId` | `dsh-auto-review` | 请求、作用域、发起会话都拿不到会话 id 时使用的稳定兜底 id |
+| `debug` | `false` | 通过 Host logger 记录每次注入 |
+
+可以在插件设置页（设置 → 插件）里改，也可以覆盖 profile `cordis.patch.yml` 中插入的行：
+
+```yaml
+- id: opencode-session-header
+  config:
+    enabled: true
+    providers:
+      - 'opencode-go*'
+    hosts:
+      - opencode.ai
+    fallbackSessionId: dsh-auto-review
+    debug: false
+```
+
+## 安装
+
+从 npm 安装（推荐）：
+
+```sh
+dsh plugin --profile desktop add dsh-opencode-go-x-session
+```
+
+或从本仓库安装：先 clone，再用 Harness 插件管理器安装本目录（Web：插件 → 安装 bundle；
+工具：`install_bundle`，target 为本目录绝对路径）。
+
+```sh
+git clone https://github.com/pengpenglele/dsh-opencode-go-x-session-code.git
+```
+
+两种方式都会由 bundle patch 插入一行 Host 插件 `opencode-session-header`，对 profile
+下所有会话生效。
+
+按 `link:` / 本地目录安装时，插件依赖从本目录真实路径解析；先在本目录执行
+`pnpm install --ignore-workspace` 安装 `schemastery` 依赖。
+
+## 关闭插件（三种等价方式）
+
+- **设置页开关**：把 `enabled` 设为 `false`，下一次设置提交即移除 fetch 补丁，所有请求
+  原样放行，无需重启。
+- **插件行开关**：在插件管理器里禁用 `opencode-session-header` 行，整个插件卸载并恢复
+  原始 `fetch`。
+- **profile patch**：在补丁层给 `- id: opencode-session-header` 加 `disabled: true`。
+
+## 验证
+
+- 插件清单显示 **OpenCode Session Header / OpenCode 会话头注入** 及本图标与描述（en/zh）。
+- 插件设置页显示上表五个字段及默认值。
+- `npm test`（纯 Node，不需要 Host）用 mock 的 `fetch` 断言：默认 `opencode-go*` 覆盖
+  目录路由与所有 `opencode-go-*` 变体（各按请求自身会话 id 注入）；自动审查形态（无
+  `sessionId`）经 `currentInitiator` 取到会话 id；无上下文时用稳定兜底 id；已有头、
+  其他 provider（含同前缀以外的 `opencode`）、其他主机、关闭开关时全部原样放行；并发
+  会话隔离；实时开关；卸载后恢复 `fetch`。
+- Host 内启用后确认日志
+  `opencode-session-header: active (providers ..., hosts ...)`；`debug: true` 时每次注入
+  记录 `[opencode-session-header] x-opencode-session: <id> -> <url>`。插件自身测试无法
+  证明真实 provider 往返。
+
+## 说明与限制
+
+- 包装器安装在进程级，但在作用域外完全惰性；按引用计数共享一份补丁，HMR 重载与并发激活
+  不会重复包装，最后一个激活卸载时恢复原始 `fetch`。
+- 依赖 `openai` SDK 每次请求解析 `globalThis.fetch`（当前安装版本如此）。若未来 SDK 在
+  导入时固定传输实例，头就不会被补上，症状与修复前相同。
+- 模型发现（`llm.discoverModels`）是模型调用之外的普通 fetch，不在本插件作用范围。
+- 路由自身的凭据（`apiKeyEnv`）与 `baseURL` 仍由路由配置负责；本插件只补头。

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# Mount the OpenCode session-header plugin on the Host plane.
+#
+# This row is the plugin's identity and its default settings; the same fields
+# are served as the plugin's settings page (`enabled` is the unified switch).
+# Only the routes named in `providers` are ever touched, and only requests to
+# the hosts named in `hosts` can receive the header.
+#
+# `opencode-go*` is one trailing-`*` prefix pattern: it covers the `opencode-go`
+# catalog route and every hand-declared `opencode-go-*` variant, so a newly
+# added variant needs no config change here.
+- insert:
+    - id: opencode-session-header
+      name: 'dsh-opencode-go-x-session'
+      config:
+        enabled: true
+        providers:
+          - 'opencode-go*'
+        hosts:
+          - opencode.ai
+        fallbackSessionId: dsh-auto-review
+        debug: false

package/icon.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="OpenCode session header">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1b2430"/>
+      <stop offset="1" stop-color="#0d1117"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#38bdf8"/>
+      <stop offset="1" stop-color="#22c55e"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="url(#bg)"/>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="none" stroke="#2b3a4b" stroke-width="2"/>
+  <g stroke-linecap="round">
+    <line x1="14" y1="20" x2="34" y2="20" stroke="#3f4f63" stroke-width="4"/>
+    <line x1="14" y1="32" x2="50" y2="32" stroke="url(#accent)" stroke-width="4"/>
+    <line x1="14" y1="44" x2="26" y2="44" stroke="#3f4f63" stroke-width="4"/>
+  </g>
+  <circle cx="44" cy="44" r="7" fill="none" stroke="url(#accent)" stroke-width="3"/>
+  <circle cx="44" cy="44" r="2.4" fill="#22c55e"/>
+</svg>

package/index.js

@@ -0,0 +1,468 @@
+/**
+ * dsh-opencode-go-x-session — Host-only Harness plugin.
+ *
+ * OpenCode Go / Zen requires the `x-opencode-session` request header: a stable
+ * identifier for one conversation, used for routing and prompt-cache affinity.
+ * Since 2026-09-05 the gateway answers inference requests that lack it with
+ * `400 {"type":"MissingSessionID"}`.
+ *
+ * Inside DSH two request shapes reach OpenCode without the header:
+ *
+ * 1. **Auto-review / other hand-built calls.** pi-ai's catalog provider
+ *    (`opencode-go`) adds the header from `GenerateOptions.sessionId`, and
+ *    `dsh-llm-pi-ai` forwards that field. The auto-review reviewer calls
+ *    `ctx.llm.stream()` with no `sessionId`, so the header is missing and the
+ *    review fails closed (`Auto review of tool "..." failed`).
+ * 2. **Hand-declared OpenCode routes.** A route such as
+ *    `opencode-go-audit-free-none` — a provider key pi-ai's installed catalog
+ *    does not ship, or one that spells out `api`/`baseURL` — is built by
+ *    `dsh-llm-pi-ai` itself over the plain protocol implementation, which never
+ *    applies pi-ai's OpenCode session-header wrapper. Even its ordinary
+ *    main-model requests lack the header.
+ *
+ * This plugin adds that missing header, and only for the provider routes named
+ * in its config and the request hosts named in its config. It does not touch
+ * pi-ai, the adapter configuration, any other provider's requests, or any
+ * model-visible content (no prompt text, no session event).
+ *
+ * How it works, through the weakest extension points that suffice:
+ *
+ * 1. The supported `llm/stream` waterfall captures the conversation id of a
+ *    request whose provider is configured. Resolution order: the request's own
+ *    `sessionId`; the enclosing scope (nested model calls); the initiator
+ *    Agent's session through `ctx.agents.currentInitiator()` — this is what
+ *    gives an auto-review call, which runs inside the reviewed Agent's driver
+ *    chain, its conversation's id; finally the configured stable fallback.
+ *    The downstream chunk stream is wrapped so every pull runs inside an
+ *    `AsyncLocalStorage` scope carrying that id.
+ * 2. One transparent `globalThis.fetch` wrapper (the openai SDK's default
+ *    transport, resolved per request when `options.fetch` is not set) adds the
+ *    header while such a scope is active. Outside a scope, on another host, or
+ *    when the header is already present, the request is forwarded unchanged.
+ *    The wrapper is reference-counted, so HMR reloads and concurrent
+ *    activations share exactly one patch and the original transport returns
+ *    once the last activation unloads.
+ *
+ * Config fields (all optional, `enabled` is the live switch):
+ *   enabled           boolean   master switch (default true)
+ *   providers         string[]  provider routes to serve; entries may be exact
+ *                               ids or trailing-`*` prefix patterns
+ *                               (default: opencode-go*, the catalog route plus
+ *                               every opencode-go-* variant)
+ *   hosts             string[]  host allowlist, each also covering subdomains
+ *                               (default: opencode.ai); empty = no host check
+ *   fallbackSessionId string    stable id for calls that carry no session
+ *                               anywhere (default: dsh-auto-review)
+ *   debug             boolean   log every injection (default: false)
+ *
+ * @module dsh-opencode-go-x-session
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import z from '@deepseek-ai/schemastery'
+
+/** Stable Cordis plugin name used by Loader diagnostics. */
+export const name = 'opencode-session-header'
+
+/** The `llm` service must exist before the `llm/stream` waterfall can fire. */
+export const inject = ['llm']
+
+/** The request header OpenCode Go requires. */
+export const SESSION_HEADER = 'x-opencode-session'
+
+/** Global key so a reloaded module generation reuses one fetch patch and one scope store. */
+const SHARED_STATE = Symbol.for('dsh.opencode-session-header.state')
+
+/**
+ * Provider routes that speak the OpenCode protocol and therefore need the
+ * header. One trailing-`*` prefix pattern covers the catalog route and every
+ * hand-declared variant, so a new `opencode-go-*` route is served without
+ * touching this plugin. The dash before `*` is deliberately absent: the plain
+ * catalog route is `opencode-go`, which `opencode-go-*` would not match.
+ */
+export const DEFAULT_PROVIDERS = Object.freeze(['opencode-go*'])
+
+/** Hosts that may receive the header. An empty list means "no host check". */
+export const DEFAULT_HOSTS = Object.freeze(['opencode.ai'])
+
+/** Stable id for calls whose conversation cannot be identified. */
+export const DEFAULT_FALLBACK_SESSION_ID = 'dsh-auto-review'
+
+/**
+ * Plugin config. Every field is `volatile()`: the Host serves exactly these as
+ * this plugin's settings page (the unified plugin switch is `enabled`) and
+ * commits a settings write into the running activation without a remount.
+ */
+export const Config = z.object({
+  /** Master switch: false removes the fetch patch and stops all injection. */
+  enabled: z.boolean().default(true).volatile(),
+  /**
+   * Provider routes eligible for the header. An entry is an exact route id, or
+   * a trailing-`*` pattern (`"opencode-go*"`) matching a route-id prefix. The
+   * default is one pattern — `opencode-go*` — so the catalog route and every
+   * hand-declared `opencode-go-*` variant are covered without a list to keep.
+   */
+  providers: z.array(z.string()).default([...DEFAULT_PROVIDERS]).volatile(),
+  /**
+   * Host allowlist (host itself or any subdomain). Defaults to `opencode.ai`;
+   * an empty array removes the check, for routes pointed at a proxy endpoint.
+   */
+  hosts: z.array(z.string()).default([...DEFAULT_HOSTS]).volatile(),
+  /** Session id used only when neither the request nor a context carries one. */
+  fallbackSessionId: z.string().default(DEFAULT_FALLBACK_SESSION_ID).volatile(),
+  /** Log every injected request URL and session id (diagnostics). */
+  debug: z.boolean().default(false).volatile(),
+})
+
+/** Schema defaults for a bare mount (profile patch or test context). */
+export const DEFAULT_CONFIG = Object.freeze({
+  enabled: true,
+  providers: [...DEFAULT_PROVIDERS],
+  hosts: [...DEFAULT_HOSTS],
+  fallbackSessionId: DEFAULT_FALLBACK_SESSION_ID,
+  debug: false,
+})
+
+/**
+ * Read one activation field. The Loader hands volatile fields over as
+ * references, so a read goes through `get()`; a plain value (profile patch,
+ * test context) passes through, and an absent field falls back to its default.
+ * @param field - the config field as the Host handed it over.
+ * @param fallback - the schema default.
+ * @returns the effective value.
+ */
+function readField(field, fallback) {
+  if (field === undefined || field === null) return fallback
+  if (typeof field === 'object' && typeof field.get === 'function') {
+    const value = field.get()
+    return value === undefined ? fallback : value
+  }
+  return field
+}
+
+/**
+ * Normalize a configured string list. A non-array (or absent) value falls back
+ * to the default; an explicitly empty array is kept, because it means
+ * "nothing"/"no host check" and must not silently restore a default.
+ * @param value - raw config value.
+ * @param fallback - schema default list.
+ * @returns a clean string list.
+ */
+function readStringList(value, fallback) {
+  if (!Array.isArray(value)) return [...fallback]
+  return value
+    .filter((entry) => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+}
+
+/**
+ * Resolve the effective settings of this activation. Called at every use site,
+ * so a settings write or a profile-patch edit applies to the next request.
+ * @param config - the config the Host passed to the activation.
+ * @returns every field resolved against the schema defaults.
+ */
+export function resolveConfig(config) {
+  return {
+    enabled: readField(config?.enabled, DEFAULT_CONFIG.enabled) !== false,
+    providers: readStringList(readField(config?.providers, DEFAULT_CONFIG.providers), DEFAULT_PROVIDERS),
+    hosts: readStringList(readField(config?.hosts, DEFAULT_CONFIG.hosts), DEFAULT_HOSTS).map((host) =>
+      host.toLowerCase().replace(/^\*?\./, ''),
+    ),
+    fallbackSessionId: (() => {
+      const value = readField(config?.fallbackSessionId, DEFAULT_CONFIG.fallbackSessionId)
+      return typeof value === 'string' && value.trim().length > 0 ? value.trim() : DEFAULT_FALLBACK_SESSION_ID
+    })(),
+    debug: readField(config?.debug, DEFAULT_CONFIG.debug) === true,
+  }
+}
+
+/**
+ * Whether one provider route is covered by the configured patterns.
+ * @param provider - the route the request selects.
+ * @param patterns - exact route ids and/or trailing-`*` prefix patterns.
+ * @returns true when the route is covered.
+ */
+export function matchesProvider(provider, patterns) {
+  if (typeof provider !== 'string' || provider.length === 0) return false
+  return patterns.some(
+    (pattern) => pattern === provider || (pattern.endsWith('*') && provider.startsWith(pattern.slice(0, -1))),
+  )
+}
+
+/**
+ * Whether one request URL's host is on the allowlist. An empty list allows
+ * every host, because the provider match already scopes the injection.
+ * @param url - the request URL.
+ * @param hosts - lowercased host names; each also covers its subdomains.
+ * @returns true when the URL may receive the header.
+ */
+export function matchesHost(url, hosts) {
+  if (hosts.length === 0) return true
+  let hostname
+  try {
+    hostname = new URL(url).hostname.toLowerCase()
+  } catch {
+    return false
+  }
+  return hosts.some((host) => hostname === host || hostname.endsWith(`.${host}`))
+}
+
+/**
+ * The process-wide transport state shared by every plugin generation.
+ * @returns the shared state, creating it on first use.
+ */
+function sharedState() {
+  const holder = globalThis
+  if (holder[SHARED_STATE] === undefined) {
+    holder[SHARED_STATE] = {
+      /** Scope of the model request the current async chain belongs to. */
+      storage: new AsyncLocalStorage(),
+      /** Live activations that installed the middleware. */
+      refs: 0,
+      original: undefined,
+      patched: undefined,
+    }
+  }
+  return holder[SHARED_STATE]
+}
+
+// ---------------------------------------------------------------------------
+// Session-id resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the session id of the Agent whose driver chain is running this call.
+ * Auto-review is exactly such a call: it is built inside the reviewed Agent's
+ * tool execution and carries no `sessionId` of its own.
+ * @param ctx - the plugin context.
+ * @returns the initiator session id, or `undefined` when none is available.
+ */
+function initiatorSessionId(ctx) {
+  try {
+    const agents = typeof ctx.get === 'function' ? ctx.get('agents') : undefined
+    if (agents === undefined || agents === null) return undefined
+    const initiator = typeof agents.currentInitiator === 'function' ? agents.currentInitiator() : undefined
+    const id = initiator?.session?.id
+    if (typeof id === 'string' && id.length > 0) return id
+    const headerId = initiator?.session?.header?.id
+    return typeof headerId === 'string' && headerId.length > 0 ? headerId : undefined
+  } catch {
+    // No agents service, a disposed service, or no initiator boundary.
+    return undefined
+  }
+}
+
+/**
+ * Pick the stable per-conversation id for one model call.
+ * @param ctx - the plugin context (initiator fallback).
+ * @param options - resolved plugin settings.
+ * @param request - the `llm/stream` request options.
+ * @param inherited - the enclosing scope, when one model call nests inside another.
+ * @returns the id to send, or `undefined` to leave the call untouched.
+ */
+function resolveSessionId(ctx, options, request, inherited) {
+  const direct = request?.sessionId
+  if (direct !== undefined && direct !== null) {
+    const text = String(direct)
+    if (text.length > 0) return text
+  }
+  if (inherited !== undefined && typeof inherited.sessionId === 'string' && inherited.sessionId.length > 0) {
+    return inherited.sessionId
+  }
+  return initiatorSessionId(ctx) ?? options.fallbackSessionId
+}
+
+// ---------------------------------------------------------------------------
+// Stream wrapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-enter the captured scope for every pull of the downstream chunk stream, so
+ * the fetch calls that produce those chunks see the session id. The inner
+ * iterator is created inside the scope as well, which covers transports that
+ * start their request at iteration time.
+ * @param produced - whatever the next waterfall listener returned.
+ * @param store - the scope value for this call.
+ * @param storage - the shared AsyncLocalStorage.
+ * @returns an iterable that behaves like `produced`.
+ */
+function wrapIterable(produced, store, storage) {
+  if (produced === null || produced === undefined) return produced
+  if (typeof produced[Symbol.asyncIterator] !== 'function') return produced
+  const iterator = produced[Symbol.asyncIterator]()
+  const bind = (method) => {
+    const fn = iterator[method]
+    return typeof fn === 'function' ? (...args) => storage.run(store, () => fn.apply(iterator, args)) : undefined
+  }
+  const wrapped = {
+    [Symbol.asyncIterator]() {
+      return this
+    },
+    next: bind('next'),
+  }
+  const returnMethod = bind('return')
+  if (returnMethod !== undefined) wrapped.return = returnMethod
+  const throwMethod = bind('throw')
+  if (throwMethod !== undefined) wrapped.throw = throwMethod
+  return wrapped
+}
+
+// ---------------------------------------------------------------------------
+// Fetch interception
+// ---------------------------------------------------------------------------
+
+/** Extract the target URL of a `fetch` call without consuming the input. */
+export function requestUrl(input) {
+  if (typeof input === 'string') return input
+  if (typeof URL !== 'undefined' && input instanceof URL) return input.href
+  if (input !== null && typeof input === 'object' && typeof input.url === 'string') return input.url
+  return undefined
+}
+
+/**
+ * Build the fetch call that carries the session header, or `undefined` when the
+ * request must be forwarded unchanged.
+ * @param input - fetch's first argument (URL string, URL, or Request).
+ * @param init - fetch's second argument.
+ * @param store - the active scope.
+ * @returns the arguments to pass to the real fetch, or undefined to forward.
+ */
+export function addSessionHeader(input, init, store) {
+  const url = requestUrl(input)
+  if (url === undefined || !matchesHost(url, store.hosts)) return undefined
+  const isRequest = typeof Request !== 'undefined' && input instanceof Request
+  // Reproduce fetch's own precedence: init.headers replaces a Request's headers
+  // entirely; without init.headers the Request's headers are the base.
+  const headers =
+    init?.headers !== undefined
+      ? new Headers(init.headers)
+      : new Headers(isRequest ? input.headers : undefined)
+  if (headers.has(store.headerName)) return undefined
+  headers.set(store.headerName, store.sessionId)
+  if (isRequest) return [new Request(input, { ...(init ?? {}), headers })]
+  return [input, { ...(init ?? {}), headers }]
+}
+
+/**
+ * Install the transparent fetch wrapper once and count live owners.
+ * @param state - the shared state.
+ * @returns the release function for this owner.
+ */
+function acquireFetchPatch(state) {
+  if (typeof globalThis.fetch !== 'function') {
+    throw new Error('dsh-opencode-go-x-session: globalThis.fetch is unavailable')
+  }
+  if (state.refs === 0) {
+    state.original = globalThis.fetch
+    state.patched = createPatchedFetch(state.original, state.storage)
+    globalThis.fetch = state.patched
+  }
+  state.refs += 1
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    state.refs -= 1
+    if (state.refs > 0) return
+    state.refs = 0
+    if (globalThis.fetch === state.patched) globalThis.fetch = state.original
+    state.patched = undefined
+    state.original = undefined
+  }
+}
+
+/**
+ * Build the fetch wrapper. It only changes a request while a scope created by
+ * this plugin is active, so every other caller sees the original transport.
+ * @param originalFetch - the transport captured at install time.
+ * @param storage - the shared AsyncLocalStorage.
+ * @returns the wrapper.
+ */
+function createPatchedFetch(originalFetch, storage) {
+  return function fetchWithOpenCodeSessionHeader(input, init) {
+    let store
+    try {
+      store = storage.getStore()
+    } catch {
+      store = undefined
+    }
+    if (store === undefined || store === null) return Reflect.apply(originalFetch, this, [input, init])
+    let rewritten
+    try {
+      rewritten = addSessionHeader(input, init, store)
+    } catch {
+      // Header bookkeeping must never break a model call.
+      return Reflect.apply(originalFetch, this, [input, init])
+    }
+    if (rewritten === undefined) return Reflect.apply(originalFetch, this, [input, init])
+    store.log?.(`${store.headerName}: ${store.sessionId} -> ${String(requestUrl(input) ?? '?')}`)
+    return Reflect.apply(originalFetch, this, rewritten)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mount
+// ---------------------------------------------------------------------------
+
+/**
+ * Mount the plugin: keep one fetch patch in step with the effective config and
+ * scope every covered model call.
+ * @param ctx - the plugin context (carries `llm`).
+ * @param config - the row config, with volatile fields as references.
+ */
+export function apply(ctx, config) {
+  const state = sharedState()
+  const settings = () => resolveConfig(config)
+  let release
+
+  /** Install the fetch patch while enabled, remove it while disabled. */
+  const sync = () => {
+    const current = settings()
+    if (current.enabled && release === undefined) {
+      release = acquireFetchPatch(state)
+      ctx.logger?.info?.(
+        `opencode-session-header: active (providers ${current.providers.join(', ')}, hosts ${current.hosts.join(', ') || '*'})`,
+      )
+    } else if (!current.enabled && release !== undefined) {
+      release()
+      release = undefined
+      ctx.logger?.info?.('opencode-session-header: disabled by config; requests pass through')
+    }
+  }
+
+  ctx.effect(() => {
+    sync()
+    return () => {
+      release?.()
+      release = undefined
+    }
+  }, 'opencode-session-header: fetch transport')
+
+  // Volatile settings writes commit in place; re-evaluate the switch.
+  ctx.on('loader/volatile-update', () => sync())
+
+  ctx.on('llm/stream', (request, next) => {
+    if (request === null || typeof request !== 'object') return next()
+    const current = settings()
+    if (!current.enabled) return next()
+    if (!matchesProvider(request.provider, current.providers)) return next()
+    let inherited
+    try {
+      inherited = state.storage.getStore()
+    } catch {
+      inherited = undefined
+    }
+    const sessionId = resolveSessionId(ctx, current, request, inherited)
+    if (sessionId === undefined) return next()
+    const store = {
+      sessionId,
+      headerName: SESSION_HEADER,
+      hosts: current.hosts,
+      provider: request.provider,
+      log: current.debug ? (message) => ctx.logger?.debug?.('[opencode-session-header] ' + message) : undefined,
+    }
+    const produced = state.storage.run(store, () => next())
+    return wrapIterable(produced, store, state.storage)
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OpenCode Session Header",
+    "description": "Adds OpenCode Go's required x-opencode-session header to model requests on the configured OpenCode routes (including auto-review and hand-declared routes), with a live on/off switch."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OpenCode 会话头注入",
+    "description": "为配置的 OpenCode 路由上的模型请求补上 OpenCode Go 必需的 x-opencode-session 头（含自动审查与手写路由），并带实时开关。"
+  }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "dsh-opencode-go-x-session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Adds OpenCode Go's required x-opencode-session header to model requests of the configured OpenCode routes (including auto-review and hand-declared routes), with a live on/off switch.",
+  "author": "pengpenglele",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pengpenglele/dsh-opencode-go-x-session-code.git"
+  },
+  "homepage": "https://github.com/pengpenglele/dsh-opencode-go-x-session-code#readme",
+  "bugs": {
+    "url": "https://github.com/pengpenglele/dsh-opencode-go-x-session-code/issues"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "README.zh.md"
+  ],
+  "icon": "./icon.svg",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "opencode",
+    "opencode-go",
+    "x-opencode-session",
+    "missing-session-id",
+    "session-affinity",
+    "prompt-cache"
+  ],
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.2.1-rc.2"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "scripts": {
+    "test": "node test/plugin.test.mjs",
+    "prepublishOnly": "node test/plugin.test.mjs"
+  },
+  "license": "MIT"
+}