@verneuil/dsh-ocg-session-head 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.1
+
+### 改进
+- README 新增开篇《先读这段》：明确本插件仅适用于 DeepSeek Harness 0.2.2 及以上，且仅用于「自定义供应商名称」的 OpenCode 接入；官方路径接入无需本插件。
+- README 安装说明更新为 npm 优先，并修正已失效的 DSH_HOME 路径示例。
+
+---
+### Improvements
+- README now opens with a "Read this first" section: the plugin requires DeepSeek Harness 0.2.2 or newer, and is only needed for OpenCode connected under a custom provider name — the official path needs no plugin.
+- Install instructions now prefer npm, and the outdated DSH_HOME path samples are corrected.
+
+## 0.1.0
+
+### 新功能
+- 首个版本：通过宿主官方 `llm-pi-ai/request-headers` 瀑布，为 OpenCode Go 路由按会话注入 `x-opencode-session` 请求头，解决 400 MissingSessionID，并保留按会话的路由与提示词缓存亲和。
+- 支持自定义路由：`providers` 路由键白名单与 `hostSuffixes` 主机后缀两条匹配门，默认适配 `ocg`。
+- 支持 `session-id` 与 `uuid` 两种头值模式；`uuid` 模式可隐藏真实会话 ID。
+- 配置错误会在插件激活阶段直接报错并指出字段，不会静默回落。
+- 自带零依赖自测：`node scripts/self-test.mjs`。
+
+*需要 DeepSeek Harness 0.2.2 或更高版本。*
+
+---
+### New Features
+- First release: injects the `x-opencode-session` header per conversation for OpenCode Go routes through the host's official `llm-pi-ai/request-headers` waterfall, fixing 400 MissingSessionID while preserving per-conversation routing and prompt-cache affinity.
+- Custom routes supported: a provider-key allowlist plus a baseURL host-suffix gate, tailored to `ocg` by default.
+- Two header-value modes, `session-id` and `uuid`; `uuid` hides the real session id.
+- Invalid configuration fails loudly at activation and names the offending field.
+- Ships a zero-dependency self-test: `node scripts/self-test.mjs`.
+
+*Requires DeepSeek Harness 0.2.2 or newer.*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 verneuil
+
+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,179 @@
-# Temporary Holding Version
+# OCG 会话头（@verneuil/dsh-ocg-session-head）
 
