dsh-router-core 0.3.21 → 0.4.1

package/src/index.ts

@@ -36,12 +36,13 @@ import { ROUTER_API_BASE, type RouterPeriod } from './shared.ts'
 import { Router } from './router/index.ts'
 import { RouterAdapter, type RouterAttachmentStore } from './llm/adapter.ts'
 import { KeysStore } from './keys.ts'
-import { loadSuppliers, wrapModule, type LoadedSupplier } from './suppliers/loader.ts'
+import { loadSuppliers, supplierWins, wrapModule, type LoadedSupplier } from './suppliers/loader.ts'
 import { supplierRoutes } from './suppliers/registry.ts'
-import type { SupplierEnv, SupplierModule } from './suppliers/contract.ts'
+import type { SupplierEnv, SupplierModule, SupplierRegistry } from './suppliers/contract.ts'
 import { SupplierConfigStore } from './supplier-config.ts'
 import { CredentialStore } from './credential-store.ts'
 import { dataDirOf, profileDirOf } from './data-dir.ts'
+import { detectHostVersion, isHost017Plus, supportsLastHitDock } from './host-version.ts'
 import { ExtStore } from './ext/store.ts'
 import type { ExtInfo, ExtStoreService, RouterExt, RouterExtService } from './ext/contract.ts'
 
@@ -54,6 +55,34 @@ export const name = 'dsh-router-core'
 /** Services required before mounting: the webserver (routes) + llm (设置-模型). */
 export const inject = ['webServer', 'llm']
 
