dsh-router-core 0.4.5 → 0.4.7

package/src/protocol/stream.ts

@@ -0,0 +1,195 @@
+/**
+ * 流的协议转码 —— 把「一种协议的 SSE 字节流」翻译成「另一种协议的 SSE 字节流」。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么拆成 transform + state 两层
+ * ════════════════════════════════════════════════════════════════════
+ * 逐帧翻译需要一个**有状态**的累加器（usage 分散在多帧、工具名要先于参数、
+ * 收尾帧要在流末补），直接写成一个 200 行的 async generator 会把「状态」和
+ * 「翻译」搅在一起。所以：
+ *   - `StreamState`：一次流的有状态累加（纯内存，可单测，无 IO）。
+ *   - `translateStream`：把它接到字节流上（只管分帧/拼帧/生命周期）。
+ *
+ * 同一条流里**同时只有一个转码器**（上游协议固定），但出站协议由客户端决定 ——
+ * 所以是「一个 decode + 一个 encode」，而不是各自独立的两趟。
+ *
+ * ⚠️ **不缓冲、不聚合**：每个事件到立刻吐对应帧。首字节延迟与上游一致，
+ * 不会因为转码多等一个 chunk（Gemini 的工具调用除外：它的参数是一次性整块，
+ * 天然没有增量可言）。
+ */
+import type { ChatEvent, CodecSession, ProtocolId } from './types.ts'
+import { codecOf } from './index.ts'
+import { SseSplitter, framesToBytes } from './sse.ts'
+
+/** 一次流式转码的有状态累加。 */
+export class StreamState {
+  /** 上游协议（解码用）。 */
+  readonly from: ProtocolId
+  /** 客户端协议（编码用）。 */
+  readonly to: ProtocolId
+  /** 上游 usage（跨帧合并，字段级 max —— 见 mergeUsage 的注释）。 */
+  private usage: { promptTokens: number; completionTokens: number; cachedTokens: number } = {
+    promptTokens: 0,
+    completionTokens: 0,
+    cachedTokens: 0,
+  }
+  /** 已经吐过起始帧没有（起始帧只能在流最前发一次）。 */
+  private started = false
+  /** 收尾原因（用于补 endFrames；缺省 stop）。 */
+  private finish: Extract<ChatEvent, { type: 'finish' }> | undefined
+  /** 模型名（回显进 startFrames/endFrames，如 Anthropic 的 message_start）。 */
+  private model = ''
+  /**
+   * 解码侧会话与编码侧会话，各一份。
+   *
+   * **必须每帧复用同一个**：Gemini 的工具名↔index 映射就存在这里；每帧新建
+   * 会让 `tool-args` 找不到 `tool-start` 给的名字（参数被丢），而放模块级会
+   * 跨请求串名。会话在 `StreamState` 构造时建、随流结束丢弃 —— 生命周期与
+   * 「一条流」严格对齐。
+   */
+  private readonly decodeSession: CodecSession | undefined
+  private readonly encodeSession: CodecSession | undefined
+
+  constructor(from: ProtocolId, to: ProtocolId, model = '') {
+    this.from = from
+    this.to = to
+    this.model = model
+    this.decodeSession = codecOf(from).createSession?.()
+    this.encodeSession = codecOf(to).createSession?.()
+  }
+
+  /** 当前累计的用量。 */
+  currentUsage(): { promptTokens: number; completionTokens: number; cachedTokens: number } {
+    return { ...this.usage }
+  }
+
+  /** 把上游一帧原文（`data:` 载荷）翻成出站帧原文列表。 */
+  translateFrame(frame: string, event?: string): string[] {
+    const events = codecOf(this.from).decodeFrame(frame, event, this.decodeSession)
+    const out: string[] = []
+    if (!this.started) {
+      this.started = true
+      out.push(...codecOf(this.to).startFrames({ model: this.model, stream: true }))
+    }
+    for (const ev of events) {
+      if (ev.type === 'usage') this.mergeUsage(ev)
+      if (ev.type === 'finish') this.finish = ev
+      // finish / usage 在出站侧的帧要等流末一起发（见 finish()），
+      // 因为它们的位置在协议里是固定的（Anthropic 的 message_delta 在
+      // message_stop 前、Responses 的 completed 是最后一件）。
+      if (ev.type === 'finish' || ev.type === 'usage') continue
+      out.push(...codecOf(this.to).encodeFrame(ev, this.encodeSession))
+    }
+    return out
+  }
+
+  /**
+   * 上游流结束：补发收尾帧。
+   *
+   * **顺序固定**：finish → usage → endFrames。各协议的收尾帧都要求这个次序
+   * （Anthropic 的 message_delta 必须在 message_stop 前，Responses 的
+   * `response.completed` 是最后一件且自带 usage）。
+   *
+   * `endFrames` 拿得到 finish 与 usage —— 有的协议（Responses）只有收尾帧
+   * 里才有地方放 usage 与「是否被截断」。
+   */
+  finishStream(): string[] {
+    const enc = codecOf(this.to)
+    const ctx = { model: this.model, stream: true, finish: this.finish?.reason ?? 'stop', usage: { ...this.usage } }
+    if (!this.started) {
+      // 上游一个字节都没给：也要给客户端一个**完整形状**的流。只发
+      // startFrames 是不够的 —— Anthropic 客户端等 message_stop、Codex 等
+      // response.completed，缺收尾帧它们会报「流被截断」而不是「上游没答」。
+      this.started = true
+      return [...enc.startFrames(ctx), ...enc.endFrames(ctx, this.encodeSession)]
+    }
+    // finish 帧要拿到**已经累计好的**用量：有的协议（Anthropic）把 stop_reason
+    // 与 output_tokens 绑在同一帧里，而 finish 事件本身不带 usage。所以要派生
+    // 一个带 usage 的会话给它，不能复用构造时那份（那份的 usage 是空的）。
+    const finishSession = this.finishSessionWithUsage()
+    const out: string[] = []
+    out.push(...enc.encodeFrame(this.finish ?? { type: 'finish', reason: 'stop' }, finishSession))
+    out.push(...enc.encodeFrame({ type: 'usage', ...this.usage }, finishSession))
+    out.push(...enc.endFrames(ctx, finishSession))
+    return out
+  }
+
+  /**
+   * 带当前用量派生的编码会话。
+   *
+   * 不能只在 `encodeSession` 存在时才派生：`createSession` 是**可选**的
+   * （只有 Gemini 这类有跨帧映射的协议实现它），Anthropic 没有 —— 按
+   * `encodeSession === undefined` 就返回 undefined 会让 usage 永远送不进去
+   * （2026-10-21 实测：output_tokens 恒为 0）。所以无论如何都造一个，
+   * 有 state 就带上。
+   */
+  private finishSessionWithUsage(): CodecSession {
+    return { ...this.encodeSession, usage: { ...this.usage } }
+  }
+
+  /**
+   * usage 合并：字段级 max。
+   *
+   * 与 `router/usage-tokens.ts` 的 `mergeUsage` 同规则（那里照 9router）：
+   * Claude 把输入用量放 `message_start`、输出放 `message_delta`，两帧都给
+   * `usage` 字段，**覆盖**会让后一帧把前面的输入清零。
+   */
+  private mergeUsage(ev: Extract<ChatEvent, { type: 'usage' }>): void {
+    this.usage.promptTokens = Math.max(this.usage.promptTokens, ev.promptTokens)
+    this.usage.completionTokens = Math.max(this.usage.completionTokens, ev.completionTokens)
+    this.usage.cachedTokens = Math.max(this.usage.cachedTokens, ev.cachedTokens)
+  }
+}
+
+/**
+ * 把上游 SSE 字节流转成客户端协议的 SSE 字节流。
+ *
+ * 生命周期：上游正常读完 / 上游 error / 消费方取消，三条路径都要**释放上游
+ * reader** 并把取消传下去 —— 否则上游 fetch body 永不 cancel，长跑会漏连接
+ * （`router/index.ts` 的 `normalizeSSEStream` 里同一个坑，判据在
+ * `router/disconnect-leak.test.ts`）。
+ */
+export function translateStream(
+  upstream: ReadableStream<Uint8Array>,
+  state: StreamState,
+): ReadableStream<Uint8Array> {
+  const splitter = new SseSplitter()
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+  let released = false
+  const release = (): void => {
+    if (released) return
+    released = true
+    try { reader?.releaseLock() } catch { /* 有待定 read 时会抛，忽略 */ }
+  }
+  return new ReadableStream<Uint8Array>({
+    async start(ctrl) {
+      reader = upstream.getReader()
+      try {
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          const frames = splitter.push(value)
+          for (const f of frames) {
+            if (f.data === '[DONE]' || f.data === '') continue
+            const out = state.translateFrame(f.data, f.event)
+            if (out.length > 0) ctrl.enqueue(framesToBytes(out))
+          }
+        }
+        // 尾帧（上游不发结束空行时 SseSplitter.end() 才吐得出）
+        for (const f of splitter.end()) {
+          if (f.data === '[DONE]' || f.data === '') continue
+          const out = state.translateFrame(f.data, f.event)
+          if (out.length > 0) ctrl.enqueue(framesToBytes(out))
+        }
+        const tail = state.finishStream()
+        if (tail.length > 0) ctrl.enqueue(framesToBytes(tail))
+      } catch {
+        // 上游断流/消费方取消：已吐出的内容留着（HTTP 语义，写出去收不回）
+      } finally {
+        release()
+      }
+      try { ctrl.close() } catch { /* 已取消 */ }
+    },
+    cancel: (reason) => reader?.cancel(reason),
+  })
+}