-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.
+给 **OpenCode Go** 路由按会话注入 `x-opencode-session` 请求头。
+
+> ### ⚠️ 先读这段：不满足以下任一条，你不需要本插件
+>
+> **1）宿主必须是 DeepSeek Harness 0.2.2 或更高版本**
+>
+> 本插件只做一件事：在宿主官方预留的请求头席位（`llm-pi-ai/request-headers` 瀑布）里写一个头。
+> 该席位自 **0.2.2-alpha.3** 才引入、0.2.2-rc.1 起稳定，**更早的版本没有这个能力底座**。
+> 在低版本上装它不会报错，但**永远不会生效**——看起来像「装了没用」，其实是无处可挂。
+>
+> **2）只对「自定义供应商名称」的 OpenCode 接入才有意义**
+>
+> - 如果你是通过 DSH 的**官方添加路径**接入 OpenCode / OpenCode Go（走 pi-ai 内置的
+>   `opencode` / `opencode-go` 路由），新版 pi-ai 已经会**自动**带上会话请求头，
+>   **不需要本插件**，装了纯属多余。
+> - 只有当你是这样接入的——**确实在用 OpenCode 服务，但供应商名是自己起的**
+>   （手写 `baseURL` + `api: openai-completions`，例如把它叫 `ocg`）——
+>   才拿不到那层自动包装，需要本插件补上这个头。
+>
+> 一句话：**官方路径接入 → 不用装；自定义命名接入 → 装本插件。**
+
+这是 `dsh-opencode-session`（fetch 猴补丁版）的**替代实现**：不替换 `globalThis.fetch`、不使用
+`AsyncLocalStorage`，只在宿主官方预留的请求头席位里写一个头。
+
+- 仓库：<https://github.com/verneuil/dsh-ocg-session-head>
+- 自测：`node scripts/self-test.mjs`（零依赖，不需要宿主）
+
+---
+
+## 1. 为什么需要
+
+OpenCode Go 自 2026-09-05 起，推理请求必须携带稳定的 `x-opencode-session`，否则返回：
+
+```
+400 {"type":"MissingSessionID", ...}
+```
+
+官方对**内置** `opencode` / `opencode-go` 路由已经在 pi-ai 里做了包装；但**自定义命名**的路由
+（自己起个名字、手写 `baseURL` + `api: openai-completions`）拿不到那层包装，因此需要插件补上。
+
+> 不确定自己属于哪种情况？回到开篇《先读这段》第 2 条对号入座。
+
+## 2. 版本要求（重要）
+
+| 项 | 要求 |
+|---|---|
+| DSH | **≥ 0.2.2**（`llm-pi-ai/request-headers` 席位自 0.2.2-alpha.3 引入，0.2.2 系列起可用） |
+| Node | 无额外要求（纯 ESM，零依赖） |
+
+在**低于该版本**的宿主上安装是安全的：插件能加载、会打一行 ready 日志，但事件永不触发 →
+行为等价于不装（OCG 仍会 400）。**可用这一特性做「先装后升级」的分步验证。**
+
+## 3. 安装
+
+### 3.1 从 npm 安装（推荐）
+
+在 DSH 的插件管理里安装 `@verneuil/dsh-ocg-session-head`（或指定版本 `@verneuil/dsh-ocg-session-head@0.1.1`），
+或直接在 profile 的 `package.json` 里加：
+
+```json
+"@verneuil/dsh-ocg-session-head": "^0.1.1"
+```
+
+### 3.2 离线 / 本地 tarball
+
+> ⚠️ **绝不要把「包目录」当安装 target。** pnpm 对目录使用 `link:`（junction），模块解析会
+> 退化成 Node 原生解析，DSH 解析拦截层失效 → 条目 `failed to import`。
+> **只有 tarball 会被解包成 profile 内的实体目录。**
+
+在 profile 的 `dependencies` 里写成 `file:` 形式：
+
+```json
+"@verneuil/dsh-ocg-session-head": "file:<你的绝对路径>/dsh-ocg-session-head-<版本>.tgz"
+```
+
+写入依赖后，用 DSH 自带的 node/pnpm 安装（本机不需要系统 npm）：
+
+```powershell
+$node   = Join-Path $env:DSH_HOME 'dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe'
+$pnpm   = Join-Path $env:DSH_HOME 'dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.mjs'
+$target = Join-Path $env:DSH_HOME 'profiles\desktop'
+& $node $pnpm install --dir $target
+```
+
+无论哪种方式，安装后都需要**重启 DSH**（重启会杀掉宿主里的 AI 进程，需人工执行）。
+
+## 4. 配置
+
+`cordis.patch.yml` 自带一份默认 config；也可在 profile 的 `cordis.patch.yml` 里按 id 覆盖：
+
+```yaml
+- id: dsh-ocg-session-head
+  config:
+    providers:
+      - ocg
+    debug: true
+```
+
+> 按 id 覆盖是**整体替换** config。
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `providers` | `['ocg']` | 路由键白名单，精确匹配事件里的 `provider` |
+| `hostSuffixes` | `['opencode.ai']` | baseURL 主机后缀白名单；两条门是**或**关系，换路由键时兜底 |
+| `header` | `x-opencode-session` | 注入的头名，必须是合法 HTTP header 名 |
+| `mode` | `session-id` | `session-id`：直接用宿主会话 id（跨轮次/压缩/重启稳定）；`uuid`：按会话派生进程内稳定的不透明 uuid |
+| `debug` | `false` | 每次成功注入打一行日志 |
+| `maxTrackedSessions` | `4096` | `uuid` 模式下会话映射上限，超出按最旧淘汰 |
+
+### 配置校验（错误会响亮报错）
+
+遵循官方「配置错误要响亮」原则：**非法配置会让插件激活失败并给出字段名**，不会静默回落。
+
+| 情况 | 行为 |
+|---|---|
+| 键未配置（`undefined`） | 使用默认值 |
+| 出现未知键名（疑似拼写错误） | ❌ 报错并列出合法键 |
+| `providers` / `hostSuffixes` 不是字符串数组、含空串、含重复项 | ❌ 报错并指出下标 |
+| `header` 为空或不是合法 HTTP header 名 | ❌ 报错 |
+| `header` 指向 Harness 归属头（`user-agent`、`x-deepseek-harness-*`） | ❌ 报错（宿主会在所有贡献者之后覆盖它，写了也无效） |
+| `mode` 不是 `session-id` / `uuid` | ❌ 报错 |
+| `debug` 不是布尔、`maxTrackedSessions` 不是正整数 | ❌ 报错 |
+| `providers` 与 `hostSuffixes` **同时为空** | ❌ 报错（永远匹配不到任何请求） |
+
+> 数组字段语义：「未配置」用默认值；**显式传空数组表示关闭这道门**。
+> 例如 `hostSuffixes: []` 表示只按路由键匹配、不再按 baseURL 主机兜底。
+
+## 5. 行为保证
+
+- **已有同名头一律让路**：不覆盖静态 `headers` 配置、官方实现或其它插件写入的值。
+- **无会话 id 不注入**：辅助调用若没有 `sessionId`，原样放行。
+- **失败即放行**：插件内部任何异常只 `warn` 一行，然后继续 `next()`，绝不因本插件打断推理。
+- **零全局副作用**：不修改 `globalThis`、不替换 `fetch`、不写文件。
+- **随插件卸载自动撤销**：监听器由 `ctx.on()` 注册，归 fiber 生命周期管理。
+
+## 6. 验证（四关）
+
+1. **启动日志**：宿主控制台出现
+   `[dsh-ocg-session-head] ready (header=x-opencode-session mode=session-id providers=ocg ...)`
+2. **注入日志**：把 `debug` 打开后，每次模型调用出现
+   `[dsh-ocg-session-head] x-opencode-session=<id> provider=ocg model=... purpose=chat`
+3. **真请求 200**：正常对话不出现 400 `MissingSessionID`。
+4. **反向证明**：禁用本插件后立刻 400 —— 证明头确实是它在发。
+
+## 7. 卸载与回滚
+
+- 插件管理页卸载，或从 profile `dependencies` 删除该包后重装依赖。
+- 旧插件 `dsh-opencode-session` 可与之**共存**（两者都「已有不覆盖」，新实现先写入、旧的自动 no-op）。
+  切换期建议：**旧插件保持安装但禁用**，出问题 30 秒切回。
+
+## 8. 开发与打包
+
+```powershell
+# 自测（零依赖，不需要宿主）
+node scripts/self-test.mjs
+
+# 用 DSH 自带运行时打包（无需系统 node/pnpm）
+$node = Join-Path $env:DSH_HOME 'dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe'
+$pnpm = Join-Path $env:DSH_HOME 'dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.mjs'
+& $node $pnpm pack
+```
+
+本地测试包可命名 `<版本>-rc.<YYYYMMDD-HHmm>`（临时改版本 → 打包 → 立即还原）。
+
+## 9. 已知限制
+
+- 只覆盖 **pi-ai 路由**（`@deepseek-ai/dsh-llm-pi-ai`）。`deepseek-official` 走
+  `@deepseek-ai/dsh-llm-deepseek`，它自己发 `x-deepseek-harness-session-id`，与本插件无关。
+- **不覆盖模型发现**（宿主契约明确该事件 `excludes model discovery`）。
+- 事件是**同步**的：监听器必须就地修改 `headers` 并立刻 `return next()`，不得保存该对象引用。
+- 未声明 `engines.dsh`。官方推荐声明兼容范围，但 SemVer 的预发布规则会让 `>=0.2.2` 拒绝
+  `0.2.2-rc.1`、让 `>=0.2.2-rc.1` 拒绝将来的 `0.2.3-rc.1`，对跟着 rc 升级的用户反而更危险；
+  因此这里选择不声明（等价于不做版本门禁），运行期依赖单一公开事件，兼容面本就很窄。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# 插入本插件的 loader row。
+#
+# 注意：这个 id 与 index.js 的 `export const name` 保持一致，
+# 同时是 profile 里「按 id 覆盖 config」的锚点。
+#
+# profile 侧按 id 覆盖会**整体替换** config。未写的键由 index.js 的 DEFAULTS 兜底；
+# 写错的键/类型/枚举会在插件激活阶段直接报错（官方「配置错误要响亮」），不会静默回落。
+- insert:
+    - id: dsh-ocg-session-head
+      name: '@verneuil/dsh-ocg-session-head'
+      config:
+        providers:
+          - ocg
+        hostSuffixes:
+          - opencode.ai
+        header: x-opencode-session
+        mode: session-id
+        debug: false