+/**
+ * `Config` 导出：让 Router 卡片进 0.1.7 的设置镜像。
+ *
+ * **这处刻意保留能力检测，不用宿主版本号** —— 与另两处兼容点（installSection /
+ * adapter 消息形态）不同。原因（已实测）：这是**模块顶层导出**，loader 一 import
+ * 就求值；而 schemastery 是本插件的**普通依赖**（`^3.18.4`，见 package.json），
+ * 解析到的是**插件自己 node_modules 里那一份**，跟宿主实际加载的版本无关
+ * （实测：插件解析到 3.18.4，而 profile 里是 3.18.3、全局是 3.18.2）。既然这里
+ * 拿不到宿主版本，就只剩「这份 Schema 实例到底有没有 `.volatile`」这个真问题 ——
+ * 能力检测恰好就是**对**的判据。
+ *
+ * 定位说明（非兼容分叉）：`.volatile()` 是 schemastery 3.18.4 才有的原型方法；
+ * 老版本上直写 `Schema.object({}).volatile()` 会 `.volatile` 为 undefined →
+ * 抛 TypeError → **整个插件加载失败**（不只是卡片，是 dsh-router 完全挂掉）。
+ *   - 有 volatile：走 volatile，空 object 不被 volatileForm 过滤 → 卡片进镜像；
+ *   - 无 volatile：回落普通空 schema，不抛；此时宿主必是 0.1.5，本就靠
+ *     installSection 出卡片（见下方按版本分流的注册），这个 Config 无副作用。
+ */
+const emptySchema = Schema.object({})
+const hasVolatile = typeof (emptySchema as { volatile?: unknown }).volatile === 'function'
+
+/**
+ * 0.1.7 的设置镜像只认「插件导出的 Config + 配置树行 id」这条收录链，且空 object
+ * 会被 volatileForm 过滤掉 —— 顶层 `.volatile()` 才能让 Router 卡片出现在设置-模型。
+ * Router 的真配置在自己的 state.json（路由系统面板），这里故意不暴露任何字段。
+ */
+export const Config = hasVolatile ? emptySchema.volatile() : emptySchema
+
 /** Minimal shape of the webServer service face used here. */
 interface WebServerRoute {
   kind: 'prefix' | 'exact'
@@ -96,12 +125,12 @@ interface Llm {
 }
 
 /**
- * 设置服务（`ctx.settings`，dsh-settings）的最小切面：本插件只用 `installSection`
- * 注册一个命名空间，让设置-模型页能列出 Router provider 卡片。dsh-settings 是
- * 宿主注入的 peer service，这里不深绑它的类型，只声明用到的这一个方法。
+ * 设置服务（`ctx.settings`，dsh-settings）的最小切面。0.1.5 用 `installSection`
+ * 注册命名空间；0.1.7 已移除该方法、改由插件导出的 Config 驱动 —— 故声明为可选，
+ * 调用处做能力检测（不是版本分支）。dsh-settings 是宿主注入的 peer service，不深绑类型。
  */
 interface SettingsServiceFace {
-  installSection: (
+  installSection?: (
     owner: CordisContext,
     ns: string,
     schema: unknown,
@@ -156,6 +185,8 @@ export function apply(rawContext: unknown): void {
     logger: { info: (message: string) => void; warn: (message: string) => void }
     effect: (fn: () => () => void, label?: string) => void
     inject: (services: string[], callback: (sctx: unknown) => void) => void
+    /** cordis-plugin-loader 挂在 fiber 上的配置树锚点（tests 等环境可能没有）。 */
+    fiber?: { entry?: { options?: { id?: string } } }
     /** 配置树锚点 = profile 目录（宿主注入），用来把数据钉在 profile 里。 */
     baseUrl?: string
   }
@@ -166,6 +197,12 @@ export function apply(rawContext: unknown): void {
   const dataDir = dataDirOf(ctx.baseUrl)
   const stateFile = join(dataDir, 'state.json')
   log(`data dir: ${dataDir}`)
+  // 宿主版本探测：三处 0.1.5/0.1.7 兼容分叉共用这一个判据（徽章 / 设置命名空间 /
+  // adapter 的 tool-result 消息形态）。探测失败按老版本处理，不影响其它功能。
+  const hostVersion = detectHostVersion(ctx.baseUrl)
+  const host017Plus = isHost017Plus(ctx.baseUrl)
+  const lastHitDock = supportsLastHitDock(ctx.baseUrl)
+  log(`host version: ${hostVersion ?? '未知'} (>=0.1.7: ${host017Plus ? 'yes' : 'no'}, last-hit dock: ${lastHitDock ? 'on' : 'off'})`)
   const store = new SupplierConfigStore(stateFile)
   const credentials = new CredentialStore(join(dataDir, 'auths'))
   const router = new Router(stateFile, store, log)
@@ -180,7 +217,7 @@ export function apply(rawContext: unknown): void {
     disposers.push(ctx.webServer.register({ kind: 'exact', path, handler }))
   }
 
-  // ---- 供应商注册表：内置 + 用户自定义 js + 外部插件供应商 ----
+  // ---- 供应商注册表：行（内置）+ 用户目录 js + 外部插件供应商 ----
   const loadedSuppliers: LoadedSupplier[] = []
   /** 每个供应商的 webServer 路由注销函数（注销时单独清理）。 */
   const supplierDisposers = new Map<string, Array<() => void>>()
@@ -224,23 +261,38 @@ export function apply(rawContext: unknown): void {
 
   // 内置 + 用户 + 外部插件供应商（异步加载，完成后注册路由 + 加入路由器）
   const registerLoaded = (loaded: LoadedSupplier): void => {
+    // 同 id 已有供应商：只有「级别更高」的那个能顶掉它（用户目录 js > 内置行 >
+    // 外部插件）。级别不高不低就直接丢，别把先到的那份卸了又装回来。
+    const existing = loadedSuppliers.find((l) => l.supplier.id === loaded.supplier.id)
+    if (existing !== undefined) {
+      if (!supplierWins(loaded.source, existing.source)) {
+        log(`supplier ${loaded.supplier.id} (${loaded.source}) skipped: ${existing.source} already registered`)
+        return
+      }
+      log(`supplier ${loaded.supplier.id}: ${existing.source} replaced by ${loaded.source}`)
+      unregisterSupplier(loaded.supplier.id)
+    }
     loadedSuppliers.push(loaded)
     router.add(loaded.supplier)
     registerSupplierRoutes(loaded)
   }
   /** 当前由 router.suppliers service 加载的供应商 id（外部插件卸载时全部注销）。 */
   let externalSupplierIds: string[] = []
-  const loadExternal = (suppliers: Record<string, (env: SupplierEnv) => SupplierModule>): void => {
+  const loadExternal = (suppliers: SupplierRegistry): void => {
     for (const [sid, factory] of Object.entries(suppliers)) {
       if (externalSupplierIds.includes(sid)) continue // 已加载（internal/service + inject 可能重复触发）
       try {
         const module = factory({ dataDir, log, store, credentials })
-        const loaded = wrapModule(module, { dataDir, log, store, credentials }, `service router.suppliers.${sid}`)
+        // 工厂上的 source 标签决定 `/health` 怎么报它：内置行标 'builtin'，独立
+        // 安装的供应商插件不标（= external）。面板按这个值分「内置 / 插件」两组，
+        // 标错就把随核心分发的供应商混进插件组了。
+        const kind = factory.source === 'builtin' ? 'builtin' : 'external'
+        const loaded = wrapModule(module, { dataDir, log, store, credentials }, `service router.suppliers.${sid}`, kind)
         registerLoaded(loaded)
         externalSupplierIds.push(loaded.supplier.id)
-        log(`external supplier loaded: ${sid}`)
+        log(`${kind} supplier loaded: ${sid}`)
       } catch (err) {
-        ctx.logger.warn(`[dsh-router] external supplier ${sid} load failed: ${(err as Error).message}`)
+        ctx.logger.warn(`[dsh-router] supplier ${sid} load failed: ${(err as Error).message}`)
       }
     }
   }
@@ -268,7 +320,6 @@ export function apply(rawContext: unknown): void {
       // 用户供应商目录也在 profile 里：跟着 baseUrl 走，别硬编码 `web`。
       const userDir = join(profileDirOf(ctx.baseUrl), 'suppliers')
       const { suppliers, errors } = await loadSuppliers({
-        builtinDir: join(import.meta.dirname, 'suppliers'), // 内置 js（opencode 等）
         userDir,
         dataDir,
         store,
@@ -323,8 +374,17 @@ export function apply(rawContext: unknown): void {
     const lv = typeof peek.reasoning_effort === 'string' && peek.reasoning_effort !== ''
       ? peek.reasoning_effort
       : 'auto'
+    // 宿主会话身份（adapter 从 GenerateOptions.sessionId 转来的内部头）；外部客户端没有。
+    const sessionRaw = req.headers['x-dsh-router-session']
+    const session = typeof sessionRaw === 'string' && sessionRaw !== '' ? sessionRaw : undefined
     await router.chatCompletions(
-      { rawBody: body, stream: !!peek.stream, model: typeof peek.model === 'string' ? peek.model : '', lv },
+      {
+        rawBody: body,
+        stream: !!peek.stream,
+        model: typeof peek.model === 'string' ? peek.model : '',
+        lv,
+        ...(session === undefined ? {} : { session }),
+      },
       res,
     )
   }))
@@ -335,6 +395,10 @@ export function apply(rawContext: unknown): void {
     const { suppliers } = router.status()
     writeJson(res, 200, {
       ok: true,
+      // 宿主版本 + 徽章支持位：客户端据此决定是否挂「最近命中」控件
+      // （composer.dock 在 0.1.5 渲染位置不对，只有 >= 0.1.7 才挂）。
+      hostVersion: hostVersion ?? '',
+      lastHitDock: lastHitDock,
       suppliers: suppliers.map((s) => {
         const loaded = loadedSuppliers.find((l) => l.supplier.id === s.id)
         return {
@@ -344,6 +408,8 @@ export function apply(rawContext: unknown): void {
           apiKeyHint: loaded?.supplier.apiKeyHint,
           capabilities: loaded ? [...loaded.capabilities] : [],
           source: loaded?.source ?? 'external',
+          // 开关状态：关掉的供应商**仍在列表里**（关掉后要能再开），只是不参与路由。
+          enabled: s.enabled,
         }
       }),
     })
@@ -374,6 +440,38 @@ export function apply(rawContext: unknown): void {
     writeJson(res, 200, { ok: true })
   })
 
+  route(`${ROUTER_API_BASE}/last-hit`, (req, res) => {
+    // 最近一次被服务的请求：给输入框旁的小指示器用。
+    // `?session=` 给定时只在该会话内找（当前会话视角）；不给则退回全局最近。
+    // 附上连接显示别名与积分 —— 前端只读这一个端点，不打 status（重）。
+    const session = new URL(req.url ?? '/', 'http://localhost').searchParams.get('session') ?? undefined
+    const last = router.usage.lastHit(session)
+    if (last === undefined) {
+      writeJson(res, 200, { ok: true, hit: null })
+      return
+    }
+    const { suppliers } = router.status()
+    const owner = suppliers.find((s) => s.id === last.supplier)
+    const acct = owner?.accounts.find((a) => a.uid === last.uid)
+    // 连接名：**优先直接查 accountNames**（面板里配的显示别名），不依赖
+    // status 列表里有没有这个号 —— 号未上报/未加载时 status 里就没有它，
+    // 只靠 acct 会回落成 uid（显示成 cb-12 而不是 k8661）。
+    const named = last.uid === undefined || last.uid === '' ? undefined : store.getAccountName(last.supplier, last.uid)
+    writeJson(res, 200, {
+      ok: true,
+      hit: {
+        supplier: last.supplier,
+        model: last.model,
+        requested: last.requested,
+        uid: last.uid,
+        account: named ?? acct?.nickname ?? (last.uid === undefined || last.uid === '' ? undefined : last.uid),
+        credits: acct?.credits,
+        ok: last.ok,
+        ts: last.ts,
+      },
+    })
+  })
+
   route(`${ROUTER_API_BASE}/models`, async (_req, res) => {
     try {
       const models = await router.listModels()
@@ -392,26 +490,26 @@ export function apply(rawContext: unknown): void {
   })
 
   route(`${ROUTER_API_BASE}/combos/create`, async (req, res) => {
-    let body: { name?: string; strategy?: string; models?: string[] }
+    let body: { name?: string; models?: string[] }
     try {
-      body = JSON.parse(await readBody(req, 64 << 10)) as { name?: string; strategy?: string; models?: string[] }
+      body = JSON.parse(await readBody(req, 64 << 10)) as { name?: string; models?: string[] }
     } catch {
       writeJson(res, 400, { ok: false, error: 'invalid JSON body' })
       return
     }
-    const result = router.createCombo(body.name ?? '', body.strategy ?? 'fallback', body.models ?? [])
+    const result = router.createCombo(body.name ?? '', body.models ?? [])
     writeJson(res, result.ok ? 200 : 400, result)
   })
 
   route(`${ROUTER_API_BASE}/combos/update`, async (req, res) => {
-    let body: { id?: string; name?: string; strategy?: string; models?: string[] }
+    let body: { id?: string; name?: string; models?: string[] }
     try {
-      body = JSON.parse(await readBody(req, 64 << 10)) as { id?: string; name?: string; strategy?: string; models?: string[] }
+      body = JSON.parse(await readBody(req, 64 << 10)) as { id?: string; name?: string; models?: string[] }
     } catch {
       writeJson(res, 400, { ok: false, error: 'invalid JSON body' })
       return
     }
-    const result = router.updateCombo(body.id ?? '', body.name ?? '', body.strategy ?? 'fallback', body.models ?? [])
+    const result = router.updateCombo(body.id ?? '', body.name ?? '', body.models ?? [])
     writeJson(res, result.ok ? 200 : 400, result)
   })
 
@@ -528,6 +626,8 @@ export function apply(rawContext: unknown): void {
           ...(e.icon !== undefined ? { icon: e.icon } : {}),
           enabled: extStore.isEnabled(e.id),
           ready: st?.ready === true,
+          // 随核心分发的扩展带这个标记（插件页自绘节据此不重复列它：它已经有原生行）
+          ...(raw.source === 'builtin' ? { source: 'builtin' as const } : {}),
           ...(st?.detail !== undefined ? { detail: st.detail } : {}),
         }
       })
@@ -535,34 +635,6 @@ 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)
-
   // ---- 概览看板：用量统计 ----
 
   /** 解析并校验周期参数（不接受任意字符串）。 */
@@ -590,7 +662,14 @@ export function apply(rawContext: unknown): void {
       bySupplier: s.bySupplier,
       byModel: s.byModel,
       byRequested: s.byRequested,
-      recent: router.usage.recentList(20),
+      // 「最近请求」的「连接」列要显示连接名（uid → 显示别名）。后端一次解析，
+      // 前端不必再拉 /status。无 uid（失败/未服务）→ 返回空串，前端显示「—」。
+      recent: router.usage.recentList(20).map((r) => ({
+        ...r,
+        connection: r.uid === undefined || r.uid === ''
+          ? ''
+          : store.getAccountName(r.supplier, r.uid) ?? r.uid,
+      })),
     })
   })
 
@@ -610,42 +689,55 @@ export function apply(rawContext: unknown): void {
 
   // ---- 设置-模型：Router 提供方（固定卡片，插件注册，不可删）+ 模型目录（= 组合） ----
 
+  // settings ns = 配置树行 id（cordis.patch.yml insert 的 id）—— 0.1.7 设置镜像按
+  // entry.options.id 收录；loader 未挂 entry 时回落到同一默认值，两版一个 ns。
+  const settingsNs = ctx.fiber?.entry?.options?.id ?? 'dsh-router'
+
   // llm 缺失时（如测试环境）跳过，不影响 /v1 核心。
   if (ctx.llm !== undefined) {
-    const LLM_NS = 'llm-dsh-router'
     try {
       const providerReg = ctx.llm.registerConfigurableProviders([
         {
           provider: 'router',
           displayName: 'Router',
-          settingsNs: LLM_NS,
+          settingsNs,
           settingsPath: [],
         },
       ])
       disposers.push(providerReg)
-      disposers.push(ctx.llm.registerModelDiscovery(LLM_NS, async () => {
+      disposers.push(ctx.llm.registerModelDiscovery(settingsNs, async () => {
         const combos = await router.combos()
         return combos.map((c) => ({ id: c.name }))
       }))
       // Router 的配置（组合/密钥/签到）存在 core 自己的 state.json，走插件自己的
-      // 「路由系统」面板；设置-模型 这边**仍必须注册 `llm-dsh-router` 命名空间**。
-      // 原因：设置-模型 的 provider 列表只渲染 settingsNs 能在设置镜像里解析出来的
-      // 行（见 dsh-client-ui-settings-models 的 configurable 过滤）。只调
-      // registerConfigurableProviders 而不注册 section，Router 卡片**不会出现**。
+      // 「路由系统」面板；设置-模型 这边必须让 settingsNs 在设置镜像里能解析出来
+      // （见 dsh-client-ui-settings-models 的 configurable 过滤），否则卡片不出现。
+      // 按宿主版本分流（不再靠 installSection 能力检测）：
+      //   0.1.7+：镜像行来自顶部导出的 volatile Config（ns = 行 id），无需注册；
+      //   0.1.5 ：镜像行来自 settings.installSection。
       // 空 schema = 卡片是入口/占位（该布局下不可提交），真正的配置在路由系统面板。
       const routerSettingsSchema = Schema.object({})
-      ctx.inject(['settings'], (sctx: unknown) => {
-        const settings = (sctx as { settings?: SettingsServiceFace }).settings
-        if (settings === undefined) {
-          log('settings service absent — skip Router settings-section registration')
-          return
-        }
-        settings.installSection(rawContext as CordisContext, LLM_NS, routerSettingsSchema, {}, {
-          setSource: () => {},
-          onChange: () => {},
+      if (isHost017Plus(ctx.baseUrl)) {
+        log(`settings section driven by exported Config (${settingsNs})`)
+      } else {
+        ctx.inject(['settings'], (sctx: unknown) => {
+          const settings = (sctx as { settings?: SettingsServiceFace }).settings
+          if (settings === undefined) {
+            log('settings service absent — skip Router settings-section registration')
+            return
+          }
+          if (settings.installSection === undefined) {
+            // 版本说该走 installSection 但它不在（异常宿主）：只记日志，不抛。
+            log(`settings.installSection absent despite 0.1.5 host (${settingsNs})`)
+            return
+          }
+          settings.installSection(rawContext as CordisContext, settingsNs, routerSettingsSchema, {}, {
+            setSource: () => {},
+            onChange: () => {},
+          })
+          log(`Router settings section registered (${settingsNs})`)
         })
-        log(`Router settings section registered (${LLM_NS})`)
-      })
+      }
       // adapter：模型目录自动带出组合；对话转发到本插件 /v1（组合路由在 /v1 内完成）。
       // 带上组合的上下文窗口：没有它 dsh 的自动压缩算不出阈值、会静默关闭。
       // 图片序列化需要读附件字节：把 ctx.attachments 传给 adapter（dsh-attachment
@@ -655,7 +747,12 @@ export function apply(rawContext: unknown): void {
           const w = router.comboContextWindow(c)
           return { id: c.name, ...(w !== undefined ? { contextWindow: w } : {}) }
         }),
-      }, () => ctx.get('attachments') as RouterAttachmentStore | undefined)))
+      },
+      () => ctx.get('attachments') as RouterAttachmentStore | undefined,
+      undefined,
+      // 第五个参数 = 降级诊断出口：图片读不到会降级成占位文本，原因必须出口
+      // （曾经那条路径是空 catch，issue #8 的回归因此静默了两个内测版本）。
+      (msg) => ctx.logger.warn(`[dsh-router] ${msg}`))))
       log('llm provider (Router) + discovery + adapter registered ok')
       // 预热模型缓存：`comboContextWindow` 只读缓存、不打上游，缓存空着就
       // 报不出窗口。这里后台填一次，让第一次 resolveModel 就有值。
@@ -708,7 +805,7 @@ export function apply(rawContext: unknown): void {
       directory,
       registeredProviders,
       settingsNamespaces,
-      routerNamespaceRegistered: Array.isArray(settingsNamespaces) && settingsNamespaces.includes('llm-dsh-router'),
+      routerNamespaceRegistered: Array.isArray(settingsNamespaces) && settingsNamespaces.includes(settingsNs),
     })
   })
 

package/src/llm/adapter.test.ts

@@ -479,6 +479,80 @@ test('wire：空工具结果发空串，不伪造 (no output) 字面量', async
   assert.equal(tool?.content, '', '空结果就该是空串')
 })
 
