dsh-router-core 0.3.19 → 0.3.21

package/src/client/ExtTab.tsx

@@ -10,6 +10,7 @@
  */
 import { useEffect, useRef, useState } from 'react'
 import { ROUTER_API_BASE, type RouterExtItem, type RouterExtResponse } from '../shared.ts'
+import { ExtDetail } from './ExtDetail.tsx'
 
 function Icon({ d, size = 18 }: { d: string; size?: number }): JSX.Element {
   return (
@@ -28,6 +29,7 @@ export function ExtTab(): JSX.Element {
   const [items, setItems] = useState<RouterExtItem[]>([])
   const [loaded, setLoaded] = useState(false)
   const [error, setError] = useState('')
+  const [selectedId, setSelectedId] = useState<string | null>(null)
   const mounted = useRef(true)
 
   useEffect(() => {
@@ -79,6 +81,12 @@ export function ExtTab(): JSX.Element {
     }
   }
 
+  // 打开详情视图：用 live item（否则详情里的开关状态不会随列表更新）。
+  const selected = selectedId !== null ? items.find((i) => i.id === selectedId) ?? null : null
+  if (selected !== null) {
+    return <ExtDetail item={selected} onBack={() => setSelectedId(null)} onToggle={toggle} />
+  }
+
   return (
     <div className="dshr-tabBody">
       {error !== '' && (
@@ -92,51 +100,43 @@ export function ExtTab(): JSX.Element {
           <span className="dshr-keyEmptyIcon"><Icon d={I.puzzle} size={30} /></span>
           <p className="dshr-keyEmptyTitle">暂无扩展</p>
           <p className="dshr-keyEmptyDesc">
-            安装扩展插件(如 <code>dsh-router-ext-rtk</code>)后,这里会出现开关
+            安装扩展插件(如 <code>dsh-router-ext-watch</code>)后,这里会出现开关
           </p>
         </div>
       ) : (
-        items.map(item => {
-          const notReady = item.ready === false
-          return (
-            <section key={item.id} className="dshr-card">
-              <div className="dshr-cardHead">
-                <span className="dshr-cardIcon"><Icon d={I.bolt} /></span>
-                <div className="dshr-cardTitle">{item.name}</div>
-                {/* 开关放标题行最右端:.dshr-cardAction 是现成的
-                    margin-left:auto(EndpointTab 的「创建 Key」就靠它),复用不新增。
-                    不可用时禁开——禁了就无从开启成功。 */}
-                <button
-                  type="button"
-                  className={`dshr-toggle dshr-cardAction ${item.enabled ? 'dshr-toggle-on' : ''}`}
-                  role="switch"
-                  aria-checked={!!item.enabled}
-                  disabled={notReady && !item.enabled}
-                  onClick={() => void toggle(item, !item.enabled)}
-                  title={notReady && !item.enabled
-                    ? '当前不可用,无法开启'
-                    : item.enabled ? `关闭 ${item.name}` : `开启 ${item.name}`}
-                >
-                  <span className="dshr-toggleKnob" />
-                </button>
-              </div>
+        <div className="dshr-supplierGrid">
+          {items.map(item => {
+            const notReady = item.ready === false
+            return (
+              <section key={item.id} className="dshr-supplierCard" onClick={() => setSelectedId(item.id)}>
+                <div className="dshr-supplierRow">
+                  {item.icon !== undefined ? (
+                    <img
+                      className="dshr-supplierIcon dshr-extLogo"
+                      src={item.icon}
+                      alt=""
+                      onError={(e) => { e.currentTarget.style.display = 'none' }}
+                    />
+                  ) : (
+                    <span className="dshr-supplierIcon"><Icon d={I.bolt} size={24} /></span>
+                  )}
+                  <div className="dshr-supplierName">{item.name}</div>
+                </div>
 
-              {/* 内容区：说明 + 未就绪红字（左对齐、与卡片图标对齐） */}
-              <div className="dshr-extBody">
-                {item.description !== undefined && item.description !== '' && (
-                  <div className="dshr-muted">{item.description}</div>
-                )}
                 {notReady && (
-                  <div className="dshr-ext-error">
-                    {item.detail !== undefined && item.detail !== ''
-                      ? item.detail
-                      : '未就绪,无法开启'}
+                  <div className="dshr-extCardError">
+                    {item.detail !== undefined && item.detail !== '' ? item.detail : '未就绪'}
                   </div>
                 )}
-              </div>
-            </section>
-          )
-        })
+
+                <div className="dshr-supplierMeta">
+                  <span className="dshr-muted">{item.enabled ? '已启用' : '未启用'}</span>
+                  <span className="dshr-chevron">›</span>
+                </div>
+              </section>
+            )
+          })}
+        </div>
       )}
     </div>
   )

package/src/client/router.css

@@ -923,6 +923,34 @@ html[data-dsh-router-active]:not([data-dsh-taskboard-active]):not([data-dsh-ssh-
   margin-top: 4px;
 }
 
+/* watch 进程行动作区（复制 PID / kill 命令，只读） */
+.dshr-procOps {
+  display: inline-flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 4px;
+  white-space: nowrap;
+}
+
+/* 扩展供应商式小卡片：未就绪红字（描述只在详情页，卡片不放） */
+.dshr-extCardError {
+  color: var(--rs-danger);
+  font-size: 11px;
+}
+
+/* 扩展卡 logo（如 rtk 白底 logo）：黑底 + 内边距,白色 logo 在黑底上显形 */
+.dshr-extLogo {
+  background: #000;
+  padding: 3px;
+  box-sizing: border-box;
+  object-fit: contain;
+}
+
+/* 扩展详情头部右侧的开关（顶到标题行右边，同供应商详情的编辑按钮位） */
+.dshr-extDetailToggle {
+  margin-left: auto;
+}
+
 /* 扩展卡片内容区：文字左对齐，左侧留白与标题行的图标位对齐 */
 .dshr-extBody {
   padding: 10px 14px 12px 48px;

package/src/ext/contract.ts

@@ -25,6 +25,7 @@
  *     file IO —— 落盘位置由核心锚定（不跟 cwd 跑），读写经核心，插件无状态。
  */
 import type { Context } from '@deepseek-ai/cordis'
+import type { IncomingMessage, ServerResponse } from 'node:http'
 
 /** 扩展器唯一 id（注册键）。 */
 export type ExtId = string
@@ -53,8 +54,16 @@ export interface RouterExt {
   readonly name: string
   /** 面板副标题说明。 */
   readonly description?: string
+  /** 卡片/详情图标的 logo URL（可选；缺省用默认图标）。 */
+  readonly icon?: string
   /** 当前运行时状态（ready + 不就绪时的说明）。 */
   getState(): ExtState
+  /**
+   * 通用扩展 API 点（可选）：核心把 `/router/api/ext/{id}/{subpath}` 兜底路由派发进来，
+   * 由扩展器自己裁决/处理（如 watch 的 `processes`/`kill`）。返回 true 表示已处理；
+   * false / 未实现 → 核心回 404。这样扩展的执行面逻辑进插件，核心只加一条通用转发。
+   */
+  api?(subpath: string, req: IncomingMessage, res: ServerResponse): boolean | Promise<boolean>
   /** 卸载清理（表删除时由 dsh-router 调用，可选）。 */
   dispose?(): void
 }
@@ -64,6 +73,8 @@ export interface ExtInfo {
   id: string
   name: string
   description?: string
+  /** 卡片/详情图标 logo URL（可选）。 */
+  icon?: string
   /** 核心持久化的开关（默认关）。 */
   enabled: boolean
   /** 插件报的运行时就绪状态。 */

package/src/index.ts

@@ -525,6 +525,7 @@ export function apply(rawContext: unknown): void {
           id: e.id,
           name: e.name ?? e.id,
           ...(e.description !== undefined ? { description: e.description } : {}),
+          ...(e.icon !== undefined ? { icon: e.icon } : {}),
           enabled: extStore.isEnabled(e.id),
           ready: st?.ready === true,
           ...(st?.detail !== undefined ? { detail: st.detail } : {}),
@@ -534,6 +535,34 @@ export function apply(rawContext: unknown): void {
     writeJson(res, 200, { ok: true, enhancers: list })
   })
 
+  // ---- 扩展通用 API 转发：/router/api/ext/{id}/{subpath} → 该扩展器的 api() ----
+  // watch 这类自定义扩展用它暴露自己的面板接口（如 processes）。分开的 exact 路由
+  // `/ext`（上方）管开关列表；这里必须是 **prefix** 路由兜子路径（`route()` 是 exact,
+  // 匹配不了 `/ext/watch/processes`——用 exact 会造成 404 空 body → 前端 res.json() 崩）。
+  // 核心不知道子路径长什么样——是否处理、怎么处理全由扩展器自己裁决（执行面），核心只转发。
+  const extDispatch = ctx.webServer.register({
+    kind: 'prefix',
+    path: `${ROUTER_API_BASE}/ext/`,
+    handler: async (req, res) => {
+      const pathname = new URL(req.url ?? '/', 'http://localhost').pathname
+      const mount = `${ROUTER_API_BASE}/ext/`
+      const rest = pathname.startsWith(mount) ? pathname.slice(mount.length) : ''
+      const slash = rest.indexOf('/')
+      const extId = slash < 0 ? rest : rest.slice(0, slash)
+      const subpath = slash < 0 ? '' : rest.slice(slash + 1)
+      if (extId === '') {
+        writeJson(res, 404, { ok: false, error: 'extension not found' })
+        return
+      }
+      const ext = (exts[extId] as RouterExt | undefined)
+      if (ext !== undefined && typeof ext.api === 'function' && (await ext.api(subpath, req, res))) {
+        return // 扩展器已处理并写出响应
+      }
+      writeJson(res, 404, { ok: false, error: 'extension api not found' })
+    },
+  })
+  disposers.push(extDispatch)
+
   // ---- 概览看板：用量统计 ----
 
   /** 解析并校验周期参数（不接受任意字符串）。 */

package/src/llm/adapter.test.ts

@@ -11,7 +11,7 @@
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { EMPTY_RESPONSE_CODE } from '@deepseek-ai/dsh-llm'
+import { AssistantStreamAccumulator, EMPTY_RESPONSE_CODE } from '@deepseek-ai/dsh-llm'
 import { toTokenUsage } from '../router/usage-tokens.ts'
 import { RouterAdapter, translateSse } from './adapter.ts'
 
@@ -191,6 +191,59 @@ async function toolCallsOf(...payloads: string[]): Promise<Array<{ name?: string
   return out
 }
 
+test('工具调用：后续 delta 把 id/name 重发成 null 时，不能冲掉首帧也不许发 null', async () => {
+  // 真实事故（2026-09-22，OpenCode/Zen）：上游首帧给 id+name，后续分片帧把
+  // 它们**显式重发成 null**（不是省略、不是空串）。用对象构造、交给 frame() 序列化，
+  // 免得在字符串字面量里跟引号打架。
+  const tcDelta = (tc: unknown): string => frame({ choices: [{ delta: { tool_calls: [tc] } }] })
+  const payloads = [
+    tcDelta({ index: 0, id: 'call_abc', type: 'function', function: { name: 'bash', arguments: '' } }),
+    tcDelta({ index: 0, id: null, type: 'function', function: { name: null, arguments: '{' } }),
+    tcDelta({ index: 0, id: null, type: 'function', function: { name: null, arguments: '"command": "ls"}' } }),
+    frame({ choices: [{ delta: {}, finish_reason: 'tool_calls' }] }),
+    '[DONE]',
+  ]
+
+  // 旧判据是 `!== undefined`，null 通不过它却被当成真值：既把 "bash" 冲成 null，
+  // 又把 `name: null` 发进 StreamChunk。而真实运行路径
+  // （dsh-llm 的 AssistantStreamAccumulator.push）判据是
+  // `Object.hasOwn(chunk,'name') && typeof chunk.name !== 'string'` → 抛
+  // `TypeError: tool-call-delta name must be a string`（用户看到的
+  // 「本轮运行失败 tool-call-delta name must be a string」）。
+  //
+  // 用**真实的那个累加器**验收，而不是自己复述规则：它就是运行时会抛的那一段。
+  const acc = new AssistantStreamAccumulator()
+  let n = 0
+  for await (const chunk of translateSse(payloads)) {
+    acc.push({ time: n++, chunk }) // 这里就是线上抛错的那一步
+  }
+
+  // 逐条再按原判据过一遍，失败时能直接指向违规的那条 delta
+  for await (const chunk of translateSse(payloads)) {
+    if (chunk.type !== 'tool-call-delta') continue
+    if (Object.hasOwn(chunk, 'name')) assert.equal(typeof chunk.name, 'string', 'name 一旦出现就必须是字符串')
+    assert.equal(typeof chunk.id, 'string', 'id 必须是字符串')
+    assert.equal(typeof chunk.argumentsDelta, 'string', 'argumentsDelta 必须是字符串')
+  }
+
+  // 首帧给的 name/id 必须在后续 null 帧里**保持**
+  const deltas: Array<Record<string, unknown>> = []
+  for await (const chunk of translateSse(payloads)) {
+    if (chunk.type === 'tool-call-delta') deltas.push(chunk as unknown as Record<string, unknown>)
+  }
+  assert.ok(deltas.length >= 3, '三个分片帧都该产出 delta')
+  for (const d of deltas) {
+    assert.equal(d.name, 'bash', 'name 被后续 null 帧冲掉了（工具名会变成空）')
+    assert.equal(d.id, 'call_abc', 'id 被后续 null 帧冲掉了')
+  }
+
+  // 收尾后的完整调用也要正确
+  const calls = await toolCallsOf(...payloads)
+  assert.equal(calls.length, 1)
+  assert.equal(calls[0]?.name, 'bash', '工具名必须保住')
+  assert.equal(calls[0]?.arguments, '{"command": "ls"}')
+})
+
 test('工具调用：参数分片发完才收尾，完整 JSON 原样保留', async () => {
   const calls = await toolCallsOf(
     frame({ choices: [{ delta: { tool_calls: [{ index: 0, id: 'c1', function: { name: 'bash', arguments: '' } }] } }] }),

package/src/llm/adapter.ts

@@ -439,9 +439,21 @@ export async function* translateSse(payloads: AsyncIterable<string> | Iterable<s
           toolBlocks.set(key, block)
           yield { type: 'block-start', index: block.index, blockType: 'tool-call' }
         }
-        if (call.id !== undefined) block.callId = call.id
-        if (call.function?.name !== undefined) block.name = call.function.name
-        const fragment = call.function?.arguments ?? ''
+        // 身份字段只认**非空字符串**。上游（OpenCode/Zen）在后续 delta 里会把
+        // 首帧已给过的 id/name 显式重发成 `null`（不是省略、也不是空串）——
+        // 实测帧形状：
+        //   {"index":0,"id":"call_abc","function":{"name":"bash","arguments":""}}
+        //   {"index":0,"id":null,   "function":{"name":null,  "arguments":"{"}}
+        // 用 `!== undefined` 挡不住 null：它既会把首帧的 "bash"/"call_abc" **冲成
+        // null**（工具名丢失），又会把 `name: null` 原样发进 StreamChunk，而
+        // dsh-llm 的校验是 `typeof chunk.name !== 'string'`（Object.hasOwn 先判存在）
+        // → 抛 `TypeError: tool-call-delta name must be a string` →「本轮运行失败」。
+        // 判据与核心 aggregateSSE（非流式聚合路径）保持一致，两条路不能有分歧。
+        if (typeof call.id === 'string' && call.id !== '') block.callId = call.id
+        if (typeof call.function?.name === 'string' && call.function.name !== '') block.name = call.function.name
+        // arguments 同理只认字符串：`?? ''` 挡得住 null/undefined，但挡不住
+        // 上游偶发把参数发成对象/数字——那会撞 dsh-llm 的同一条校验。
+        const fragment = typeof call.function?.arguments === 'string' ? call.function.arguments : ''
         block.text += fragment
         yield {
           type: 'tool-call-delta',

package/src/router/disconnect-leak.test.ts

@@ -198,3 +198,53 @@ test('聚合失败：reader 必须被解绑（否则连接还活着时上层无
   assert.equal(releaseLocked, true, '聚合失败后必须 releaseLock，否则流锁死、上层无法回收')
   assert.equal(failing.locked, false, '流必须处于未锁定状态（可被 cancel / 已被回收）')
 })
+
+test('fixFrame：把后续 delta 里重发成 null 的 id/name 剥掉（否则外部 OpenAI 客户端会丢工具名）', async () => {
+  // 为什么这一层也得修（adapter 的修复保护不到它）：`/v1/chat/completions` 是
+  // **对外**的 OpenAI 兼容端点，外部客户端（Cline/Cursor/其它工具）直接读这条流。
+  // 上游 OpenCode/Zen 在工具调用的后续分片帧里会把首帧已给过的 id/name 显式重发成
+  // null——外部客户端普遍按 `name !== undefined` 判「有没有新值」，于是把已经拿到的
+  // "bash" 冲成 null，表现为 `unknown tool ""`。fixFrame 是核心的**线上归一化层**，
+  // 职责就是抹掉这类不合规的空值（空串早就抹了，null 语义相同）。
+  const enc = new TextEncoder()
+  const sse =
+    'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_abc","type":"function","function":{"name":"bash","arguments":""}}]}}]}\n\n' +
+    'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":null,"type":"function","function":{"name":null,"arguments":"{"}}]}}]}\n\n' +
+    'data: [DONE]\n\n'
+  const upstream = new ReadableStream<Uint8Array>({
+    start(ctrl) { ctrl.enqueue(enc.encode(sse)); ctrl.close() },
+  })
+
+  const router = new Router('')
+  router.add(supplierWith(upstream) as never)
+
+  const server = http.createServer((req, res) => {
+    let body = ''
+    req.on('data', (c) => { body += c })
+    req.on('end', () => {
+      void router.chatCompletions(
+        { model: 'sup,m1', stream: true, rawBody: body } as never,
+        res as never,
+      )
+    })
+  })
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()))
+  const port = (server.address() as { port: number }).port
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: 'sup,m1', messages: [{ role: 'user', content: 'hi' }], stream: true }),
+    })
+    const text = await resp.text()
+    // 第一帧给的 "bash"/"call_abc" 必须还在
+    assert.ok(text.includes('"name":"bash"'), `首帧的工具名丢了：${text.slice(0, 200)}`)
+    assert.ok(text.includes('"id":"call_abc"'), `首帧的 id 丢了：${text.slice(0, 200)}`)
+    // 后续帧的 null 必须被剥掉（不能出现在线上字节里）
+    assert.equal(/"name":null/.test(text), false, `null 的 name 泄漏到了线上：${text.slice(0, 200)}`)
+    assert.equal(/"id":null/.test(text), false, `null 的 id 泄漏到了线上：${text.slice(0, 200)}`)
+  } finally {
+    server.closeAllConnections?.()
+    server.close()
+  }
+})

package/src/router/index.ts

@@ -296,7 +296,16 @@ function isDoneFrame(frame: string): boolean {
   return /(^|\n)data:[ \t]*\[DONE\][ \t]*(\n|$)/.test(frame)
 }
 
-/** 修一帧 SSE：只剥空的 name/id，出任何问题都原样返回。 */
+/**
+ * 修一帧 SSE：剥掉**空的**（`''` 或 `null`）name/id，出任何问题都原样返回。
+ *
+ * 为什么 `null` 也算空：上游（OpenCode/Zen）在后续 delta 里会把首帧已给过的
+ * id/name 显式重发成 `null`——`{"id":null,"function":{"name":null,"arguments":"{"}}`。
+ * 下游判「有没有新值」用的是 `name !== undefined`（dsh 的 BlockAssembler 就是），
+ * null 过不了这个判断、却也不该覆盖首帧：客户端会把已拿到的 "bash" 冲成 null，
+ * 工具名丢失（表现为 `unknown tool ""`）。空串早就剥了，null 语义上同样是
+ * 「本帧没给新值」，一并剥掉。
+ */
 function fixFrame(frame: string): string {
   // 绝大多数帧没有 tool_calls，先廉价字符串筛查，避免无谓的 JSON 解析
   if (!frame.includes('tool_calls')) return frame
@@ -314,9 +323,13 @@ function fixFrame(frame: string): string {
       const tcs = delta?.tool_calls as Array<Record<string, unknown>> | undefined
       if (Array.isArray(tcs)) {
         for (const tc of tcs) {
-          if (tc.id === '') { delete tc.id; changed = true }
+          // 空串与 null 都是「本帧没给新值」，剥掉让下游沿用首帧那个
+          if (tc.id === '' || tc.id === null) { delete tc.id; changed = true }
           const fn = tc.function as Record<string, unknown> | undefined
-          if (fn !== null && typeof fn === 'object' && fn.name === '') { delete fn.name; changed = true }
+          if (fn !== null && typeof fn === 'object' && (fn.name === '' || fn.name === null)) {
+            delete fn.name
+            changed = true
+          }
         }
       }
       return changed ? `data: ${JSON.stringify(obj)}` : line

package/src/shared.ts

@@ -143,6 +143,8 @@ export interface RouterExtItem {
   id: string
   name: string
   description?: string
+  /** 卡片/详情图标 logo URL（可选）。 */
+  icon?: string
   /** 是否启用改写（面板开关）。 */
   enabled?: boolean
   /** 运行时是否就绪（如 RTK 二进制是否可用）。 */
@@ -158,6 +160,25 @@ export interface RouterExtResponse {
   enhancers?: RouterExtItem[]
 }
 
+/** 一行 watch 进程（`/router/api/ext/watch/processes`）。 */
+export interface RouterWatchProcess {
+  pid: number
+  ppid: number
+  /** %cpu 快照 */ cpu: number
+  /** %mem 快照 */ mem: number
+  command: string
+  /** 命中的已记录 agent 命令。 */
+  match: string
+  recordedAt: number
+}
+
+/** `/router/api/ext/{id}/processes` response。 */
+export interface RouterWatchResponse {
+  ok: boolean
+  error?: string
+  processes?: RouterWatchProcess[]
+}
+
 /** 供应商模型（含启用状态）。 */
 export interface RouterSupplierModel {
   id: string

package/src/suppliers/opencode/plugin.test.ts

@@ -0,0 +1,176 @@
+/**
+ * opencode(Zen 免费档)握手契约测试 —— 锁住 2026-09-22 实测的那组硬门。
+ *
+ * 为什么值得固化：这四条**都不是可选优化，缺一即 403**
+ * `FreeTierError: OpenCode's free tier can only be used from within OpenCode`。
+ * 它们全是「看不出来」的那种约定——代码删掉一行 headers、或把 UA 改回
+ * `opencode`，单测本该立刻变红，否则下次只能在真机对话里发现整个供应商死了。
+ *
+ * 实测依据（2026-09-22，逐项消融验证）：
+ *   - UA 必须带版本且 ≥1.18：裸 `opencode`→403；`opencode/1.17.x`→426；1.18.0 起 200
+ *   - 必须同时有 `x-opencode-session`/`x-opencode-request`，且形状是
+ *     `ses_<12hex><14base62>` / `msg_<同形状>`——格式错也 403
+ *   - tools 里必须**同时**有 bash 和 read，只给一个也 403
+ *   - 非流式（`stream:false`）即使三样齐全也 403 → 必须恒发 stream:true
+ *
+ * 用 node --test 跑（Node 原生剥 TS 类型）：
+ *   node --test src/suppliers/opencode/plugin.test.ts
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import factory from './plugin.ts'
+import { SupplierConfigStore } from '../../supplier-config.ts'
+import type { CredentialStore } from '../../credential-store.ts'
+import type { SupplierEnv, SupplierModule } from '../contract.ts'
+import type { ChatRequest } from '../../router/types.ts'
+
+/** 上游认的 session/request id 形状：前缀 + 12 位小写 hex + 14 位 base62。 */
+const SES_RE = /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/
+const MSG_RE = /^msg_[0-9a-f]{12}[0-9A-Za-z]{14}$/
+
+interface Captured {
+  url: string
+  headers: Record<string, string>
+  body: Record<string, unknown>
+}
+
+/** 打桩 globalThis.fetch，接住一次请求（上游返回空 SSE 流即可）。 */
+function stubFetch(): { captured: Captured[]; restore: () => void } {
+  const captured: Captured[] = []
+  const real = globalThis.fetch
+  globalThis.fetch = (async (url: string, init?: { headers?: Record<string, string>; body?: string }) => {
+    captured.push({
+      url: String(url),
+      headers: init?.headers ?? {},
+      body: init?.body !== undefined ? (JSON.parse(init.body) as Record<string, unknown>) : {},
+    })
+    return new Response(new ReadableStream<Uint8Array>({ start: (c) => c.close() }), { status: 200 })
+  }) as unknown as typeof fetch
+  return { captured, restore: () => { globalThis.fetch = real } }
+}
+
+/** 造一个最小 env（store 空文件路径 = 纯内存，credentials 用不着的空壳）。 */
+function makePlugin(): SupplierModule {
+  const store = new SupplierConfigStore('')
+  const env: SupplierEnv = {
+    dataDir: '/tmp',
+    log: () => {},
+    store,
+    credentials: {} as CredentialStore,
+  }
+  return factory(env)
+}
+
+function request(over: Partial<ChatRequest> = {}): ChatRequest {
+  return {
+    model: 'big-pickle',
+    stream: true,
+    rawBody: JSON.stringify({ model: 'big-pickle', messages: [{ role: 'user', content: 'hi' }] }),
+    ...over,
+  }
+}
+
+test('chatOnce 必须带版本化 UA + 合法形状的 session/request 头', async () => {
+  const stub = stubFetch()
+  try {
+    const r = await makePlugin().chatOnce('', 'auto', request())
+    assert.equal(r.ok, true, '握手齐全时应当成功')
+    const h = stub.captured[0]!.headers
+
+    // UA 必须带版本号（裸 'opencode' 会被上游按非 CLI 拒掉）
+    assert.match(h['User-Agent'] ?? '', /^opencode\/\d+\.\d+/, 'UA 必须带 opencode/ 版本号')
+
+    // session/request 形状不对上游是**拒绝**而不是忽略 —— 形状必须严格
+    assert.match(h['x-opencode-session'] ?? '', SES_RE, 'x-opencode-session 形状不对会被 403')
+    assert.match(h['x-opencode-request'] ?? '', MSG_RE, 'x-opencode-request 形状不对会被 403')
+  } finally {
+    stub.restore()
+  }
+})
+
+test('请求体恒为流式，且 tools 同时含 bash 与 read', async () => {
+  const stub = stubFetch()
+  try {
+    // 调用方明确要非流式 —— 上游免费档对非流式一律 403，插件必须翻成流式
+    await makePlugin().chatOnce('', 'auto', request({ stream: false }))
+    const body = stub.captured[0]!.body
+    assert.equal(body.stream, true, '免费档只支持流式，非流式必须翻成 stream:true')
+
+    const names = (body.tools as Array<{ function?: { name?: string } }>).map((t) => t.function?.name)
+    assert.ok(names.includes('bash'), 'tools 缺 bash 会被 403')
+    assert.ok(names.includes('read'), 'tools 缺 read 会被 403')
+  } finally {
+    stub.restore()
+  }
+})
+
+test('调用方自带的同名工具不被占位工具覆盖（bash/read 只补缺）', async () => {
+  const stub = stubFetch()
+  try {
+    const realBash = {
+      type: 'function',
+      function: { name: 'bash', description: 'REAL BASH', parameters: { type: 'object', properties: { command: { type: 'string' } } } },
+    }
+    await makePlugin().chatOnce('', 'auto', request({
+      rawBody: JSON.stringify({ model: 'big-pickle', messages: [], stream: true, tools: [realBash] }),
+    }))
+    const tools = stub.captured[0]!.body.tools as Array<{ function: { name: string; description?: string } }>
+
+    const bash = tools.filter((t) => t.function.name === 'bash')
+    assert.equal(bash.length, 1, 'bash 不能被注入成两条（否则真实工具签名被挤掉）')
+    assert.equal(bash[0]!.function.description, 'REAL BASH', '调用方自己的定义必须原样保留')
+
+    // read 缺失 → 补上；bash 已有 → 不重复
+    assert.ok(tools.some((t) => t.function.name === 'read'), '缺的 read 要补上')
+  } finally {
+    stub.restore()
+  }
+})
+
+test("effort='off' 必须删字段而不是下发（上游没有这个值，会 400）", async () => {
+  const stub = stubFetch()
+  try {
+    // 关键：rawBody 里**本来就带** reasoning_effort/reasoning_summary。
+    // 不种这两个字段的话，「删」与「什么都不做」结果一样，闸门形同虚设
+    // （实测过：把 else-if 的 'off' 分支去掉，测试照样全绿）。
+    await makePlugin().chatOnce('', 'off', request({
+      rawBody: JSON.stringify({
+        model: 'big-pickle',
+        messages: [],
+        stream: true,
+        reasoning_effort: 'high',
+        reasoning_summary: 'auto',
+      }),
+    }))
+    const body = stub.captured[0]!.body
+    assert.equal('reasoning_effort' in body, false, "off 要删字段：上游收到 'off' 直接 400 invalid_request_error")
+    assert.equal('reasoning_summary' in body, false, 'reasoning_summary 一并删掉')
+  } finally {
+    stub.restore()
+  }
+})
+
+test("effort='auto' 不动调用方自己的 reasoning_effort（不误删）", async () => {
+  const stub = stubFetch()
+  try {
+    await makePlugin().chatOnce('', 'auto', request({
+      rawBody: JSON.stringify({ model: 'big-pickle', messages: [], stream: true, reasoning_effort: 'high' }),
+    }))
+    const body = stub.captured[0]!.body
+    assert.equal(body.reasoning_effort, 'high', 'auto = 不显式下发，调用方原值必须留着')
+  } finally {
+    stub.restore()
+  }
+})
+
+test('非 free 模型报 no_such_model（不记账、不冷号）', async () => {
+  const stub = stubFetch()
+  try {
+    const r = await makePlugin().chatOnce('', 'auto', request({ model: 'gpt-5.5' }))
+    assert.equal(r.ok, false)
+    assert.equal(r.ok === false ? r.state : '', 'no_such_model', '模型不属于本供应商 → 核心换供应商而不是冷号')
+    assert.equal(stub.captured.length, 0, '不属于自己的模型不该打上游')
+  } finally {
+    stub.restore()
+  }
+})