package/src/protocol/types.ts

@@ -0,0 +1,249 @@
+/**
+ * 协议矩阵的**规范形态**（canonical form）与编解码契约。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么内部只留一种形态
+ * ════════════════════════════════════════════════════════════════════
+ * 四种协议两两互转是 4×3 = 12 条路径，逐条实现必然长出一打互相不一致的
+ * 实现。收敛成「全部先转成同一个规范形态、再从规范形态转出去」之后：
+ *
+ *     外来请求 ──decode──┐                ┌──encode── 外来响应
+ *                        ├─ 规范形态 ────┤
+ *     供应商请求 ◀─encode─┘                └─decode──▶ 供应商响应
+ *
+ * 只需要 N 个协议模块（N=4），而不是 N² 条翻译路径；新增第五种协议只是再加
+ * 一个模块，已有路径一行不改。
+ *
+ * 规范形态选 **OpenAI Chat Completions**（请求体）与**一组扁平事件**（响应流），
+ * 不是随便挑的：供应商契约（`suppliers/contract.ts` 的 `chatOnce`）今天就是
+ * 「吃 Chat Completions 请求体、吐 OpenAI SSE」，选别的形态等于把每个已装
+ * 供应商插件都改一遍。
+ *
+ * 天花板：规范形态只覆盖**能表达的部分**。各家私有的、没有对应概念的东西
+ * （Anthropic 的 `cache_control`、Responses 的 `previous_response_id`、
+ * Gemini 的 `safetySettings`）在跨协议时会被**丢掉**，不是被翻译。每条丢弃
+ * 在对应模块的注释里点名。
+ */
+
+/** 四种协议。`chat` 是规范形态本身，因此它的编解码是恒等变换。 */
+export type ProtocolId = 'chat' | 'anthropic' | 'responses' | 'gemini'
+
+/** 所有协议 id（顺序 = 文档与面板展示顺序）。 */
+export const PROTOCOL_IDS: readonly ProtocolId[] = ['chat', 'anthropic', 'responses', 'gemini']
+
+/** 宽松 JSON 对象（外来请求体一律不可信，逐字段校验）。 */
+export type JsonObject = Record<string, unknown>
+
+/** 编解码时需要知道的上下文。 */
+export interface CodecContext {
+  /**
+   * 请求里声明的模型名（已剥掉本插件的 `alias/` 前缀）。
+   *
+   * 有些协议把模型名放在 URL 路径里（Gemini 的
+   * `/v1beta/models/<model>:generateContent`），有些放在请求体里；模块统一从
+   * 这里取，不各自去猜。
+   */
+  model: string
+  /** 客户端是否要流式。 */
+  stream: boolean
+  /**
+   * 收尾原因（仅 `endFrames` 会读）。
+   *
+   * 有些协议的收尾帧要**同时**带状态与用量（Responses 的 `response.completed`
+   * 里 `status: 'completed' | 'incomplete'` 决定 Codex 是否认为被截断），
+   * 而 `finish` 事件本身在这些协议里没有独立帧可发 —— 于是原因必须通过
+   * 上下文传进 `endFrames`，不能只靠「收到过 finish 事件」这个事实。
+   */
+  finish?: FinishReason
+  /** 累计用量（仅 `endFrames` 会读，同上：Responses 只在收尾帧给 usage）。 */
+  usage?: { promptTokens: number; completionTokens: number; cachedTokens: number }
+}
+
+/**
+ * 规范形态的**流式事件**。
+ *
+ * 刻意做得很小：只要四家能无损落进来的都在这，落不进来的都不在。工具调用用
+ * `tool-start` + `tool-args` 两段表达（各家都是「先给名字、再给参数增量」，
+ * 只有 Gemini 把参数整块给一次 —— 它在 decode 时拆成一段即可）。
+ */
+export type ChatEvent =
+  /** 可见文本增量。 */
+  | { type: 'text'; text: string }
+  /** 推理过程增量（`reasoning_content` / `thinking` / `thought`）。 */
+  | { type: 'reasoning'; text: string }
+  /** 一个工具调用的开始（名字先到，参数随后）。同一 index 只发一次。 */
+  | { type: 'tool-start'; index: number; id?: string; name?: string }
+  /** 工具调用的参数**增量**（JSON 片段，逐段拼接后才是完整参数）。 */
+  | { type: 'tool-args'; index: number; delta: string }
+  /** 收尾原因。一条流最多一个，且必须是最后一个内容事件。 */
+  | { type: 'finish'; reason: FinishReason }
+  /** 用量。多数上游在最后一帧才给。 */
+  | { type: 'usage'; promptTokens: number; completionTokens: number; cachedTokens: number }
+  /** 上游在流内报的错（HTTP 200 + 流内 error 是真实存在的形态）。 */
+  | { type: 'error'; message: string }
+
+/** 收尾原因（规范形态）。 */
+export type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error'
+
+/**
+ * 一条流里的编解码会话状态。
+ *
+ * 刻意做成**不透明的空接口 + 可选**：绝大多数协议（chat / Anthropic /
+ * Responses）逐帧无状态，不需要它；只有 Gemini 这类「用名字而非 index 指代
+ * 工具」的协议需要跨帧记住名字↔index。让它可选，是为了不给无状态协议强加
+ * 一个空对象参数。
+ */
+export interface CodecSession {
+  /** 会话内的临时槽位（各协议自己的形状，核心不解读）。 */
+  readonly state?: unknown
+  /**
+   * 本流已累计的用量。
+   *
+   * 为什么编码器需要它：有的协议把「收尾原因」与「输出用量」绑在**同一帧**
+   * （Anthropic 的 `message_delta`），而 finish 事件本身不带 usage。不给这个
+   * 槽位，收尾帧只能写 `output_tokens: 0` 或者再多发一帧 —— 后者会让客户端
+   * 取到第一个（占位）值，把用量读成 0（2026-10-21 在 3080 实测到）。
+   */
+  readonly usage?: { promptTokens: number; completionTokens: number; cachedTokens: number }
+}
+
+/**
+ * 一个协议的编解码器。
+ *
+ * 四个方法分成两组，两组都必须实现 —— 少了任何一组就只能单向，而「双向互转」
+ * 正是这个模块存在的理由：
+ *   - `toChat*`：**入站**用。客户端说这个协议，我们得听懂它、并用它回答。
+ *   - `fromChat*`：**出站**用。供应商说这个协议，我们得用它的语言请求、并把
+ *     它的回答翻回规范形态。
+ */
+export interface ProtocolCodec {
+  readonly id: ProtocolId
+
+  /**
+   * 一条流的编解码会话。
+   *
+   * 部分协议是**有状态**的：Gemini 的 `functionCall` 靠工具名认，而规范形态
+   * 靠 index，跨帧必须有映射；映射若放模块级就会串请求（并发两条流各自的
+   * `ls` 抢同一个 index，或上一条流的残留映射漏到下一条）。
+   *
+   * 所以状态由调用方在**请求边界**建一次、在整条流里传给每一帧：
+   *   - `translateStream` / `StreamState` 在一次转码里建一个；
+   *   - 单帧转换（测试、非流式一次性）可以不传，此时每帧各建一份 —— 结果
+   *     等价于无状态，代价只有一次 Map 分配。
+   */
+  createSession?(): CodecSession
+
+  /** 外来请求体 → 规范请求体。`chat` 是恒等。 */
+  toChat(body: JsonObject, ctx: CodecContext): JsonObject
+
+  /** 规范请求体 → 外来请求体。`chat` 是恒等。 */
+  fromChat(body: JsonObject, ctx: CodecContext): JsonObject
+
+  /**
+   * 外来响应流的**单帧**解码：一帧 SSE 载荷（已剥掉 `data:` 前缀）→ 0..n 个
+   * 规范事件。`[DONE]` 与无法识别的帧返回空数组，**不抛**：一条坏帧不该让
+   * 整轮响应作废（上游发半截 JSON 是常态，见 `llm/adapter.ts` 的同类处理）。
+   *
+   * @param frame SSE 的 `data:` 载荷原文；`[DONE]` 由调用方过滤，不会传进来。
+   * @param event 该帧的 `event:` 名（Anthropic 用它区分事件类型；其余协议为空）。
+   */
+  decodeFrame(frame: string, event?: string, session?: CodecSession): ChatEvent[]
+
+  /**
+   * 规范事件 → 0..n 个外来 SSE 帧。
+   *
+   * 返回的是**完整帧**（含 `event:`/`data:` 行与结尾空行），调用方只管拼字节。
+   * 做成整帧而不是载荷，是因为 Anthropic 这类协议每个事件都要带 `event:` 行，
+   * 让编码器自己拼比让调用方猜事件名干净。
+   */
+  encodeFrame(event: ChatEvent, session?: CodecSession): string[]
+
+  /**
+   * 非流式响应体的解码：整个 JSON body → 规范事件列表。
+   *
+   * 与 `decodeFrame` 同构（同样返回事件列表），区别只在输入是**一个完整的
+   * 响应对象**而不是一帧增量。两种都必须实现：客户端可能发 `stream:false`，
+   * 供应商也可能只给 JSON（有些上游对短请求直接回非流式）。
+   */
+  decodeJson(body: JsonObject): ChatEvent[]
+
+  /**
+   * 规范事件 → 非流式响应体。
+   *
+   * 与 `encodeFrame` 同构：把攒起来的事件折成一个完整响应对象。
+   * `events` 里最多一个 `finish`、一个 `usage`，其余是内容。
+   */
+  encodeJson(events: ChatEvent[], ctx: CodecContext): JsonObject
+
+  /**
+   * 流开始时的一次性帧（Anthropic 的 `message_start`、Responses 的
+   * `response.created`）。恒等协议返回空数组。
+   */
+  startFrames(ctx: CodecContext): string[]
+
+  /**
+   * 流结束时的一次性帧（`message_stop`、`response.completed`、`[DONE]`）。
+   * 与 `startFrames` 对称；`finish` 事件本身走 `encodeFrame`。
+   *
+   * 带上 `session` 是因为有的协议**必须**在流末才发得出东西：Gemini 的
+   * `functionCall` 是「名字+完整参数」一个 part，而上游逐帧发参数增量，
+   * 只能攒到流末（见 gemini.ts 的 endFrames）。
+   */
+  endFrames(ctx: CodecContext, session?: CodecSession): string[]
+}
+
+/** 是否为已知协议 id。 */
+export function isProtocolId(v: unknown): v is ProtocolId {
+  return typeof v === 'string' && (PROTOCOL_IDS as readonly string[]).includes(v)
+}
+
+/* ------------------------------------------------------------------ */
+/* 小工具：外来 JSON 一律不可信，取字段全部走这里                       */
+/* ------------------------------------------------------------------ */
+
+/** 取对象字段（不是对象则 undefined）。 */
+export function obj(v: unknown): JsonObject | undefined {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as JsonObject) : undefined
+}
+
+/** 取数组字段（不是数组则 undefined）。 */
+export function arr(v: unknown): unknown[] | undefined {
+  return Array.isArray(v) ? v : undefined
+}
+
+/** 取非空字符串字段。 */
+export function str(v: unknown): string | undefined {
+  return typeof v === 'string' && v !== '' ? v : undefined
+}
+
+/** 取有限数字字段。 */
+export function num(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined
+}
+
+/** 取布尔字段。 */
+export function bool(v: unknown): boolean | undefined {
+  return typeof v === 'boolean' ? v : undefined
+}
+
+/** 把 `finish` 原因在各协议间对齐（各家词汇不同，这里是唯一的对照表）。 */
+export function finishOf(v: unknown): FinishReason {
+  switch (v) {
+    case 'length':
+    case 'max_tokens':
+    case 'MAX_TOKENS':
+      return 'length'
+    case 'tool_calls':
+    case 'tool_use':
+    case 'function_call':
+      return 'tool-calls'
+    case 'content_filter':
+    case 'SAFETY':
+    case 'safety':
+      return 'content-filter'
+    case 'error':
+      return 'error'
+    default:
+      return 'stop'
+  }
+}