+// 0.1.7+ 消息模型：tool 结果是**独立 role:"tool" 消息**、toolCallId 挂消息级，
+// ContentBlockMap 已无 'tool-result' 块。必须原样发 role:"tool"，否则工具结果被
+// 序列化成 role:"user"、夹在 assistant(tool_calls) 与 tool 之间，上游判定失配 → 400
+// code=11148。下面几条锁死新分支；老的 'tool-result' 块路径（≤0.1.6）仍有各自的用例。
+test('wire：0.1.7+ 独立 role:"tool" 消息序列化为 role:"tool"，正确带 tool_call_id', async () => {
+  const body = await captureBody({
+    messages: [
+      { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
+      { role: 'tool', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] },
+    ],
+  })
+  const messages = body.messages as Array<{ role: string; tool_call_id?: string; content: unknown }>
+  const tool = messages.find((m) => m.role === 'tool')
+  assert.ok(tool, '0.1.7 tool 消息必须原样发 role:"tool"')
+  assert.equal(tool.tool_call_id, 'c1', 'tool_call_id 取自消息级 toolCallId')
+  assert.equal(tool.content, 'out', '纯文本重组为字符串')
+  assert.equal(messages.filter((m) => m.role === 'user').length, 0, '不容许被误序列化成 user 消息')
+})
+
+test('wire：0.1.7+ 独立 role:"tool" 消息不带图时不在其后插 user(图)', async () => {
+  // 图片才攒批补 user(图)；纯文本 tool 后面绝不能冒出 user，配对接续必须完整。
+  const body = await captureBody({
+    messages: [
+      { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'a', name: 'bash', arguments: '{}' }] },
+      { role: 'tool', toolCallId: 'a', content: [{ type: 'text', text: 'x' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'done' }] },
+    ],
+  })
+  const messages = body.messages as Array<{ role: string }>
+  // 没有任何位置允许 user 夹在 tool 与下一 assistant 之间。
+  for (let i = 1; i < messages.length; i++) {
+    const m = messages[i]
+    assert.ok(m, `第 ${i} 条缺失`)
+    assert.notEqual(m.role, 'user', `第 ${i} 条不应该是 user（tool 配对接续被插断）`)
+  }
+})
+
+test('wire：0.1.7+ 空 tool 结果发空串（不伪造字面量）', async () => {
+  const body = await captureBody({
+    messages: [{ role: 'tool', toolCallId: 'c2', content: [] }],
+  })
+  const tool = (body.messages as Array<{ role: string; content: string }>).find((m) => m.role === 'tool')
+  assert.equal(tool?.content, '', '空结果该是空串')
+})
+
+/**
+ * tool 结果的两种形态**都必须序列化成 role:'tool'**，且分派只看消息形状、与宿主版本无关。
+ *
+ * 背景（实测）：同一宿主内两种形态都合法 —— 0.1.7 loop-built 走新形态
+ * （独立 role:'tool' 消息），而老会话历史经 session-format 迁移/重放时仍是旧形态
+ * （user 消息里的 'tool-result' 块）。所以 adapter 不能按版本号判形态对错，
+ * 只能按形状分派；这条锁死两种形状在**同一份 adapter**下产物一致。
+ */
+test('wire：tool-result 新/旧两种形态都序列化为 role:"tool"（按形状分派，与版本无关）', async () => {
+  const newShapeMsgs = [
+    { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
+    { role: 'tool', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] },
+  ]
+  const oldShapeMsgs = [
+    { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
+    { role: 'user', content: [{ type: 'tool-result', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] }] },
+  ]
+  // 新形态：原样发 role:'tool'
+  const n = await captureBody({ messages: newShapeMsgs })
+  const nt = (n.messages as Array<{ role: string; tool_call_id?: string }>).find((m) => m.role === 'tool')
+  assert.ok(nt, '新形态应发 role:"tool"')
+  assert.equal(nt.tool_call_id, 'c1')
+  // 旧形态：由 'tool-result' 块转出 role:'tool'（同样带 tool_call_id）
+  const o = await captureBody({ messages: oldShapeMsgs })
+  const ot = (o.messages as Array<{ role: string; tool_call_id?: string }>).find((m) => m.role === 'tool')
+  assert.ok(ot, '旧形态也应转出 role:"tool"')
+  assert.equal(ot.tool_call_id, 'c1')
+})
+
 /**
  * 为什么要有这一条：只不发 `block-end` **并不能**拦住残缺调用。
  *
@@ -609,13 +683,48 @@ test('resolveModel 透传组合的 contextWindow（自动压缩才能算阈值
 
 /* ---------------- 图片序列化：图片必须真正到上游（不静默丢图） ---------------- */
 
