dsh-router-core 0.4.0 → 0.4.2

package/src/llm/adapter.ts

@@ -8,7 +8,9 @@
  * `image` 块序列化成 OpenAI 标准的 `image_url` base64 part，经 /v1 原样透传给
  * 命中的上游供应商。最终能否看图取决于**命中的那个上游模型**——组合里是异构
  * 供应商，可能在网关端声明了图片能力、某条上游却只收文本（此时由上游自行拒收）。
- * 图片字节从 `ctx.attachments` 读取（读不到的按稳定占位文本降级，绝不静默丢图）。
+ * 图片字节从 `ctx.attachments` 读取。读不到时按稳定占位文本降级（不让整条消息失败），
+ * 但**必须留痕**：降级原因走 adapter 的 `log` 出口打到宿主 logger。曾经这里是
+ * 一个空 `catch {}`，字段改名导致的读图失败静默了跨两个内测版本（issue #8）。
  */
 import {
   EMPTY_RESPONSE_CODE,
@@ -31,15 +33,58 @@ import { mergeUsage, normalizeUsage, toTokenUsage, type UsageTokens } from '../r
  * 这一行为，不引入对 dsh-attachment 包编译期/运行期的依赖（它是宿主注入的
  * devDependency）。本地声明与原包 `AttachmentStore.readImageRequest` 形状一致，
  * 宿主注入真实 store 时天然满足。
+ *
+ * ⚠️ **第二个参数是 `ImageRequestTarget`（`width` + `height` + `maxBytes`），
+ * 不是 0.1.5 时代的 `ImageRequestPolicy`（`maxPixels` + `maxBytes`）**。宿主从
+ * 0.1.6 起在 `validateTarget()` 里校验这三个字段，缺一个就抛
+ * `Image request width must be a positive integer`，读图整体失败（issue #8）。
+ * 这两个字段不是摆设：宿主的 `pipeline()` 按 **target 的长边**把图缩到该尺寸，
+ * 短边由它自己推 —— 所以这里传投影后的尺寸，就是「按预算给我这张图」。
  */
 export interface RouterAttachmentStore {
   readImageRequest(
     ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
-    policy: { maxPixels: number; maxBytes: number },
+    target: { width: number; height: number; maxBytes: number },
     signal?: AbortSignal,
   ): Promise<{ mediaType: string; data: Uint8Array }>
 }
 
+/** 送上游的请求图的像素预算（宽 × 高），沿用 0.1.5 时代 `maxPixels` 的意图。 */
+const MAX_REQUEST_PIXELS = 64e4
+/** 送上游的请求图的字节上限。 */
+const MAX_REQUEST_BYTES = 1024 * 1024
+
+/**
+ * 把源图尺寸投影到「总像素 ≤ maxPixels」的请求目标（等比、只缩不放）。
+ *
+ * 为什么需要它：宿主 0.1.6 起要的是 `ImageRequestTarget`（width/height/maxBytes），
+ * 而「别把一张 12MP 手机照原样塞进对话」这个意图原本靠 `maxPixels` 表达。
+ * 宿主自己**只按 target 的长边**缩放、短边由它推，所以我们要做的只是给出一组
+ * 落在预算内的正整数；短边取 floor 即可（它只参与校验与缓存键，不决定出图尺寸）。
+ *
+ * 没有直接复用官方的 `requestImageDimensions`（`@deepseek-ai/dsh-attachment` 有导出）：
+ * 本文件刻意不依赖那个包（见 `RouterAttachmentStore` 的说明 —— 它是宿主注入的
+ * devDependency，引入它等于给插件加一条编译期/运行期依赖）。这 8 行是纯函数、
+ * 有测试钉住；真要换成官方实现时，语义等价。
+ */
+export function projectImageDimensions(
+  width: number,
+  height: number,
+  maxPixels: number,
+): { width: number; height: number } {
+  const pixels = width * height
+  // 尺寸缺失/非法时不投影：让宿主自己的校验去报错，别在这里造一个假尺寸掩盖问题
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    return { width, height }
+  }
+  if (pixels <= maxPixels) return { width, height }
+  const scale = Math.sqrt(maxPixels / pixels)
+  return {
+    width: Math.max(1, Math.floor(width * scale)),
+    height: Math.max(1, Math.floor(height * scale)),
+  }
+}
+
 /** 一张 image 块的 attachment ref 的最小形状（value 类型，够用即可）。 */
 interface RouterImgLike {
   attachmentId: string
@@ -96,7 +141,7 @@ const TOOL_RESULT_IMAGE_TEXT = 'Tool result images'
  */
 const STREAM_IDLE_TIMEOUT_MS = 300_000
 
-async function wireMessages(options: GenerateOptions, system: string | undefined, attachments: RouterAttachmentStore | undefined): Promise<Array<Record<string, unknown>>> {
+async function wireMessages(options: GenerateOptions, system: string | undefined, attachments: RouterAttachmentStore | undefined, log?: (msg: string) => void): Promise<Array<Record<string, unknown>>> {
   const out: Array<Record<string, unknown>> = []
   /**
    * 攒着「tool-result 里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
@@ -157,7 +202,7 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       // 图片不能放进 tool 消息（实测模型会把两张不同图认成同一张），也不能插在两条 tool
       // 之间（同样 400），所以先攒进 pending，等整串 tool 发完再补一条 user(图)。
       const toolCallId = (message as { toolCallId?: unknown }).toolCallId
-      const parts = await contentParts(message.content, attachments, options.signal)
+      const parts = await contentParts(message.content, attachments, options.signal, log)
       const imageParts = parts.filter((p) => p.type !== 'text')
       const text = parts
         .filter((p) => p.type === 'text')
@@ -176,6 +221,7 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       message.content.filter((b) => b.type !== 'tool-result'),
       attachments,
       options.signal,
+      log,
     )
     // 有实质 user 内容（或压根没有 tool 结果）就先发这条 user 消息；
     // 只有 tool 结果的「纯工具」消息不发空 user，图片留到 pending 里合并。
@@ -189,7 +235,7 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       // 11148「tool calls and tool results do not match」。
       // 图片不能放进 tool 消息（实测模型会把两张不同的图认成同一张），
       // 也不能插在两条 tool 之间（同样 400），所以先攒起来、发完整串再补一条 user。
-      const parts = await contentParts(result.content, attachments, options.signal)
+      const parts = await contentParts(result.content, attachments, options.signal, log)
       const imageParts = parts.filter((p) => p.type !== 'text')
       const text = parts.filter((p) => p.type === 'text').map((p) => (p as { text?: string }).text ?? '').join('')
       // 空结果就发空串，不要替换成 '(no output)' 之类的字面量 —— 模型会
@@ -224,6 +270,7 @@ async function contentParts(
   blocks: ReadonlyArray<{ type: string }>,
   attachments: RouterAttachmentStore | undefined,
   signal: AbortSignal | undefined,
+  log?: (msg: string) => void,
 ): Promise<Array<Record<string, unknown>>> {
   const parts: Array<Record<string, unknown>> = []
   for (const block of blocks) {
@@ -234,11 +281,11 @@ async function contentParts(
     }
     if (block.type === 'image') {
       const ref = (block as unknown as { attachment: RouterImgLike }).attachment
-      parts.push(...(await imageParts(ref, attachments, signal)))
+      parts.push(...(await imageParts(ref, attachments, signal, log)))
       continue
     }
     if (block.type === 'tool-result') {
-      parts.push(...(await contentParts((block as unknown as { content: ReadonlyArray<{ type: string }> }).content, attachments, signal)))
+      parts.push(...(await contentParts((block as unknown as { content: ReadonlyArray<{ type: string }> }).content, attachments, signal, log)))
     }
     // 其它块（reasoning/tool-call）不属于 user content，忽略
   }
@@ -250,16 +297,23 @@ async function imageParts(
   ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
   attachments: RouterAttachmentStore | undefined,
   signal: AbortSignal | undefined,
+  log?: (msg: string) => void,
 ): Promise<Array<Record<string, unknown>>> {
-  if (attachments === undefined) return [{ type: 'text', text: imagePlaceholder(ref.attachmentId) }]
+  if (attachments === undefined) {
+    log?.('图片附件 store 不可用（ctx.attachments 未注入），该图降级为占位文本')
+    return [{ type: 'text', text: imagePlaceholder(ref.attachmentId) }]
+  }
+  const ref0 = { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height }
+  // 目标 = 源尺寸按 64e4 像素预算等比投影后的宽高 + 字节上限（0.1.6+ 的 target 形状）
+  const target = { ...projectImageDimensions(ref.width, ref.height, MAX_REQUEST_PIXELS), maxBytes: MAX_REQUEST_BYTES }
   try {
-    const img = await attachments.readImageRequest(
-      { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height },
-      { maxPixels: 64e4, maxBytes: 1024 * 1024 },
-      signal,
-    )
+    const img = await attachments.readImageRequest(ref0, target, signal)
     return [{ type: 'image_url', image_url: { url: `data:${img.mediaType};base64,${bytesToBase64(img.data)}` } }]
-  } catch {
+  } catch (err) {
+    // 曾经这里是空 catch：宿主把请求目标从 maxPixels 换成 width/height 之后读图
+    // 全失败，图被静默换成占位文本，跨两个内测版本没被发现（issue #8）。降级仍然
+    // 保留（不能让整条消息失败），但原因必须出口。
+    log?.(`读取图片 ${ref.attachmentId} 失败，已降级为占位文本：${(err as Error).message}`)
     return [{ type: 'text', text: imagePlaceholder(ref.attachmentId) }]
   }
 }
@@ -280,8 +334,8 @@ function imagePlaceholder(attachmentId: string): string {
 }
 
 /** 组装 wire 请求体。图片序列化需要读 attachments，故为异步。 */
-async function wireRequest(options: GenerateOptions, attachments: RouterAttachmentStore | undefined): Promise<Record<string, unknown>> {
-  const messages = await wireMessages(options, options.system, attachments)
+async function wireRequest(options: GenerateOptions, attachments: RouterAttachmentStore | undefined, log?: (msg: string) => void): Promise<Record<string, unknown>> {
+  const messages = await wireMessages(options, options.system, attachments, log)
   const body: Record<string, unknown> = {
     model: options.model,
     messages,
@@ -580,27 +634,38 @@ const ROUTER_REASONING_EFFORTS: readonly LlmReasoningEffortInfo[] = [
 ]
 
 export class RouterAdapter extends LlmAdapter {
-  private readonly baseURL: string
+  /**
+   * 网关端点。**函数形态 = 每次请求现算**：端口要等宿主 listen 完才有值的场景
+   * 必须传函数（写死 3080 在桌面端等非 3080 宿主上全线 `fetch failed`，
+   * issue #9），见 `host-base-url.ts`。
+   */
+  private readonly baseURL: string | (() => string)
   private readonly source: RouterAdapterSource
   private readonly resolveAttachments: () => RouterAttachmentStore | undefined
   /** 流空闲超时（ms）：上游这么久不吐字节就判 TIMEOUT。 */
   private readonly idleTimeoutMs: number
+  /** 降级/失败诊断的出口（宿主接 ctx.logger.warn）。缺省丢弃 —— 仅为测试可注入。 */
+  private readonly log: ((msg: string) => void) | undefined
 
   /**
    * @param idleTimeoutMs 流空闲超时；缺省用生产值（300s，对齐 pi-ai）。
    *   可注入只为测试能压到几百毫秒，生产不传。
+   * @param log 降级诊断出口。图片读不到时会降级成占位文本，原因走这里 ——
+   *   曾经那条路径是个空 `catch`，出问题跨版本都没人发现（issue #8）。
    */
   constructor(
-    baseURL: string,
+    baseURL: string | (() => string),
     source: RouterAdapterSource,
     resolveAttachments?: () => RouterAttachmentStore | undefined,
     idleTimeoutMs: number = STREAM_IDLE_TIMEOUT_MS,
+    log?: (msg: string) => void,
   ) {
     super()
     this.baseURL = baseURL
     this.source = source
     this.resolveAttachments = resolveAttachments ?? (() => undefined)
     this.idleTimeoutMs = idleTimeoutMs
+    this.log = log
   }
 
   providerInfo(provider: string): { id: string; name: string } {
@@ -647,13 +712,17 @@ export class RouterAdapter extends LlmAdapter {
   }
 
   async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    const body = await wireRequest(options, this.resolveAttachments())
+    const body = await wireRequest(options, this.resolveAttachments(), this.log)
     const controller = new AbortController()
     const onAbort = (): void => controller.abort()
     options.signal?.addEventListener('abort', onAbort, { once: true })
     let resp: Response
     try {
-      resp = await fetch(`${this.baseURL}/chat/completions`, {
+      // 端点现算：宿主监听端口在 listen 之后才有值、也会随宿主重启变（issue #9）。
+      // 解析器自己抛错时也落进下面这个 catch，于是「端口拿不到」是以
+      // LlmError 消息报出来的，而不是一句无从查证的 `fetch failed`。
+      const base = typeof this.baseURL === 'function' ? this.baseURL() : this.baseURL
+      resp = await fetch(`${base}/chat/completions`, {
         method: 'POST',
         // attributionHeaders() 是 dsh-llm 对 adapter 的硬契约：每个 provider
         // 请求都必须带（LlmAdapter 类注释原话）。它给出

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

@@ -158,28 +158,24 @@ test('客户端断开：上游流 cancel 链要穿过 tapStreamUsage / normalize
   assert.equal(leak.cancelled(), true, '取消必须穿过两层 wrapper 到达上游')
 })
 
-test('聚合失败：reader 必须被解绑（否则连接还活着时上层无法 cancel）', async () => {
+test('聚合失败：上游流必须被回收（解锁，不能永久锁死）', async () => {
   // 这一条测的**不是**「cancel 回调有没有触发」——那测不出东西：
   // 实测结论（两个都验过）：
   //   - 流 error 后调 cancel()，只会以同一错误 reject，**不触发** cancel 回调
   //     （`pull()` 抛错会把流置为 errored；上游拆连接则流直接 error）
   //   - 这两种情况下 undici **已经自己关了连接**，不需要我们 cancel
-  // 所以聚合失败路径真正要保证的是 **reader 被解绑**：流锁着的话，上层
+  // 所以聚合失败路径真正要保证的是 **上游流不再被锁着**：锁着的话上层
   // （writeChatResult 的失败路径 / 未来的取消逻辑）想 cancel 都会抛
   // `Invalid state: ReadableStream is locked`，连接就永久漏了。
-  let releaseLocked = false
+  //
+  // 注意拓扑：核心现在隔着「首字节截止」wrapper（withFirstByteDeadline）读上游，
+  // 所以判据只能是**最终状态**（locked=false），不能再断言核心直接 releaseLock
+  // 上游的 reader —— 中间隔了一层，核心只会解锁 wrapper 那个 reader。
   const enc = new TextEncoder()
   const failing = new ReadableStream<Uint8Array>({
     start(c) { c.enqueue(enc.encode('data: {"choices":[{"delta":{"content":"a"}}]}\n\n')) },
     pull() { throw new Error('aggregate read failed') },
   })
-  const origGetReader = failing.getReader.bind(failing)
-  ;(failing as unknown as { getReader: () => unknown }).getReader = () => {
-    const r = origGetReader()
-    const origRelease = r.releaseLock.bind(r)
-    r.releaseLock = () => { releaseLocked = true; origRelease() }
-    return r
-  }
 
   const router = new Router('')
   router.add(supplierWith(failing) as never)
@@ -195,8 +191,7 @@ test('聚合失败：reader 必须被解绑（否则连接还活着时上层无
   )
   await new Promise((r) => setTimeout(r, 150))
 
-  assert.equal(releaseLocked, true, '聚合失败后必须 releaseLock，否则流锁死、上层无法回收')
-  assert.equal(failing.locked, false, '流必须处于未锁定状态（可被 cancel / 已被回收）')
+  assert.equal(failing.locked, false, '上游流必须处于未锁定状态（可被 cancel / 已被回收）')
 })
 
 test('fixFrame：把后续 delta 里重发成 null 的 id/name 剥掉（否则外部 OpenAI 客户端会丢工具名）', async () => {

package/src/router/first-byte-budget.test.ts

@@ -0,0 +1,160 @@
+/**
+ * 首字节预算测试 —— 组合的一条腿「连上了、200 了、就是不吐字节」时必须降级。
+ *
+ * 2026-09-24 夜里的现场（usage.json / 三个 session 的 step 时间线互相对齐）：
+ * money 组合第一腿 codebuddy-en 卡住，ttfb 分别 84s / 122s / 151s / 244s / 246s /
+ * 250s / 254s / 255s，**8 次全部 ok: true**——全都最终成功了，只是晚了四分钟。
+ * 用户干等 200 多秒手动暂停。
+ *
+ * 为什么以前不会降级：停滞既不是成功也不是失败，所以
+ *   - 插件的 120s 只守「连接 + 响应头」（fetch 一返回就撤表），守不到 body
+ *   - 核心写响应的路径没有计时器，组合链卡在这一条腿上一动不动
+ *   - 该号也不会被冷却（没失败 → noteFailure 不触发）→ 下次还挑它
+ *
+ * 这里守的是修复后的语义：**预算到就判失败，链往前走**。没装这个闸门时
+ * 下面两条测试都会在 5s 的看门狗里超时变红（而不是把测试进程挂死）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import type { ServerResponse } from 'node:http'
+import { Router, withFirstByteDeadline } from './index.ts'
+import { AccountPool } from './account-pool.ts'
+import type { ModelInfo } from './types.ts'
+import type { AccountPool as Pool } from './account-pool.ts'
+import type { ChatOnceResult, SupplierAccountNow, SupplierStatusNow } from '../suppliers/contract.ts'
+
+const enc = new TextEncoder()
+
+/** 永不吐字节的流（模拟「200 响应头到手，body 停摆」），记录有没有被 cancel。 */
+function stallingStream(): { stream: ReadableStream<Uint8Array>; cancelled: () => boolean } {
+  let cancelled = false
+  const stream = new ReadableStream<Uint8Array>({
+    cancel() { cancelled = true },
+  })
+  return { stream, cancelled: () => cancelled }
+}
+
+/** 立刻吐一帧 + [DONE] 的正常流。 */
+function healthyStream(text: string): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      ctrl.enqueue(enc.encode(`data: {"choices":[{"delta":{"content":"${text}"}}]}\n\n`))
+      ctrl.enqueue(enc.encode('data: [DONE]\n\n'))
+      ctrl.close()
+    },
+  })
+}
+
+function supplier(id: string, uids: string[], chatOnce: (uid: string) => Promise<ChatOnceResult>) {
+  const accounts: SupplierAccountNow[] = uids.map((uid) => ({ uid, credits: 0, state: 'ok' as const }))
+  return {
+    id, name: id, priority: 0, pool: new AccountPool(id) as Pool,
+    status: (): SupplierStatusNow => ({ id, name: id, accounts }),
+    listModels: async (): Promise<ModelInfo[]> => [{ id: 'm1' }],
+    getAlias: () => id,
+    accounts: () => accounts,
+    chatOnce,
+    dispose: () => {},
+  }
+}
+
+function captureRes(): { res: ServerResponse; body: () => string } {
+  const chunks: string[] = []
+  const text = (chunk: unknown): string =>
+    chunk instanceof Uint8Array ? new TextDecoder().decode(chunk) : String(chunk)
+  const res = {
+    writableEnded: false,
+    destroyed: false,
+    writeHead: (): unknown => undefined,
+    write: (chunk?: unknown): boolean => { chunks.push(text(chunk)); return true },
+    end: (chunk?: unknown): unknown => { if (chunk !== undefined) chunks.push(text(chunk)); return undefined },
+    once: (): unknown => undefined,
+    removeListener: (): unknown => undefined,
+    destroy: (): unknown => undefined,
+  } as unknown as ServerResponse
+  return { res, body: () => chunks.join('') }
+}
+
+const req = {
+  model: 'c',
+  stream: true,
+  rawBody: JSON.stringify({ model: 'c', messages: [{ role: 'user', content: 'hi' }], stream: true }),
+}
+
+/** 给等待加看门狗：闸门没装时这里是 5s 超时（红），而不是把测试挂死。 */
+async function within<T>(ms: number, run: () => Promise<T>): Promise<T> {
+  return await Promise.race([
+    run(),
+    new Promise<T>((_, reject) => setTimeout(() => reject(new Error(`组合 ${ms}ms 内没有降级`)), ms)),
+  ])
+}
+
+test('第一腿停滞：预算到就判失败，落到下一条腿（而不是把请求挂到客户端自己放弃）', async () => {
+  const stall = stallingStream()
+  const router = new Router('', undefined, undefined, { firstByteBudgetMs: 150 })
+  router.add(supplier('supA', ['a1'], async () => ({ ok: true, stream: stall.stream })) as never)
+  router.add(supplier('supB', ['b1'], async () => ({ ok: true, stream: healthyStream('ok-from-B') })) as never)
+  assert.equal(router.createCombo('c', ['supA,m1', 'supB,m1']).ok, true)
+
+  const { res, body } = captureRes()
+  const t0 = Date.now()
+  await within(5_000, () => router.chatCompletions(req, res))
+  const elapsed = Date.now() - t0
+
+  assert.match(body(), /ok-from-B/, '必须由第二条腿服务（第一腿 200 了但不吐字节）')
+  assert.equal(stall.cancelled(), true, '停滞的上游流必须被 cancel，否则连接原样挂着')
+  // 2s 是组合「喘口气」等待（TRANSIENT_SETTLE_MS）——停滞按 transport 归类，
+  // 该等就得等；这里断言它确实走了「失败→降级」这条路，而不是瞬间成功。
+  assert.ok(elapsed >= 2_000, `应先等喘口气窗口再降级，实际 ${elapsed}ms`)
+  assert.ok(elapsed < 5_000, `降级必须发生在预算+喘口气附近，实际 ${elapsed}ms`)
+})
+
+test('预算是「每条腿」一份：腿内第二个号不再各等一次（否则 60s × 号数）', async () => {
+  const stallA1 = stallingStream()
+  const stallA2 = stallingStream()
+  let a1 = 0
+  let a2 = 0
+  const router = new Router('', undefined, undefined, { firstByteBudgetMs: 150 })
+  router.add(supplier('supA', ['a1', 'a2'], async (uid) => {
+    if (uid === 'a1') { a1 += 1; return { ok: true, stream: stallA1.stream } }
+    a2 += 1
+    return { ok: true, stream: stallA2.stream }
+  }) as never)
+  router.add(supplier('supB', ['b1'], async () => ({ ok: true, stream: healthyStream('ok-from-B') })) as never)
+  assert.equal(router.createCombo('c', ['supA,m1', 'supB,m1']).ok, true)
+
+  const { res, body } = captureRes()
+  const t0 = Date.now()
+  await within(5_000, () => router.chatCompletions(req, res))
+  const elapsed = Date.now() - t0
+
+  assert.match(body(), /ok-from-B/)
+  assert.equal(a1, 1, '第一个号被调了一次')
+  assert.equal(a2, 0, '预算已耗尽：同一个号池里的第二个号不该再各等 150ms（停滞是上游级的）')
+  assert.ok(elapsed < 5_000, `不能按号数翻倍地等，实际 ${elapsed}ms`)
+})
+
+test('wrapper：第一个字节到手后不再计时（长生成不能被砍）', async () => {
+  let ctrlRef: ReadableStreamDefaultController<Uint8Array> | undefined
+  const src = new ReadableStream<Uint8Array>({ start: (c) => { ctrlRef = c } })
+  const reader = withFirstByteDeadline(src, 60).getReader()
+
+  ctrlRef?.enqueue(enc.encode('first'))
+  assert.equal(dec((await reader.read()).value!), 'first')
+  // 停 3 倍预算才吐第二块：过了截止点也必须原样透传
+  await new Promise((r) => setTimeout(r, 200))
+  ctrlRef?.enqueue(enc.encode('second'))
+  assert.equal(dec((await reader.read()).value!), 'second')
+  await reader.cancel()
+})
+
+test('wrapper：源流一个字节都不吐就到期 → 流判失败（上层据此换号/换模型）', async () => {
+  const { stream, cancelled } = stallingStream()
+  const reader = withFirstByteDeadline(stream, 60).getReader()
+  await assert.rejects(() => reader.read(), /no first byte within 60ms/)
+  assert.equal(cancelled(), true, '到期时必须把取消传给源流（否则上游连接原样挂着）')
+})
+
+function dec(v: Uint8Array): string {
+  return new TextDecoder().decode(v)
+}