package/src/protocol/wire-e2e.test.ts

@@ -0,0 +1,208 @@
+/**
+ * 四协议出口的**端到端**测试 —— 从 `outboundSink` 到真实字节。
+ *
+ * `protocol.test.ts` 守的是编解码器两两往返（纯函数、无 IO）；这里守的是接线：
+ * Router 只会写 OpenAI 形态，客户端说的是别的协议，中间那层中继必须把
+ * **状态行、content-type、内容、收尾**四件事同时搬对。
+ *
+ * 每一条都对应一个真实会坏的点：
+ *   - 流式：客户端逐帧解析，缺 `message_start` / `message_stop` 就是「流格式错误」
+ *   - 非流式：方向反了会返回 200 + 空内容（静默错，最难发现）
+ *   - 工具调用：名字只在上游第一帧给，后续增量只带参数 —— 名字丢了等于工具没了
+ *   - 空流：上游刚连上就断，要给协议合法的空流而不是裸断连接
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { outboundSink } from './entry.ts'
+import type { ProtocolId } from './types.ts'
+
+const enc = new TextEncoder()
+
+/** 假的 ServerResponse：收集状态行/头/body，够 sink 用。 */
+function captureRes(): {
+  res: Record<string, unknown>
+  status: () => number
+  headers: () => Record<string, string>
+  body: () => string
+} {
+  const chunks: string[] = []
+  let status = 0
+  let headers: Record<string, string> = {}
+  const text = (b: unknown): string =>
+    typeof b === 'string' ? b : b instanceof Uint8Array ? new TextDecoder().decode(b) : String(b)
+  const self: Record<string, unknown> = {
+    writeHead(code: number, h?: Record<string, string>) {
+      status = code
+      headers = h ?? {}
+      return self
+    },
+    flushHeaders(): void {},
+    write(b: unknown): boolean {
+      chunks.push(text(b))
+      return true
+    },
+    end(b?: unknown): void {
+      if (b !== undefined) chunks.push(text(b))
+    },
+    on() { return self },
+    once() { return self },
+    removeListener(): void {},
+    destroy(): void {},
+  }
+  return { res: self, status: () => status, headers: () => headers, body: () => chunks.join('') }
+}
+
+/** 按 SSE 规则切帧（`event:` + `data:`）。 */
+function sseFrames(body: string): Array<{ event: string; data: string }> {
+  return body
+    .split(/\r?\n\r?\n/)
+    .filter((raw) => raw.trim() !== '')
+    .map((raw) => {
+      let event = ''
+      const dataLines: string[] = []
+      for (const line of raw.split(/\r?\n/)) {
+        if (line.startsWith('event:')) event = line.slice(6).trim()
+        else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim())
+      }
+      return { event, data: dataLines.join('\n') }
+    })
+}
+
+/** 喂一段 OpenAI SSE 给 sink，返回客户端看到的 body。 */
+function runStream(protocol: ProtocolId, upstream: string): string {
+  const cap = captureRes()
+  const sink = outboundSink(protocol, 'test-model', cap.res as never)
+  sink.head?.(200, { 'content-type': 'text/event-stream' })
+  // 故意切成两段：验证跨 chunk 的分帧缓冲
+  const bytes = enc.encode(upstream)
+  const cut = Math.floor(bytes.length / 2)
+  sink.write(bytes.slice(0, cut))
+  sink.write(bytes.slice(cut))
+  sink.end()
+  return cap.body()
+}
+
+const UPSTREAM_TEXT =
+  'data: {"choices":[{"delta":{"content":"你好"}}]}\n\n' +
+  'data: {"choices":[{"delta":{"content":"世界"}}]}\n\n' +
+  'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\n' +
+  'data: [DONE]\n\n'
+
+test('端到端 · Anthropic：流式帧序列完整（message_start -> text_delta -> stop_reason -> message_stop）', () => {
+  const frames = sseFrames(runStream('anthropic', UPSTREAM_TEXT))
+  const names = frames.map((f) => f.event)
+
+  assert.equal(names[0], 'message_start', '第一帧必须是 message_start')
+  assert.equal(names.at(-1), 'message_stop', '最后一帧必须是 message_stop')
+  assert.equal(names.filter((n) => n === 'message_stop').length, 1, 'message_stop 只能有一个')
+
+  const text = frames
+    .map((f) => { try { return JSON.parse(f.data) as Record<string, unknown> } catch { return undefined } })
+    .filter((o): o is Record<string, unknown> => o !== undefined)
+    .map((o) => {
+      const d = o.delta as { type?: string; text?: string } | undefined
+      return d?.type === 'text_delta' ? (d.text ?? '') : ''
+    })
+    .join('')
+  assert.equal(text, '你好世界', '文本增量被吞了或者顺序乱了')
+
+  const stop = frames
+    .map((f) => { try { return JSON.parse(f.data) as { delta?: { stop_reason?: string } } } catch { return {} } })
+    .find((o) => o.delta?.stop_reason !== undefined)
+  assert.equal(stop?.delta?.stop_reason, 'end_turn', 'stop_reason 没落到 text 块上')
+})
+
+test('端到端 · Anthropic：工具调用跨帧保留名字（Claude Code 靠它调工具）', () => {
+  // 上游：名字在第一帧，参数分两段增量
+  const upstream =
+    'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"c1","type":"function","function":{"name":"Read","arguments":""}}]}}]}\n\n' +
+    'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\\"file_path\\":"}}]}}]}\n\n' +
+    'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\"/tmp/a\\"}"}}]}}]}\n\n' +
+    'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}\n\n' +
+    'data: [DONE]\n\n'
+  const frames = sseFrames(runStream('anthropic', upstream))
+  const objs = frames
+    .map((f) => { try { return JSON.parse(f.data) as Record<string, unknown> } catch { return undefined } })
+    .filter((o): o is Record<string, unknown> => o !== undefined)
+
+  const start = objs.find((o) => o.type === 'content_block_start')
+  assert.ok(start !== undefined, '缺 content_block_start（工具起点）')
+  const block = start.content_block as { type?: string; name?: string; id?: string }
+  assert.equal(block.type, 'tool_use')
+  assert.equal(block.name, 'Read', '工具名丢了 —— 客户端会收到一个没名字的工具')
+  assert.equal(block.id, 'c1')
+
+  const partial = objs
+    .map((o) => o.delta as { type?: string; partial_json?: string } | undefined)
+    .filter((d): d is { type: 'input_json_delta'; partial_json: string } => d?.type === 'input_json_delta')
+    .map((d) => d.partial_json)
+    .join('')
+  assert.deepEqual(JSON.parse(partial), { file_path: '/tmp/a' })
+
+  const stop = objs.find((o) => (o.delta as { stop_reason?: string } | undefined)?.stop_reason !== undefined)
+  assert.equal((stop?.delta as { stop_reason?: string }).stop_reason, 'tool_use', '工具轮的 stop_reason 必须是 tool_use')
+})
+
+test('端到端 · Responses：流有 response.created 与带 status/usage 的 response.completed', () => {
+  const upstream =
+    'data: {"choices":[{"delta":{"content":"hi"}}],"usage":{"prompt_tokens":9,"completion_tokens":4}}\n\n' +
+    'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\n' +
+    'data: [DONE]\n\n'
+  const frames = sseFrames(runStream('responses', upstream))
+  const names = frames.map((f) => f.event)
+  assert.equal(names[0], 'response.created', '缺 response.created')
+  assert.equal(names.at(-1), 'response.completed', '缺 response.completed（Codex 靠它判结束）')
+
+  const done = JSON.parse(frames.at(-1)!.data) as { response: { status?: string; usage?: Record<string, number> } }
+  assert.equal(done.response.status, 'completed')
+  assert.equal(done.response.usage?.input_tokens, 9, '输入用量丢了')
+  assert.equal(done.response.usage?.output_tokens, 4, '输出用量丢了')
+})
+
+test('端到端 · Gemini：流是裸 data: 帧，finishReason 与 usageMetadata 都在', () => {
+  const upstream =
+    'data: {"choices":[{"delta":{"content":"hi"}}],"usage":{"prompt_tokens":6,"completion_tokens":2}}\n\n' +
+    'data: {"choices":[{"delta":{},"finish_reason":"length"}]}\n\n' +
+    'data: [DONE]\n\n'
+  const frames = sseFrames(runStream('gemini', upstream))
+  assert.ok(frames.every((f) => f.event === ''), 'Gemini 不该有 event: 行')
+  const body = frames.map((f) => f.data).join('\n')
+  assert.ok(body.includes('"text":"hi"'), '文本丢了')
+  assert.ok(body.includes('"finishReason":"MAX_TOKENS"'), 'length -> MAX_TOKENS 没翻对')
+  assert.ok(body.includes('"promptTokenCount":6'), '用量丢了')
+})
+
+test('端到端 · chat 客户端拿到原生 OpenAI SSE（含 [DONE]）', () => {
+  const body = runStream('chat', UPSTREAM_TEXT)
+  assert.ok(body.includes('"content":"你好"'))
+  assert.ok(body.includes('data: [DONE]'), '缺 [DONE] 终帧')
+})
+
+test('端到端 · 空流：每种协议都给出形状合法的收尾，而不是裸断', () => {
+  for (const protocol of ['anthropic', 'responses', 'gemini', 'chat'] as ProtocolId[]) {
+    const cap = captureRes()
+    const sink = outboundSink(protocol, 'test-model', cap.res as never)
+    sink.head?.(200, { 'content-type': 'text/event-stream' })
+    sink.end()
+    const body = cap.body()
+    assert.equal(cap.status(), 200, `${protocol}: 状态行该是 200`)
+    assert.notEqual(body, '', `${protocol}: 空流不能一个字节都不给（客户端会当成网络故障重试）`)
+    if (protocol === 'anthropic') {
+      assert.ok(body.includes('message_start') && body.includes('message_stop'), 'anthropic 空流形状不完整')
+    }
+    if (protocol === 'responses') {
+      assert.ok(body.includes('response.completed'), 'responses 空流缺收尾')
+    }
+  }
+})
+
+test('端到端 · 上游 503：错误形状按客户端协议给（不是 OpenAI 的 error）', () => {
+  const cap = captureRes()
+  const sink = outboundSink('anthropic', 'test-model', cap.res as never)
+  sink.head?.(503, { 'content-type': 'application/json' })
+  sink.write(enc.encode(JSON.stringify({ error: { message: 'all models unavailable', type: 'api_error' } })))
+  sink.end()
+  const body = cap.body()
+  assert.equal(cap.status(), 503, '状态码要透传')
+  assert.ok(body.includes('"type":"error"'), `Anthropic 客户端要的是 {type:'error'} 形状，实际：${body}`)
+})