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

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,218 @@
-# 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.
+[![npm version](https://img.shields.io/npm/v/dsh-opencode-go-x-session.svg)](https://www.npmjs.com/package/dsh-opencode-go-x-session)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-opencode-go-x-session.svg)](https://www.npmjs.com/package/dsh-opencode-go-x-session)
+[![license](https://img.shields.io/npm/l/dsh-opencode-go-x-session.svg)](./LICENSE)
+
+[中文文档](./README.zh.md) · English
+
+A host-only [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that adds
+OpenCode Go's required `x-opencode-session` request header to model requests on
+the configured OpenCode provider routes — including the requests the official
+auto-review feature builds by hand — and to no other route or host.
+
+## Do you need it?
+
+OpenCode Go / Zen requires every inference request to carry
+`x-opencode-session`: a stable identifier per conversation, used for routing and
+prompt-cache affinity. Since 2026-09-05 requests without it are rejected:
+
+```
+400 {"type":"MissingSessionID","message":"... Request is missing x-opencode-session ..."}
+```
+
+Install this plugin if you see either of these inside DSH:
+
+- `400 MissingSessionID` on an `opencode-go` / `opencode-go-*` route, or
+- `Auto review of tool "..." failed` when the reviewed session uses an OpenCode Go
+  route (the reviewer call carries no `sessionId`, so pi-ai's own OpenCode
+  wrapper has nothing to write).
+
+DSH sends the header natively only on pi-ai catalog requests that carry a
+`sessionId`. Auto-review calls and hand-declared routes
+(`opencode-go-free-none`, `opencode-go-audit-free-none`, custom keys) lack it.
+This plugin fills that gap at the transport layer both paths actually use.
+
+## Requirements
+
+| Requirement | Value |
+|---|---|
+| DSH | `>= 0.2.1-rc.2` (declared as `dsh.engines.dsh`) |
+| Node.js | `>= 22.19.0` |
+| Route | an OpenCode Go provider route (`opencode-go` or `opencode-go-*`) configured with its own `apiKeyEnv` / `baseURL` |
+| Host | requests go to `opencode.ai` (subdomains included) |
+
+## Install
+
+### Option A — DSH Web UI (recommended)
+
+1. Open DSH → **Plugins** (插件) → **Add plugin** (添加插件).
+2. Enter the package name:
+
+   ```
+   dsh-opencode-go-x-session
+   ```
+
+3. Install, then **fully restart DSH**. Bundle layers are composed at startup, so
+   the plugin does not load until DSH restarts.
+
+### Option B — CLI
+
+```sh
+dsh plugin --profile desktop add dsh-opencode-go-x-session
+```
+
+Use your own profile name instead of `desktop` if you boot another one. Then
+fully restart DSH.
+
+### Option C — from this repository (development)
+
+```sh
+git clone https://github.com/pengpenglele/dsh-opencode-go-x-session-code.git
+```
+
+Then install the cloned directory as a bundle (Web: Plugins → Install bundle;
+agent tool: `install_bundle` with the directory's absolute path), or install it
+as a local link:
+
+```sh
+dsh plugin --profile desktop add link:/absolute/path/to/dsh-opencode-go-x-session-code
+```
+
+A `link:` installation resolves the plugin's dependencies from its real path, so
+run `pnpm install --ignore-workspace` in that directory first (it needs
+`@deepseek-ai/schemastery`).
+
+Either way the bundle patch inserts one host row, `opencode-session-header`,
+into the profile. It applies to every session in that profile.
+
+## Usage
+
+### It works with no configuration
+
+After installation and a restart, requests on `opencode-go` and every
+`opencode-go-*` route to `opencode.ai` receive the header automatically. The
+value is the DSH session id, so it is stable across the turns of one conversation
+and distinct between concurrent conversations.
+
+For auto-review, the reviewer request runs inside the reviewed agent's driver
+chain, so the plugin resolves that conversation's id through
+`ctx.agents.currentInitiator()` — the review keeps its prompt-cache affinity
+instead of falling back to a shared id.
+
+### Settings
+
+Settings → Plugins → **OpenCode Session Header**. All fields are optional and
+every field is live (`volatile()`): a settings save applies to the next request
+without a restart.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Master switch; `false` removes the fetch patch immediately and every request passes through untouched |
+| `providers` | `['opencode-go*']` | Provider routes served by the plugin; entries may be exact ids or trailing-`*` prefix patterns. The default covers the `opencode-go` catalog route and every `opencode-go-*` variant. An empty list disables injection |
+| `hosts` | `['opencode.ai']` | Host allowlist; each entry also covers its subdomains. An empty list removes the host check (for a proxy endpoint) |
+| `fallbackSessionId` | `dsh-auto-review` | Stable id used only when neither the request, the enclosing scope, nor an initiator session id exists |
+| `debug` | `false` | Log every injection through the host logger |
+
+### Custom routes and proxy endpoints
+
+- A new `opencode-go-something` route is covered automatically — no config change.
+- The plain `opencode` (non-Go) route is **not** covered by the default pattern;
+  add `opencode` to `providers` if you use it.
+- If your OpenCode endpoint is a proxy with another hostname, either add that
+  hostname to `hosts` or set `hosts` to `[]` to disable the host check. The
+  provider list still scopes injection.
+
+### Check that it is working
+
+1. The DSH startup log shows:
+
+   ```
+   opencode-session-header: active (providers opencode-go*, hosts opencode.ai)
+   ```
+
+2. Turn on `debug` and start a conversation on an OpenCode Go route; every
+   injected request logs:
+
+   ```
+   [opencode-session-header] x-opencode-session: <session-id> -> <url>
+   ```
+
+3. The original symptom disappears: no more `400 MissingSessionID`, and
+   auto-review on an OpenCode Go model no longer fails with
+   `Auto review of tool "..." failed`.
+
+## Disable / uninstall
+
+- **Settings switch** — set `enabled: false`; the fetch patch is removed and
+  requests pass through untouched. No restart.
+- **Plugin row** — disable the `opencode-session-header` row in the plugin
+  manager; the whole plugin unloads and the original `fetch` is restored.
+- **Profile patch** — add `- id: opencode-session-header` with
+  `disabled: true` under your profile patch layer.
+- **Uninstall** — remove it in the plugin manager, or run:
+
+  ```sh
+  dsh plugin --profile desktop remove dsh-opencode-go-x-session
+  ```
+
+  Then restart DSH.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| Still `400 MissingSessionID` | Route not covered: add the exact route id (or a matching `something*` pattern) to `providers` |
+| Still `400` on a custom endpoint | Host not allowlisted: add the real hostname to `hosts`, or set `hosts: []` |
+| Settings page missing the plugin | The plugin is not loaded: restart DSH and check the startup log line |
+| Plugin refuses to load | DSH is older than `0.2.1-rc.2`; upgrade DSH |
+| Header never injected although enabled | Another plugin wraps `globalThis.fetch` after this one and bypasses the chain; or the route already carries a static `x-opencode-session` header (existing headers always win — remove the static one) |
+| Auto-review still fails | The reviewer uses the session's model; make sure that route is in `providers`, and that the plugin is enabled |
+
+## How it works
+
+1. It listens on the supported `llm/stream` waterfall. For a request whose
+   provider matches `providers`, 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 the conversation it is reviewing); finally
+   the configured `fallbackSessionId`. The downstream chunk stream is re-emitted
+   so every pull runs inside an `AsyncLocalStorage` scope carrying that id.
+2. It wraps `globalThis.fetch` (the `openai` SDK's default transport). Inside a
+   captured scope it adds the header when it is absent and the URL host is
+   allowlisted; every other request keeps the original arguments. The wrapper is
+   reference-counted, so HMR reloads and concurrent activations share one patch,
+   and it is removed when the last activation unloads.
+
+The plugin changes no model-visible content: no prompt text, no session event,
+no transcript entry.
+
+## Notes and limits
+
+- It relies on the `openai` SDK resolving `globalThis.fetch` per request (the
+  installed SDK constructs one client per model call). If a future version 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.
+- Routes still need their own credential (`apiKeyEnv`) and `baseURL`; this plugin
+  only adds the header.
+- Calls with no session context share the stable `fallbackSessionId`. That keeps
+  them working, but those calls share one affinity id rather than one per
+  conversation.
+
+## Development
+
+```sh
+npm test    # 22 host-free tests against a mocked fetch
+```
+
+The tests cover injection for the default `opencode-go*` pattern, the
+auto-review shape (no `sessionId`, resolved through the initiator), the stable
+fallback, existing headers, other providers (including the sibling `opencode`),
+other hosts, concurrent session isolation, live switching, and fetch restoration
+on dispose.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,189 @@
+# dsh-opencode-go-x-session（OpenCode 会话头注入）
+
+[![npm version](https://img.shields.io/npm/v/dsh-opencode-go-x-session.svg)](https://www.npmjs.com/package/dsh-opencode-go-x-session)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-opencode-go-x-session.svg)](https://www.npmjs.com/package/dsh-opencode-go-x-session)
+[![license](https://img.shields.io/npm/l/dsh-opencode-go-x-session.svg)](./LICENSE)
+
+中文 · [English](./README.md)
+
+Host-only 的 [DeepSeek Harness](https://github.com/deepseek-ai/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-go` / `opencode-go-*` 路由时报 `400 MissingSessionID`；
+- 被审查的会话用的是 OpenCode Go 路由时，工具调用报
+  `Auto review of tool "..." failed`（审查器调用不带 `sessionId`，pi-ai 自带的 OpenCode 包装
+  没有值可写）。
+
+DSH 只会在**带 `sessionId` 的 pi-ai 目录路由请求**上原生发送这个头。自动审查的调用和手写的
+路由（`opencode-go-free-none`、`opencode-go-audit-free-none`、自定义 key）都没有它。本插件在
+两条路径实际都经过的传输层补上这个缺口。
+
+## 前置条件
+
+| 要求 | 值 |
+|---|---|
+| DSH | `>= 0.2.1-rc.2`（由 `dsh.engines.dsh` 声明） |
+| Node.js | `>= 22.19.0` |
+| 路由 | 已配置一条 OpenCode Go provider 路由（`opencode-go` 或 `opencode-go-*`），带自己的 `apiKeyEnv` / `baseURL` |
+| 主机 | 请求目标是 `opencode.ai`（含子域） |
+
+## 安装
+
+### 方式 A — DSH Web 界面（推荐）
+
+1. 打开 DSH → 左侧 **插件** → **添加插件**
+2. 输入包名：
+
+   ```
+   dsh-opencode-go-x-session
+   ```
+
+3. 安装后**完全重启 DSH**。bundle 层是在启动时组合的，不重启插件不会加载。
+
+### 方式 B — 命令行
+
+```sh
+dsh plugin --profile desktop add dsh-opencode-go-x-session
+```
+
+如果你启动的不是 `desktop` profile，把 `desktop` 换成你的 profile 名。装完**完全重启 DSH**。
+
+### 方式 C — 从本仓库安装（开发）
+
+```sh
+git clone https://github.com/pengpenglele/dsh-opencode-go-x-session-code.git
+```
+
+把 clone 下来的目录作为 bundle 安装（Web：插件 → 安装 bundle；agent 工具：`install_bundle`，
+target 为该目录绝对路径），或者按本地 link 安装：
+
+```sh
+dsh plugin --profile desktop add link:/absolute/path/to/dsh-opencode-go-x-session-code
+```
+
+按 `link:` 安装时，插件依赖从本目录真实路径解析，所以要先在该目录执行
+`pnpm install --ignore-workspace`（需要 `@deepseek-ai/schemastery`）。
+
+三种方式都会由 bundle patch 向 profile 插入一行 Host 插件 `opencode-session-header`，对该
+profile 下所有会话生效。
+
+## 使用
+
+### 装完即用，无需配置
+
+安装并重启后，`opencode-go` 及所有 `opencode-go-*` 路由发往 `opencode.ai` 的请求会自动带上
+这个头。头的值是 DSH 会话 id：同一会话跨轮次稳定，并发会话之间互不相同。
+
+自动审查的审查请求跑在被审查 Agent 的驱动链内，插件通过 `ctx.agents.currentInitiator()`
+拿到该会话的 id，所以审查请求也能保持自己的缓存亲和，而不是退化成共享的固定值。
+
+### 设置项
+
+设置 → 插件 → **OpenCode Session Header**。所有字段均可选，且都是实时的（`volatile()`）：
+保存后下一次请求就生效，无需重启。
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 总开关；`false` 立即移除 fetch 补丁，所有请求原样放行 |
+| `providers` | `['opencode-go*']` | 需要补头的 provider 路由；条目可写精确 id，也可用尾部 `*` 前缀匹配。默认覆盖目录路由 `opencode-go` 与所有 `opencode-go-*` 变体；空数组 = 不生效 |
+| `hosts` | `['opencode.ai']` | 主机白名单（各条目含其子域）；空数组 = 不检查主机（路由指向代理端点时用） |
+| `fallbackSessionId` | `dsh-auto-review` | 请求、外层作用域、发起会话都拿不到会话 id 时使用的稳定兜底 id |
+| `debug` | `false` | 通过 Host logger 记录每次注入 |
+
+### 自定义路由与代理端点
+
+- 新增 `opencode-go-xxx` 路由会被默认通配自动覆盖，不用改配置。
+- 裸 `opencode`（非 Go）路由**不在**默认范围内；需要的话把 `opencode` 加进 `providers`。
+- 如果 OpenCode 端点走代理、域名不同：把该域名加到 `hosts`，或把 `hosts` 设为 `[]` 关闭主机
+  检查。provider 列表仍然限制注入范围。
+
+### 确认是否生效
+
+1. DSH 启动日志出现：
+
+   ```
+   opencode-session-header: active (providers opencode-go*, hosts opencode.ai)
+   ```
+
+2. 打开 `debug`，在 OpenCode Go 路由上发一条消息，每次注入都会记录：
+
+   ```
+   [opencode-session-header] x-opencode-session: <session-id> -> <url>
+   ```
+
+3. 原来的症状消失：不再有 `400 MissingSessionID`；自动审查工具调用不再报
+   `Auto review of tool "..." failed`。
+
+## 关闭 / 卸载
+
+- **设置页开关**：把 `enabled` 设为 `false`，fetch 补丁被移除，请求原样放行，无需重启。
+- **插件行开关**：在插件管理器里禁用 `opencode-session-header` 行，整个插件卸载并恢复原始
+  `fetch`。
+- **profile patch**：在 profile 补丁层给 `- id: opencode-session-header` 加
+  `disabled: true`。
+- **卸载**：在插件管理器里移除，或执行：
+
+  ```sh
+  dsh plugin --profile desktop remove dsh-opencode-go-x-session
+  ```
+
+  然后重启 DSH。
+
+## 故障排查
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| 仍然 `400 MissingSessionID` | 路由没命中：把确切的 route id（或匹配的 `something*` 模式）加进 `providers` |
+| 自定义端点仍然 400 | 主机没命中：把真实域名加进 `hosts`，或设 `hosts: []` |
+| 设置页看不到插件 | 插件没加载：重启 DSH 并检查启动日志里有没有那行 `active` |
+| 插件加载被拒 | DSH 低于 `0.2.1-rc.2`，升级 DSH |
+| 已启用但始终没注入 | 有别的插件在本插件之后再包 `globalThis.fetch`、绕过了链路；或者路由里写死了静态 `x-opencode-session` 头（已有头优先，请删掉静态头） |
+| 自动审查仍失败 | reviewer 用的是会话当前模型：确认该路由在 `providers` 内，且插件处于启用状态 |
+
+## 工作原理
+
+1. 监听官方支持的 `llm/stream` 瀑布。请求的 provider 命中 `providers` 时，按以下顺序确定会话
+   id：请求自身的 `sessionId`；外层模型调用作用域（嵌套调用）；通过
+   `ctx.agents.currentInitiator()` 取发起 Agent 的会话 id（自动审查正是靠这一步拿到被审查
+   会话）；最后用配置的 `fallbackSessionId`。下游 chunk 流的每次拉取都放进携带该 id 的
+   `AsyncLocalStorage` 作用域。
+2. 包装 `globalThis.fetch`（`openai` SDK 的默认传输）。只在上述作用域生效、URL 主机命中
+   `hosts`、且请求尚无该头时加头；其余请求原参数放行。包装器按引用计数共享，HMR 重载与并发
+   激活不会重复包装，最后一个激活卸载时恢复原始 `fetch`。
+
+插件不改任何模型可见内容：不增提示词、不写会话事件、不改对话记录。
+
+## 说明与限制
+
+- 依赖 `openai` SDK 每次请求解析 `globalThis.fetch`（当前安装版本每次模型调用都会新建
+  client）。若未来版本在导入时固定传输实例，头就不会被补上，症状与修复前相同。
+- 模型发现（`llm.discoverModels`）是模型调用之外的普通 fetch，不在本插件作用范围。
+- 路由自身的凭据（`apiKeyEnv`）与 `baseURL` 仍由路由配置负责；本插件只补头。
+- 完全拿不到会话上下文的调用会共用 `fallbackSessionId`：能正常发出去，但这些调用共享一个
+  亲和 id，而不是各自一条会话。
+
+## 开发
+
+```sh
+npm test    # 22 条无需 Host 的测试，针对 mock 的 fetch
+```
+
+测试覆盖：默认 `opencode-go*` 通配注入、自动审查形态（无 `sessionId`，经 initiator 解析）、
+稳定兜底 id、已有头不覆盖、其他 provider（含裸 `opencode`）、其他主机、并发会话隔离、实时
+开关、卸载后恢复 `fetch`。
+
+## 许可证
+
+MIT

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.1",
+  "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"
+}