@karoc/dsh-smoothly-opencode-session 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Process rule:** every released version MUST have a matching entry in this
+> file AND its user-visible behavior reflected in the README (both `README.md`
+> and `README.zh.md`) — all in the same release. The automated gate
+> `pnpm release:check` (also run by `prepublishOnly`) blocks publishing until
+> every item passes. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## [0.1.0] - 2026-09-14
+
+### Added
+
+- **Initial release — OpenCode session header injection.** External DeepSeek
+  Harness host plugin that attaches the OpenCode-required `x-opencode-session`
+  header to model calls routed to OpenCode / OpenCode Go provider routes
+  (fixes `400 MissingSessionID`, in effect for OpenCode Go since 2026-09-05;
+  tracked in deepseek-harness discussion #5495).
+- Observes the documented `llm/stream` waterfall for `provider` + `sessionId`
+  and injects the header via one patched `globalThis.fetch` inside an
+  `AsyncLocalStorage` store (options are deep-frozen, so mutation is off the
+  table for external plugins).
+- Per-conversation stability: `mode: session-id` (default) reuses the DSH
+  session id — stable across turns, compaction, retries and restarts, unique
+  per conversation — which keeps OpenCode's backend affinity / prompt-cache
+  working; `mode: uuid` derives an opaque process-stable UUID per session.
+- Config-driven, fully optional row config (`providers` / `mode` / `debug` /
+  `debugFile`); defaults cover the pi-ai catalog ids `opencode` and
+  `opencode-go`, custom route keys (e.g. `opencode-go-self`) are added through
+  a same-id profile patch entry.
+- Requests that already carry the header, non-OpenCode providers, and
+  session-id-less auxiliary calls pass through untouched; discovery probes
+  are not affected.
+- Fiber-scoped cleanup: unload / update / stop restores the original
+  `globalThis.fetch` and removes the listener.
+- Bilingual README, CHANGELOG, CONTRIBUTING, release gate
+  (`release-check.mjs`) and post-publish verification
+  (`post-publish-check.mjs`), `node --test` unit tests for the pure helpers.

package/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+Thanks for contributing to `@karoc/dsh-smoothly-opencode-session`. This is a
+small external host plugin, but it is **published to npm and distributed to
+users** — so releases must be coherent: a version bump without its
+documentation is a defect.
+
+## Development
+
+Prerequisites: Node.js ≥ 18, [pnpm](https://pnpm.io).
+
+```sh
+pnpm install      # installs dev deps (tsdown, @deepseek-ai/cordis types, @types/node)
+pnpm bundle       # emits lib/index.js
+npm test          # node --test tests/*.test.ts (runs TypeScript directly)
+```
+
+- `src/index.ts` is the host plugin: an `llm/stream` waterfall listener plus a
+  single patched `globalThis.fetch`. It reads `provider` + `sessionId` off the
+  waterfall options and injects `x-opencode-session` into the outbound request
+  via an `AsyncLocalStorage` store (options are deep-frozen for LOOP-built
+  requests; external plugins cannot mutate them).
+- Keep the plugin **zero-dependency at runtime**: only Node built-ins may be
+  imported as values. `@deepseek-ai/cordis` is a devDependency for types only
+  (`import type`), erased from the build.
+- The local `declare module '@deepseek-ai/cordis'` augmentation mirrors the
+  official `llm/stream` Events merge published by `@deepseek-ai/dsh-llm`; keep
+  its signature in sync with `packages/llm/llm/src/index.ts`.
+- Copy is bilingual: any user-visible text appears in both `README.md` and
+  `README.zh.md` (same `##`/`###` section set — the release gate verifies the
+  counts match).
+
+## What every release must contain
+
+A release is ONE coherent change — code and its documentation land together.
+Splitting a feature's docs into a later "docs release" is a defect. Every
+release MUST include, in the SAME release:
+
+1. **Code change** — implemented, and `pnpm bundle` succeeds (`lib/` produced).
+2. **README.md (English)** — describes the new user-visible behavior.
+3. **README.zh.md (Chinese)** — mirrors the same sections (same `##` section
+   set; the release gate verifies the section counts match).
+4. **CHANGELOG.md** — an entry under `## [<version>]` for this release, as the
+   latest released entry (Keep a Changelog + SemVer).
+5. **Version** — `package.json` version equals the CHANGELOG entry and the git
+   tag `v<version>` on HEAD.
+6. **Git** — working tree clean (everything committed), tag pushed.
+7. **Not re-published** — the version must not already exist on npm.
+
+## Verification — the release gate
+
+`pnpm release:check` (also wired into `prepack` and `prepublishOnly`) verifies
+every item above and **blocks** `npm publish` / `npm pack` until all pass.
+`scripts/post-publish-check.mjs` runs via `postpublish` and confirms the
+release actually landed on the registry (polling through index eventual
+consistency) and that the published tarball contains every expected file.
+
+Known bypasses, documented on purpose:
+
+- `npm publish --ignore-scripts` skips all gates. This is an explicit user
+  override; do not use it.
+- Tarballs packed outside this repo (`npm pack` elsewhere) skip `prepack`.
+
+## Publishing (maintainer, human step — 2FA)
+
+The npm account has two-factor authentication, so publishing is a manual,
+human step: `npm login` (2FA) → `npm publish`. Everything else must be
+prepared to the point of "one command by the user": clean tree, version +
+tag on HEAD, `release:check` passing, `npm pack --dry-run` contents reviewed.
+
+After a successful publish, the `postpublish` script auto-verifies the
+registry; if the index is still catching up it polls (up to ~60s) before
+judging. Do **not** re-publish the same version without checking — it may
+already be live.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 karoc
+
+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

@@ -0,0 +1,176 @@
+# Smoothly OpenCode Session (Smoothly OCS)
+
+**思磨力 OpenCode 会话头** — an external [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+(DSH) **host plugin** that attaches the OpenCode-required `x-opencode-session`
+request header to model calls routed to **OpenCode / OpenCode Go** provider
+routes, using a stable per-conversation id.
+
+Since **2026-09-05** OpenCode's relay rejects any inference request that lacks
+this header (`400 MissingSessionID`); the value is what pins a conversation to
+one upstream backend and keeps OpenCode's prompt cache warm across its turns
+(tracked upstream in [deepseek-harness discussion #5495](https://github.com/deepseek-ai/deepseek-harness/discussions/5495)).
+
+## What it does
+
+- **Fixes the 400** by always attaching `x-opencode-session` to requests that
+  are routed to a configured OpenCode(Go) provider.
+- **Keeps the cache/affinity benefit** by using a value that is unique **per
+  conversation** and stable across that conversation's turns, compaction,
+  retries and process restarts (by default the DSH session id itself — the
+  same identity the official DeepSeek adapter already sends as
+  `x-deepseek-harness-session-id`).
+- **Leaves everything else untouched**: other providers, requests that already
+  carry the header, and requests without a session id pass through exactly as
+  before.
+
+## How it works
+
+The plugin listens on the **`llm/stream` waterfall** — a documented DSH
+extension seam ("Waterfall around every streaming model call"). LOOP-built
+request options are deep-frozen (mutation throws), so the header cannot be
+added by rewriting options; instead the plugin:
+
+1. reads `provider` + `sessionId` off the waterfall options for each call;
+2. drives the downstream stream's pulls inside an `AsyncLocalStorage` store;
+3. patches `globalThis.fetch` once, and while such a store is active merges
+   `x-opencode-session: <value>` onto the outgoing request (unless the request
+   already carries the header — an existing value always wins).
+
+Both registrations are fiber-scoped (`ctx.on` listener + `ctx.effect`
+disposer), so stopping / updating / unloading the plugin restores the original
+`fetch` and removes the listener.
+
+### Why the fetch-level injection
+
+There is no official seam for an external plugin to add per-request headers to
+adapter requests (options are deep-frozen; provider `headers` config is static
+and deployment-owned). The fetch shim is the only external-plugin mechanism
+that can attach a **per-conversation** value. The correct long-term fix lives
+in the provider adapter itself (pi-ai); this plugin is the stopgap until that
+ships. See [Notes / limitations](#notes--limitations).
+
+## Configuration
+
+The row's `config` (in the bundle's `cordis.patch.yml`, or overridden per
+profile) is entirely optional — the code fills defaults for missing keys.
+
+```yaml
+- insert:
+    - id: dsh-smoothly-opencode-session
+      name: '@karoc/dsh-smoothly-opencode-session'
+      config:
+        providers: [opencode, opencode-go]
+        mode: session-id
+        debug: false
+```
+
+### providers
+
+Provider route keys whose requests receive the header. Defaults to the pi-ai
+catalog ids `opencode` and `opencode-go`. If you serve OpenCode under a custom
+provider route key (e.g. `opencode-go-self` in `llm-pi-ai`), add that key.
+
+### mode
+
+- `session-id` (default) — header value = the DSH session id of the model
+  call. Unique per conversation, stable across turns, compaction, retries and
+  restarts.
+- `uuid` — a process-stable random UUID derived once per DSH session id
+  (opaque; resets when the process restarts).
+
+### debug / debugFile
+
+- `debug: true` — log every streamed call that receives the header via
+  `ctx.logger` (the dsh process console).
+- `debugFile: <absolute path>` — append one JSON line
+  (`{"ts","provider","model","session","header","value"}`) per streamed call
+  that receives the header. Handy when the dsh console is not visible.
+
+To override configuration in a profile without editing this package, add a
+patch entry with the **same id** to the profile's own `cordis.patch.yml` (it
+replaces the whole `config`, so restate every key you need). The patch entry
+form is id-targeted, not `insert` — see [Install](#install).
+
+## Install
+
+### From npm (recommended)
+
+```sh
+dsh plugin --profile web add @karoc/dsh-smoothly-opencode-session
+```
+
+Then **fully restart** your dsh profile (bundle layers are read at startup).
+The startup log shows:
+
+```
+[dsh-smoothly-opencode-session] active for providers [opencode, opencode-go] with mode session-id
+```
+
+If you run DSH from a source checkout instead, load it as an overlay:
+`pnpm dsh web --patch ./cordis.patch.yml`.
+
+### From git
+
+```sh
+dsh plugin --profile web add git+https://github.com/karoc/dsh-smoothly-opencode-session.git
+```
+
+### Updating
+
+```sh
+dsh plugin --profile web update @karoc/dsh-smoothly-opencode-session
+```
+
+Restart `dsh web` afterwards.
+
+### Removing
+
+```sh
+dsh plugin --profile web remove @karoc/dsh-smoothly-opencode-session
+```
+
+Restart `dsh web` afterwards. Removal is safe: the original `fetch` is
+restored on unload, so no other provider is affected.
+
+## Layout
+
+```
+src/index.ts            host plugin: llm/stream listener + fetch shim
+cordis.patch.yml        bundle layer (inserts the plugin row with defaults)
+scripts/                release gate + post-publish verification
+tests/                  node --test unit tests for the pure helpers
+lib/                    built output (npm package entry)
+```
+
+## Build & test
+
+```sh
+pnpm install      # installs dev deps (tsdown, @deepseek-ai/cordis types, @types/node)
+pnpm bundle       # emits lib/index.js
+npm test          # node --test tests/*.test.ts (runs TypeScript directly)
+```
+
+## Notes / limitations
+
+- **Scope:** only chat/streaming requests inside an `llm/stream` call receive
+  the header. The one-shot model listing used by the Models page
+  (`GET <baseURL>/models`) is a separate flow and does not receive it; if your
+  OpenCode endpoint rejects that listing too, that is a separate issue.
+- **Implementation dependency:** injection rides on Node's global `fetch`. If
+  a future DSH version swaps its network stack, the header silently stops
+  being sent (the 400 comes back) — uninstall then. This is an external-plugin
+  stopgap until the provider adapter itself (pi-ai) sends the header.
+- **Not the official fix:** the DSH maintainers' position is that provider
+  particularities belong in the pi-ai package (see discussion #5495 and
+  earendil-works/pi #9326). Once that ships and DSH upgrades to it, this
+  plugin can be removed.
+- **Discovery probes are untouched** (requests without a session id pass
+  through).
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

package/README.zh.md

@@ -0,0 +1,154 @@
+# 思磨力 OpenCode 会话头（Smoothly OCS）
+
+**Smoothly OpenCode Session (Smoothly OCS)** — 一个外部 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+(DSH) **宿主插件**：为路由到 **OpenCode / OpenCode Go** 提供方的模型请求自动附加
+OpenCode 要求的 `x-opencode-session` 请求头，取值是稳定的按会话 id。
+
+自 **2026-09-05** 起，OpenCode 的中继会拒绝任何缺少该头的推理请求
+（`400 MissingSessionID`）；该值同时把一段会话固定到同一上游后端，并让
+OpenCode 的提示词缓存在该会话各轮之间保持命中（上游跟踪见
+[deepseek-harness discussion #5495](https://github.com/deepseek-ai/deepseek-harness/discussions/5495)）。
+
+## 它做什么
+
+- **修掉 400**：凡是路由到已配置的 OpenCode(Go) 提供方的请求，一律带上
+  `x-opencode-session`。
+- **保住缓存/亲和收益**：取值按**会话**唯一、且在该会话各轮、压缩、重试与进程重启
+  之间保持稳定（默认直接复用 DSH 会话 id——官方 DeepSeek 适配器已作为
+  `x-deepseek-harness-session-id` 发送的同一个身份）。
+- **其余一概不动**：其他提供方、已自带该头的请求、以及没有会话 id 的请求，原样放行。
+
+## 工作原理
+
+插件监听 **`llm/stream` 瀑布**——一个文档化的 DSH 扩展缝（"围绕每次流式模型调用的
+Waterfall"）。LOOP 构建的请求 options 是深度冻结的（改写即抛错），所以不能靠改写
+options 加头；插件改为：
+
+1. 从瀑布 options 上读取 `provider` + `sessionId`；
+2. 把下游流的每次 pull 放进一个 `AsyncLocalStorage` store 里执行；
+3. 一次性 patch `globalThis.fetch`，当有 store 处于激活时，把
+   `x-opencode-session: <值>` 合入出站请求（除非请求已自带该头——已有值永远优先）。
+
+两处注册都是 fiber 作用域的（`ctx.on` 监听 + `ctx.effect` 清理函数），因此
+停止 / 更新 / 卸载插件时会恢复原始 `fetch` 并移除监听。
+
+### 为什么在 fetch 层注入
+
+外部插件没有任何官方缝能给适配器请求逐条加请求头（options 深度冻结；provider 的
+`headers` 配置是静态的、归属部署方）。fetch shim 是外部插件唯一能附加**按会话**值的
+机制。正确的长期修复在提供方适配器本身（pi-ai）；本插件只是它上线前的过渡方案。见
+[说明 / 限制](#说明--限制)。
+
+## 配置
+
+行的 `config`（写在插件的 `cordis.patch.yml`，或按 profile 覆盖）全部可选——
+缺失的键由代码填默认值。
+
+```yaml
+- insert:
+    - id: dsh-smoothly-opencode-session
+      name: '@karoc/dsh-smoothly-opencode-session'
+      config:
+        providers: [opencode, opencode-go]
+        mode: session-id
+        debug: false
+```
+
+### providers
+
+需要带头请求的提供方路由键。默认为 pi-ai 目录 id `opencode` 和 `opencode-go`。
+如果你用自定义提供方路由键提供 OpenCode（例如 `llm-pi-ai` 里的
+`opencode-go-self`），把该键加进来。
+
+### mode
+
+- `session-id`（默认）——头值 = 该次模型调用的 DSH 会话 id。每会话唯一，
+  跨轮次 / 压缩 / 重试 / 重启稳定。
+- `uuid`——按 DSH 会话 id 派生的进程内稳定随机 UUID（不透明；进程重启后重置）。
+
+### debug / debugFile
+
+- `debug: true`——把每个收到该头的流式调用经 `ctx.logger`（dsh 进程控制台）打日志。
+- `debugFile: <绝对路径>`——每个收到该头的流式调用向该文件追加一行 JSON
+  （`{"ts","provider","model","session","header","value"}`）。dsh 控制台不可见时很有用。
+
+想在不改本包的情况下按 profile 覆盖配置：在 profile 自己的 `cordis.patch.yml` 里加一条
+**同 id** 的 patch 条目（它整体替换 `config`，所以需要的键都要重写）。patch 条目用
+id-targeted 形式，不是 `insert`——见 [安装](#安装)。
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+```sh
+dsh plugin --profile web add @karoc/dsh-smoothly-opencode-session
+```
+
+然后**完全重启** dsh profile（bundle 层启动时才读取）。启动日志应出现：
+
+```
+[dsh-smoothly-opencode-session] active for providers [opencode, opencode-go] with mode session-id
+```
+
+如果你从源码 checkout 运行 dsh，也可以作为 overlay 加载：
+`pnpm dsh web --patch ./cordis.patch.yml`。
+
+### 从 git 安装
+
+```sh
+dsh plugin --profile web add git+https://github.com/karoc/dsh-smoothly-opencode-session.git
+```
+
+### 更新
+
+```sh
+dsh plugin --profile web update @karoc/dsh-smoothly-opencode-session
+```
+
+之后重启 `dsh web`。
+
+### 卸载
+
+```sh
+dsh plugin --profile web remove @karoc/dsh-smoothly-opencode-session
+```
+
+之后重启 `dsh web`。卸载是安全的：卸载时恢复原始 `fetch`，不影响其他提供方。
+
+## 目录结构
+
+```
+src/index.ts            宿主插件：llm/stream 监听 + fetch shim
+cordis.patch.yml        bundle 层（插入带默认配置的插件行）
+scripts/                发布门禁 + 发布后校验
+tests/                  node --test 纯函数单元测试
+lib/                    构建产物（npm 包入口）
+```
+
+## 构建与测试
+
+```sh
+pnpm install      # 安装开发依赖（tsdown、@deepseek-ai/cordis 类型、@types/node）
+pnpm bundle       # 产出 lib/index.js
+npm test          # node --test tests/*.test.ts（直接运行 TypeScript）
+```
+
+## 说明 / 限制
+
+- **范围**：只有 `llm/stream` 调用内的聊天/流式请求会收到该头。Models 页使用的一次性
+  模型列表（`GET <baseURL>/models`）是独立流程，不会收到该头；如果你的 OpenCode
+  端点连那个列表也拒绝，那是另一个问题。
+- **实现依赖**：注入依赖 Node 的全局 `fetch`。如果未来某个 DSH 版本换掉网络栈，
+  该头会静默不再发送（400 复现）——届时卸载即可。这是提供方适配器（pi-ai）自身
+  发送该头之前的过渡方案。
+- **不是官方修复**：DSH 维护者的立场是提供方特殊性应归 pi-ai 包处理（见 discussion
+  #5495 与 earendil-works/pi #9326）。等它发版并被 DSH 升级后，本插件即可移除。
+- **发现探测不受影响**（没有会话 id 的请求原样放行）。
+
+## 许可证
+
+MIT
+
+## 参与贡献
+
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。

package/cordis.patch.yml

@@ -0,0 +1,36 @@
+# Bundle layer applied when a profile lists this package. The row names the
+# package by name so Node resolution finds the installed code; this is a
+# host-only plugin (no exports["./client"], no dsh.client manifest). The
+# row's host apply listens on the llm/stream waterfall and injects the
+# OpenCode-required x-opencode-session header onto provider requests.
+#
+# Configuration (row config, all optional — the code fills defaults for
+# missing keys, so a profile override only needs the keys it changes):
+#   providers: [string]  provider route keys whose requests receive the
+#                        header. Defaults to the pi-ai catalog ids
+#                        ['opencode', 'opencode-go']. Add your own route key
+#                        when OpenCode is served under a custom provider name
+#                        (e.g. opencode-go-self).
+#   mode: 'session-id' | 'uuid'
+#                        'session-id' (default): header value = the DSH
+#                        session id that already travels with each model call
+#                        — stable across turns, compaction, retries and
+#                        restarts, unique per conversation.
+#                        'uuid': a process-stable random uuid derived per DSH
+#                        session id (opaque; resets when the process
+#                        restarts).
+#   debug: true|false    log every streamed call that receives the header
+#                        via ctx.logger (the dsh process console).
+#   debugFile: path      optional absolute path; when set, every streamed
+#                        call that receives the header appends one JSON line
+#                        ({"ts","provider","model","session","header","value"})
+#                        to that file — handy when the dsh console is hidden.
+- insert:
+    - id: dsh-smoothly-opencode-session
+      name: '@karoc/dsh-smoothly-opencode-session'
+      config:
+        providers:
+          - opencode
+          - opencode-go
+        mode: session-id
+        debug: false

package/lib/index.js

@@ -0,0 +1,203 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { appendFile } from "node:fs/promises";
+//#region src/index.ts
+/**
+* Smoothly OpenCode Session (Smoothly OCS) — 思磨力 OpenCode 会话头.
+*
+* External DeepSeek Harness HOST plugin: attaches the OpenCode-required
+* `x-opencode-session` request header to model calls routed to OpenCode /
+* OpenCode Go provider routes. Since 2026-09-05 OpenCode's relay rejects any
+* inference request that lacks the header (400 MissingSessionID); the value
+* is a stable per-conversation id, which is also what pins a conversation to
+* one upstream backend and keeps the prompt cache warm across its turns.
+*
+* Mechanism (each piece verified against the official contracts):
+*   - `llm/stream` is a documented waterfall ("Waterfall around every
+*     streaming model call", api-catalog), signature
+*     `(options: GenerateOptions, next: () => AsyncIterable<StreamChunk>)`.
+*     LOOP-built options are deep-frozen: listeners read, never rewrite.
+*   - The header therefore cannot be added by mutating options. This plugin
+*     observes provider + sessionId at the waterfall, then drives the
+*     downstream stream's pulls inside an AsyncLocalStorage store while one
+*     patched `globalThis.fetch` merges the header onto the outbound request
+*     (unless it already carries one — an existing value always wins).
+*   - Registrations are fiber-scoped (ctx.on listener + ctx.effect disposer),
+*     so stopping / updating / unloading the plugin restores the original
+*     fetch and removes the listener.
+*
+* Scope notes / honest limitations:
+*   - Requests NOT routed to a configured OpenCode provider, or carrying no
+*     session id (some auxiliary hand-built calls), pass through untouched.
+*   - The header attaches to chat/streaming requests inside an `llm/stream`
+*     call. The one-shot model listing used by the Models page
+*     (`GET <baseURL>/models`) is a separate flow and does not receive the
+*     header.
+*   - Injection rides on Node's global `fetch`. If a future dsh version swaps
+*     its network stack, the header silently stops being sent (the 400 comes
+*     back) — uninstall then. This is an external-plugin stopgap until the
+*     provider adapter itself (pi-ai) sends the header.
+*/
+/** Plugin display metadata (cordis diagnostics). */
+const name = "dsh-smoothly-opencode-session";
+/**
+* The `llm/stream` waterfall lives on the abstract `llm` service (dsh-llm).
+* Injecting it keeps this plugin PENDING until that service exists, so the
+* waterfall is already registered by its provider when we listen.
+*/
+const inject = ["llm"];
+const SESSION_HEADER = "x-opencode-session";
+/**
+* Provider route keys whose requests receive the header. A pi-ai catalog
+* provider keeps its id as the route key, so both built-in OpenCode ids are
+* covered; deployments that serve OpenCode under a custom provider key (e.g.
+* `opencode-go-self`) add it through config.
+*/
+const DEFAULT_PROVIDERS = ["opencode", "opencode-go"];
+/** Resolve row config against code defaults (missing keys are never required). */
+function resolveConfig(config = {}) {
+	const providers = Array.isArray(config.providers) && config.providers.length > 0 ? config.providers.map((value) => String(value)) : [...DEFAULT_PROVIDERS];
+	return {
+		providers: new Set(providers),
+		mode: config.mode === "uuid" ? "uuid" : "session-id",
+		debug: config.debug === true,
+		...typeof config.debugFile === "string" && config.debugFile.length > 0 ? { debugFile: config.debugFile } : {}
+	};
+}
+/**
+* Derive the opaque header value for one DSH session id.
+* `session-id` mode returns the raw id (unique per conversation, stable across
+* turns, compaction, retries and restarts); `uuid` mode returns a process-
+* stable random uuid derived once per session id (opaque, resets on restart).
+*/
+function headerValueFor(sessionId, mode, table) {
+	const raw = String(sessionId);
+	if (raw.length === 0) return void 0;
+	if (mode !== "uuid") return raw;
+	let value = table.get(raw);
+	if (value === void 0) {
+		value = randomUUID();
+		table.set(raw, value);
+	}
+	return value;
+}
+/** True when an outgoing request already carries the session header. */
+function hasSessionHeader(input, init) {
+	const source = init?.headers ?? (typeof Request !== "undefined" && input instanceof Request ? input.headers : void 0);
+	if (source === void 0) return false;
+	try {
+		return new Headers(source).has(SESSION_HEADER);
+	} catch {
+		return false;
+	}
+}
+/**
+* Build a patched fetch that injects the header while a store is active.
+* Header precedence mirrors native fetch: when `init.headers` is present it
+* wins; otherwise a Request's own headers are the base. A request that already
+* carries the header is never modified (an existing value always wins).
+*/
+function patchFetch(original, als) {
+	return function patchedFetch(input, init) {
+		const state = als.getStore();
+		if (state !== void 0 && !hasSessionHeader(input, init)) {
+			const headers = new Headers(init?.headers ?? (typeof Request !== "undefined" && input instanceof Request ? input.headers : void 0));
+			headers.set(SESSION_HEADER, state.value);
+			return original.call(this, input, {
+				...init,
+				headers
+			});
+		}
+		return original.apply(this, arguments);
+	};
+}
+/**
+* Wrap a downstream async iterable so every pull executes inside an
+* AsyncLocalStorage store. Async generators and the promises they create
+* inherit the store as long as the generator body is driven from a pull made
+* inside `als.run`, which is exactly what this wrapper does per `next()`.
+*/
+function withStore(iterable, store, als) {
+	const iterator = typeof iterable[Symbol.asyncIterator] === "function" ? iterable[Symbol.asyncIterator]() : iterable;
+	return {
+		[Symbol.asyncIterator]() {
+			return this;
+		},
+		async next() {
+			return als.run(store, () => iterator.next());
+		},
+		async return(value) {
+			if (typeof iterator.return === "function") try {
+				return await iterator.return(value);
+			} catch {}
+			return {
+				done: true,
+				value
+			};
+		},
+		async throw(error) {
+			if (typeof iterator.throw === "function") return als.run(store, () => iterator.throw(error));
+			throw error;
+		}
+	};
+}
+/** Fire-and-forget append of one debug record; failures only log a warning. */
+function recordDebug(ctx, file, entry) {
+	appendFile(file, `${JSON.stringify(entry)}\n`, "utf8").catch((error) => {
+		ctx.logger.warn("[dsh-smoothly-opencode-session] debugFile write failed: %s", error?.message ?? String(error));
+	});
+}
+function apply(ctx, config = {}) {
+	const { providers, mode, debug, debugFile } = resolveConfig(config);
+	const als = new AsyncLocalStorage();
+	const uuidBySession = /* @__PURE__ */ new Map();
+	const originalFetch = globalThis.fetch;
+	if (typeof originalFetch !== "function") {
+		ctx.logger.warn(`[${name}] globalThis.fetch is unavailable; cannot inject ${SESSION_HEADER}`);
+		return;
+	}
+	const patched = patchFetch(originalFetch, als);
+	ctx.effect(() => {
+		globalThis.fetch = patched;
+		ctx.logger.info("[%s] active for providers [%s] with mode %s", name, [...providers].join(", "), mode);
+		return () => {
+			if (globalThis.fetch === patched) globalThis.fetch = originalFetch;
+		};
+	}, `${name}.fetch-patch`);
+	ctx.on("llm/stream", (options, next) => {
+		if (options === void 0 || options === null || typeof options !== "object") return next();
+		if (!providers.has(String(options.provider))) return next();
+		const sessionId = options.sessionId;
+		if (sessionId === void 0 || sessionId === null) return next();
+		const value = headerValueFor(String(sessionId), mode, uuidBySession);
+		if (value === void 0) return next();
+		let downstream;
+		try {
+			downstream = next();
+		} catch (error) {
+			throw error;
+		}
+		if (downstream === void 0 || downstream === null) return downstream;
+		if (typeof downstream[Symbol.asyncIterator] !== "function") return downstream;
+		if (debug || debugFile !== void 0) {
+			const entry = {
+				ts: (/* @__PURE__ */ new Date()).toISOString(),
+				provider: options.provider,
+				model: options.model,
+				session: String(sessionId),
+				header: SESSION_HEADER,
+				value
+			};
+			if (debugFile !== void 0) recordDebug(ctx, debugFile, entry);
+			if (debug) ctx.logger.info("[%s] streaming provider \"%s\" with %s=%s", name, options.provider, SESSION_HEADER, value);
+		}
+		return withStore(downstream, { value }, als);
+	}, { prepend: true });
+}
+var src_default = {
+	name,
+	inject,
+	apply
+};
+//#endregion
+export { apply, src_default as default, hasSessionHeader, headerValueFor, inject, name, patchFetch, resolveConfig, withStore };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@karoc/dsh-smoothly-opencode-session",
+  "version": "0.1.0",
+  "description": "Smoothly OpenCode Session (Smoothly OCS) — 思磨力 OpenCode 会话头: external DeepSeek Harness host plugin that attaches the OpenCode-required x-opencode-session header to model calls routed to OpenCode / OpenCode Go provider routes (stable per-conversation id; fixes 400 MissingSessionID, in effect for OpenCode Go since 2026-09-05).",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown --config ./tsdown.config.ts",
+    "prepare": "tsdown --config ./tsdown.config.ts",
+    "test": "node --test tests/*.test.ts",
+    "release:check": "node scripts/release-check.mjs",
+    "prepack": "node scripts/release-check.mjs",
+    "prepublishOnly": "node scripts/release-check.mjs && tsdown --config ./tsdown.config.ts",
+    "postpublish": "node scripts/post-publish-check.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "host-plugin",
+    "opencode",
+    "opencode-go",
+    "x-opencode-session",
+    "missing-session-id",
+    "session-affinity",
+    "prompt-cache",
+    "llm",
+    "smoothly",
+    "smoothly-ocs",
+    "smoothly-opencode-session",
+    "思磨力",
+    "ocs"
+  ],
+  "author": "karoc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karoc/dsh-smoothly-opencode-session.git"
+  },
+  "bugs": {
+    "url": "https://github.com/karoc/dsh-smoothly-opencode-session/issues"
+  },
+  "homepage": "https://github.com/karoc/dsh-smoothly-opencode-session",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@types/node": "^24.0.0",
+    "tsdown": "^0.22.0"
+  }
+}