package/index.js

@@ -0,0 +1,281 @@
+/**
+ * dsh-ocg-session-head — 给 OpenCode Go 路由按会话注入 `x-opencode-session`。
+ *
+ * ## 它挂在哪里
+ *
+ * 监听宿主 dsh-llm-pi-ai 的同步瀑布事件 `llm-pi-ai/request-headers`
+ * （DSH 0.2.2-alpha.3 引入、0.2.2-rc.1 确认保留）。
+ *
+ * 事件签名（官方源码 packages/llm/llm-pi-ai/src/types.ts、README「Request headers」节）：
+ *
+ *     'llm-pi-ai/request-headers'(
+ *       request: PiAiRequestHeaderContext,
+ *       headers: Headers,
+ *       next: () => Headers,
+ *     ): Headers
+ *
+ *     interface PiAiRequestHeaderContext
+ *       extends Readonly<Pick<GenerateOptions, 'provider' | 'model' | 'sessionId' | 'purpose'>> {
+ *       readonly baseURL: string
+ *     }
+ *
+ * 官方契约要点：
+ *   - 每次**推理调用**派发前触发（含起标题 / 压缩等辅助调用），**不含模型发现**；
+ *   - `headers` 是该次请求独占的一份副本，监听者**就地修改**后调用 `next()`；
+ *   - 宿主归因头在所有贡献者之后统一写入，监听者无法覆盖；
+ *   - 监听者抛错或写入非法 HTTP 头 → 该次调用以 `REQUEST_HEADERS` 在发请求前失败；
+ *   - `ctx.on()` 注册的监听器随插件卸载自动移除。
+ *
+ * ## 为什么不猴补丁 fetch
+ *
+ * 旧方案（dsh-opencode-session）在 `globalThis.fetch` 上打补丁 + AsyncLocalStorage
+ * 传递会话身份。这条链依赖「宿主一定走全局 fetch」，网络栈一变就静默失效。
+ * 本插件只在参数层写一个头，与传输实现无关。
+ *
+ * @module dsh-ocg-session-head
+ */
+
+/** Cordis 插件名。与 cordis.patch.yml 里的 row id 保持一致，便于按 id 覆盖 config。 */
+export const name = 'dsh-ocg-session-head'
+
+/**
+ * 不依赖任何宿主服务：事件由适配器派发，注册本身不需要 llm 服务句柄。
+ * 空数组表示「无 inject」，插件在 profile 装配时即可加载。
+ */
+export const inject = []
+
+/** 配置默认值。profile 里的按 id 覆盖会**整体替换** config，缺省键在此兜底。 */
+const DEFAULTS = Object.freeze({
+  /** 路由键白名单（精确匹配 request.provider）。 */
+  providers: ['ocg'],
+  /** baseURL 主机后缀白名单（忽略大小写）。显式空数组表示不按主机匹配。 */
+  hostSuffixes: ['opencode.ai'],
+  /** 注入的请求头名。 */
+  header: 'x-opencode-session',
+  /** session-id：直接用宿主会话 id；uuid：按会话派生进程内稳定的不透明 uuid。 */
+  mode: 'session-id',
+  /** true 时每次成功注入打一行日志（默认关闭，避免刷屏）。 */
+  debug: false,
+  /** uuid 模式下最多记住多少个会话（超出按最旧淘汰，防止长跑进程无限增长）。 */
+  maxTrackedSessions: 4096,
+})
+
+/** 允许出现的配置键。写错键名属于配置错误，必须响亮报错而不是被静默忽略。 */
+const CONFIG_KEYS = Object.freeze(Object.keys(DEFAULTS))
+
+/**
+ * RFC 9110 `token` 文法：HTTP 请求头名必须由这些字符组成且非空。
+ * @see https://www.rfc-editor.org/rfc/rfc9110#section-5.6.2
+ */
+const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+/**
+ * 抛出配置错误。
+ *
+ * 依据官方配置指南「配置错误要响亮」：非法配置在插件激活阶段直接失败，
+ * 而不是悄悄回落到默认值后带着错误设定继续跑。
+ *
+ * @param {string} message 面向用户的原因。
+ * @returns {never} 永远抛出。
+ */
+function fail(message) {
+  throw new Error(`[${name}] invalid config: ${message}`)
+}
+
+/**
+ * 读取字符串数组配置。
+ *
+ * 语义刻意区分「未配置」与「配置错误」：
+ *   - 未配置（`undefined`）→ 使用默认值；
+ *   - 已配置但不是数组、含非字符串、含空串或重复项 → 响亮报错；
+ *   - 显式空数组 → 采信为空数组（表示关闭该匹配门）。
+ *
+ * @param {Record<string, unknown>} config 原始配置。
+ * @param {string} key 字段名。
+ * @param {readonly string[]} fallback 默认值。
+ * @returns {string[]} 规范化后的数组。
+ */
+function readStringList(config, key, fallback) {
+  const raw = config[key]
+  if (raw === undefined) return [...fallback]
+  if (!Array.isArray(raw)) fail(`"${key}" must be an array of strings`)
+  const seen = new Set()
+  return raw.map((item, index) => {
+    if (typeof item !== 'string') fail(`"${key}[${index}]" must be a string`)
+    const value = item.trim()
+    if (value.length === 0) fail(`"${key}[${index}]" must be a non-empty string`)
+    if (seen.has(value)) fail(`"${key}" lists ${JSON.stringify(value)} more than once`)
+    seen.add(value)
+    return value
+  })
+}
+
+/**
+ * 把原始 config 解析成运行时选项。
+ *
+ * 任何非法配置都会抛出带字段名的错误（官方「配置错误要响亮」）。运行时注入失败则走
+ * fail-open（见 `apply`），两者互不影响：配置错了直接拒绝启用，运行中偶发异常则放行请求。
+ *
+ * @param {Record<string, unknown>} [config] loader row 传入的 config。
+ * @returns {object} 运行时选项。
+ */
+export function resolveOptions(config = {}) {
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    fail('config must be an object')
+  }
+  for (const key of Object.keys(config)) {
+    if (!CONFIG_KEYS.includes(key)) {
+      fail(`unknown key ${JSON.stringify(key)}; valid keys are ${CONFIG_KEYS.join(', ')}`)
+    }
+  }
+
+  const providers = readStringList(config, 'providers', DEFAULTS.providers)
+  const hostSuffixes = readStringList(config, 'hostSuffixes', DEFAULTS.hostSuffixes)
+    .map((suffix) => suffix.toLowerCase().replace(/^\./, ''))
+
+  const rawHeader = config.header === undefined ? DEFAULTS.header : config.header
+  if (typeof rawHeader !== 'string' || rawHeader.trim().length === 0) {
+    fail('"header" must be a non-empty string')
+  }
+  const header = rawHeader.trim()
+  if (!HTTP_TOKEN.test(header)) {
+    fail(`"header" is not a valid HTTP header name: ${JSON.stringify(header)}`)
+  }
+  const headerLower = header.toLowerCase()
+  if (headerLower === 'user-agent' || headerLower.startsWith('x-deepseek-harness-')) {
+    fail(`"header" must not target a Harness attribution header (${header}); the Harness applies its own value after every contributor`)
+  }
+
+  const mode = config.mode === undefined ? DEFAULTS.mode : config.mode
+  if (mode !== 'session-id' && mode !== 'uuid') {
+    fail(`"mode" must be "session-id" or "uuid"; got ${JSON.stringify(mode)}`)
+  }
+
+  const debug = config.debug === undefined ? DEFAULTS.debug : config.debug
+  if (typeof debug !== 'boolean') fail('"debug" must be a boolean')
+
+  const maxTrackedSessions = config.maxTrackedSessions === undefined
+    ? DEFAULTS.maxTrackedSessions
+    : config.maxTrackedSessions
+  if (!Number.isSafeInteger(maxTrackedSessions) || maxTrackedSessions <= 0) {
+    fail('"maxTrackedSessions" must be a positive integer')
+  }
+
+  if (providers.length === 0 && hostSuffixes.length === 0) {
+    fail('"providers" and "hostSuffixes" are both empty, so no request could ever match')
+  }
+
+  return {
+    providers: new Set(providers),
+    hostSuffixes,
+    header,
+    mode,
+    debug,
+    maxTrackedSessions,
+  }
+}
+
+/**
+ * 取 baseURL 的主机名（小写）；无法解析时返回空串，绝不抛错。
+ * @param {unknown} baseURL 模型解析后的端点。
+ * @returns {string} 主机名或空串。
+ */
+function hostOf(baseURL) {
+  if (typeof baseURL !== 'string' || baseURL.length === 0) return ''
+  try {
+    return new URL(baseURL).hostname.toLowerCase()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 判断这次调用是否属于本插件负责的 OpenCode 路由。
+ *
+ * 两条门是「或」关系：
+ *   1. 路由键在 providers 白名单里（最精确，本机就是 `ocg`）；
+ *   2. baseURL 主机命中 hostSuffixes（换路由键、或别名路由时兜底）。
+ *
+ * @param {ReturnType<typeof resolveOptions>} options 运行时选项。
+ * @param {Record<string, unknown>} request 事件携带的路由元数据。
+ * @returns {boolean} 是否由本插件接管。
+ */
+export function isOpenCodeRoute(options, request) {
+  const provider = typeof request.provider === 'string' ? request.provider : ''
+  if (provider.length > 0 && options.providers.has(provider)) return true
+  if (options.hostSuffixes.length === 0) return false
+  const host = hostOf(request.baseURL)
+  if (host.length === 0) return false
+  return options.hostSuffixes.some((suffix) => host === suffix || host.endsWith(`.${suffix}`))
+}
+
+/**
+ * 计算某次会话要写入的头值。
+ * @param {ReturnType<typeof resolveOptions>} options 运行时选项。
+ * @param {Map<string, string>} table uuid 模式下会话 → uuid 的映射。
+ * @param {unknown} sessionId 宿主会话 id。
+ * @returns {string | undefined} 头值；无法产生时返回 undefined。
+ */
+export function headerValueFor(options, table, sessionId) {
+  const raw = String(sessionId ?? '')
+  if (raw.length === 0) return undefined
+  if (options.mode !== 'uuid') return raw
+  const cached = table.get(raw)
+  if (cached !== undefined) return cached
+  const value = globalThis.crypto?.randomUUID?.()
+  if (value === undefined) return raw
+  if (table.size >= options.maxTrackedSessions) {
+    const oldest = table.keys().next()
+    if (oldest.done !== true) table.delete(oldest.value)
+  }
+  table.set(raw, value)
+  return value
+}
+
+/**
+ * 安装插件。
+ * @param {import('cordis').Context} ctx 宿主上下文。
+ * @param {Record<string, unknown>} [config] loader row 的 config。
+ */
+export function apply(ctx, config) {
+  const options = resolveOptions(config)
+  /** @type {Map<string, string>} */
+  const uuidBySession = new Map()
+
+  ctx.on('llm-pi-ai/request-headers', (request, headers, next) => {
+    // 宿主契约要求监听者必须调用 next()；任何异常都不允许把整次推理打断，
+    // 因此在本地逻辑上失败即「放弃注入、原样放行」。
+    try {
+      if (typeof next !== 'function') return headers
+      if (request === null || typeof request !== 'object') return next()
+      if (headers === null || typeof headers !== 'object' || typeof headers.set !== 'function') return next()
+      if (!isOpenCodeRoute(options, request)) return next()
+      // 已有同名头一律让路：与官方实现、其它插件、静态 headers 配置共存。
+      if (typeof headers.has === 'function' && headers.has(options.header)) return next()
+      const value = headerValueFor(options, uuidBySession, request.sessionId)
+      if (value === undefined) return next()
+      headers.set(options.header, value)
+      if (options.debug) {
+        ctx.logger.info(
+          `[dsh-ocg-session-head] ${options.header}=${value} `
+            + `provider=${String(request.provider)} model=${String(request.model)} `
+            + `purpose=${String(request.purpose ?? 'chat')}`,
+        )
+      }
+    } catch (error) {
+      ctx.logger.warn(
+        `[dsh-ocg-session-head] header preparation skipped: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+    return next()
+  })
+
+  ctx.logger.info(
+    `[dsh-ocg-session-head] ready (header=${options.header} mode=${options.mode} `
+      + `providers=${[...options.providers].join(',') || '(none)'} `
+      + `hostSuffixes=${options.hostSuffixes.join(',') || '(none)'} debug=${String(options.debug)}`
+      + '）—— 需要宿主提供 llm-pi-ai/request-headers 事件（DSH >= 0.2.2-rc.1）',
+  )
+}
+
+export default { name, inject, apply }

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OCG Session Header",
+    "description": "Injects the x-opencode-session header per conversation for OpenCode Go routes via the official request-headers seam."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OCG 会话头",
+    "description": "为 OpenCode Go 路由按会话注入 x-opencode-session 请求头（官方 request-headers 席位实现）。"
+  }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@verneuil/dsh-ocg-session-head",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "OpenCode Go 会话头：监听宿主 llm-pi-ai/request-headers 瀑布，按会话为 ocg 路由注入 x-opencode-session（不猴补丁 fetch、不修改宿主）。",
+  "main": "index.js",
+  "type": "module",
+  "license": "MIT",
+  "author": "verneuil",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verneuil/dsh-ocg-session-head.git"
+  },
+  "homepage": "https://github.com/verneuil/dsh-ocg-session-head#readme",
+  "bugs": {
+    "url": "https://github.com/verneuil/dsh-ocg-session-head/issues"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node scripts/self-test.mjs",
+    "check": "node scripts/ci-check.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "opencode-go",
+    "session-header"
+  ],
+  "meta": {
+    "title": "OCG 会话头",
+    "description": "为 OpenCode Go 路由按会话注入 x-opencode-session 请求头（官方 request-headers 席位实现）。"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}