-/** 假附件 store：返回指定 mediaType + bytes 的请求版本。 */
+/**
+ * 假附件 store：**按宿主的方式校验请求目标**，返回指定 mediaType + bytes 的请求版本。
+ *
+ * 为什么必须校验：宿主 0.1.6 起把请求目标从 `ImageRequestPolicy`（maxPixels +
+ * maxBytes）换成 `ImageRequestTarget`（width + height + maxBytes），字段不匹配就在
+ * `validateTarget()` 抛错。之前这个假 store **两个参数都不看**（`async () => ({...})`），
+ * 于是插件侧传错字段没有任何测试会发现 —— 生产里图片静默降级成占位文本，跨两个
+ * 内测版本没人察觉（issue #8）。现在假 store 照宿主那样校验，字段写错会当场红。
+ */
 function fakeAttachments(mediaType = 'image/png', data = new TextEncoder().encode('<png-bytes>')): {
-  readImageRequest: () => Promise<{ mediaType: string; data: Uint8Array }>
+  readImageRequest: (
+    ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
+    target: { width: number; height: number; maxBytes: number },
+  ) => Promise<{ mediaType: string; data: Uint8Array }>
+  /** 最近一次收到的请求目标，供断言检查。 */
+  lastTarget?: { width: number; height: number; maxBytes: number }
 } {
-  return {
-    readImageRequest: async () => ({ mediaType, data }),
+  // 用闭包记录而不是 `this`：对象字面量里的箭头函数拿不到宿主对象。
+  // 显式标注类型，否则 `store.lastTarget = …` 会被推断出的窄类型挡下。
+  const store: {
+    readImageRequest: (
+      ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
+      target: { width: number; height: number; maxBytes: number },
+    ) => Promise<{ mediaType: string; data: Uint8Array }>
+    lastTarget?: { width: number; height: number; maxBytes: number }
+  } = {
+    readImageRequest: async (_ref: unknown, target: { width: number; height: number; maxBytes: number }) => {
+      // 与宿主 validateTarget **逐字同规则**：它查的是 width/height/maxBytes 这三个
+      // 键**存在且为正整数**。注意不能写成「遍历传进来的键校验」——那样漏掉整个
+      // 键（0.1.5 的 maxPixels）反而能过，闸门就成了摆设（实测：这么写时把实现改回
+      // maxPixels，45 条测试全绿）。
+      for (const key of ['width', 'height', 'maxBytes']) {
+        const value = (target as unknown as Record<string, unknown>)[key]
+        if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+          throw new Error(`Image request ${key} must be a positive integer.`)
+        }
+      }
+      store.lastTarget = target
+      return { mediaType, data }
+    },
   }
+  return store
 }
 
 /** 用给定 attachments 跑一次 stream()，返回上游收到的 body。 */
@@ -636,6 +745,68 @@ async function captureBodyWith(options: Record<string, unknown>, attachments?: u
   return captured
 }
 
+/* ---------------- 请求目标：形状与像素预算（issue #8 的回归闸门） ---------------- */
+
+test('目标：请求目标是 0.1.6+ 的 target 形状（width/height/maxBytes），没有 0.1.5 的 maxPixels', async () => {
+  const attachments = fakeAttachments()
+  await captureBodyWith({
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:aa', mediaType: 'image/png', bytes: 11, width: 1000, height: 338 } },
+    ] }],
+  }, attachments)
+  const target = attachments.lastTarget
+  assert.ok(target !== undefined, '必须真的调过 readImageRequest')
+  assert.deepEqual(Object.keys(target).sort(), ['height', 'maxBytes', 'width'],
+    '键就是宿主 validateTarget 查的那三个；多一个少一个都会被宿主拒')
+  assert.equal('maxPixels' in (target as unknown as Record<string, unknown>), false,
+    '0.1.5 时代的 maxPixels 不再被宿主接受，带上它等于没传 width/height')
+})
+
+test('目标：大图按 64e4 像素预算等比投影（不放大；小图原样）', async () => {
+  const big = fakeAttachments()
+  await captureBodyWith({
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:bb', mediaType: 'image/png', bytes: 11, width: 4000, height: 3000 } },
+    ] }],
+  }, big)
+  const t = big.lastTarget
+  assert.ok(t !== undefined)
+  // 12MP 投影到 ~64e4 像素内，且不超过预算
+  assert.ok(t.width * t.height <= 64e4, `投影后仍在预算内，实际 ${t.width}x${t.height}`)
+  assert.ok(t.width < 4000 && t.height < 3000, '大图要缩')
+  const small = fakeAttachments()
+  await captureBodyWith({
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:cc', mediaType: 'image/png', bytes: 11, width: 4, height: 2 } },
+    ] }],
+  }, small)
+  assert.deepEqual(small.lastTarget, { width: 4, height: 2, maxBytes: 1024 * 1024 }, '预算内的小图不放大')
+})
+
+test('降级留痕：读图失败会写一条 log，不再静默（issue #8 为什么能静默两个版本）', async () => {
+  const lines: string[] = []
+  const boom = {
+    readImageRequest: async () => { throw new Error('Image request width must be a positive integer.') },
+  }
+  const adapter = new RouterAdapter(
+    'http://x',
+    { comboModels: async () => [] },
+    () => boom as never,
+    undefined,
+    (msg) => lines.push(msg),
+  )
+  globalThis.fetch = (async () => new Response('data: [DONE]\n\n', { status: 200 })) as typeof fetch
+  for await (const _c of adapter.stream({
+    model: 'm',
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:dd', mediaType: 'image/png', bytes: 11, width: 4, height: 2 } },
+    ] }],
+    signal: AbortSignal.timeout(3000),
+  } as never)) { void _c }
+  assert.equal(lines.length, 1, '降级必须留一条痕，否则问题又会是「静默」')
+  assert.match(lines[0] ?? '', /width must be a positive integer/, 'log 要带上真实原因')
+})
+
 test('wire：图片块被序列化成 OpenAI image_url base64 part（不再静默丢图）', async () => {
   const ref = {
     attachmentId: 'sha256:abcdef1234567890',