niceeval 0.1.1 → 0.1.2

package/src/agents/ui-message-stream.test.ts

@@ -0,0 +1,249 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { AgentContext } from "../types.ts";
+import { uiMessageStreamAgent, type UIMessageLike, type UIMessagePartLike } from "./ui-message-stream.ts";
+import { createAgentSession } from "../context/session.ts";
+
+// ─────────────────── mock `ai`:协议语义的最小 reducer(readUIMessageStream 同款行为) ───────────────────
+// 只实现测试用到的 chunk 类型;seed(resume 的 message)上的 parts 原样保留、按 toolCallId 更新。
+
+vi.mock("ai", () => ({
+  readUIMessageStream: ({ message, stream }: { message?: UIMessageLike; stream: ReadableStream<Record<string, unknown>> }) =>
+    (async function* () {
+      const msg: UIMessageLike = message
+        ? { ...message, parts: message.parts.map((p) => ({ ...p })) }
+        : { id: "m1", role: "assistant", parts: [] };
+      const toolPart = (toolCallId: string) =>
+        msg.parts.find((p) => (p as UIMessagePartLike).toolCallId === toolCallId) as UIMessagePartLike | undefined;
+      const reader = stream.getReader();
+      for (;;) {
+        const { value: c, done } = await reader.read();
+        if (done) break;
+        const chunk = c as Record<string, unknown>;
+        switch (chunk.type) {
+          case "text-delta": {
+            const last = msg.parts.at(-1);
+            if (last?.type === "text") last.text = (last.text ?? "") + (chunk.delta as string);
+            else msg.parts.push({ type: "text", text: chunk.delta as string });
+            break;
+          }
+          case "tool-input-available":
+            msg.parts.push({
+              type: `tool-${chunk.toolName as string}`,
+              state: "input-available",
+              toolCallId: chunk.toolCallId as string,
+              input: chunk.input,
+            });
+            break;
+          case "tool-output-available": {
+            const p = toolPart(chunk.toolCallId as string);
+            if (p) {
+              p.state = "output-available";
+              p.output = chunk.output;
+            }
+            break;
+          }
+          case "tool-approval-request": {
+            const p = toolPart(chunk.toolCallId as string);
+            if (p) {
+              p.state = "approval-requested";
+              p.approval = { id: chunk.approvalId as string };
+            }
+            break;
+          }
+          default:
+            break; // start / finish / error 等对归约无影响
+        }
+      }
+      yield msg;
+    })(),
+}));
+
+// ─────────────────── fetch mock:每次调用吐一段脚本化的 SSE ───────────────────
+
+function sse(chunks: Array<Record<string, unknown>>): Response {
+  const payload = [...chunks.map((c) => `data: ${JSON.stringify(c)}\n\n`), "data: [DONE]\n\n"].join("");
+  return new Response(payload, { status: 200, headers: { "content-type": "text/event-stream" } });
+}
+
+const fetchMock = vi.fn<typeof fetch>();
+vi.stubGlobal("fetch", fetchMock);
+
+function ctx(overrides: Partial<{ model: string }> = {}): AgentContext {
+  return {
+    signal: new AbortController().signal,
+    model: overrides.model,
+    flags: {},
+    sandbox: undefined as never,
+    // 同一个 ctx 重复用 = 同一条会话线(续接,同一个 ctx.session);新造 = 新线。
+    session: createAgentSession(),
+    log: () => {},
+  } as AgentContext;
+}
+
+function sentBody(call: number): { messages: UIMessageLike[] } & Record<string, unknown> {
+  return JSON.parse(fetchMock.mock.calls[call]![1]!.body as string) as { messages: UIMessageLike[] };
+}
+
+afterEach(() => {
+  fetchMock.mockReset();
+});
+
+describe("uiMessageStreamAgent", () => {
+  it("纯文本轮:message 事件 + completed;第二轮重放全量历史(客户端带历史的协议语义)", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat", body: (c) => ({ model: c.model }) });
+    fetchMock.mockResolvedValueOnce(sse([{ type: "text-delta", delta: "你好" }, { type: "text-delta", delta: "!" }]));
+
+    const c = ctx({ model: "m-1" });
+    const turn = await agent.send({ text: "hi" }, c);
+    expect(turn.status).toBe("completed");
+    expect(turn.events).toEqual([{ type: "message", role: "assistant", text: "你好!" }]);
+    expect(c.session.id).toBeTruthy();
+    expect(sentBody(0).model).toBe("m-1");
+    expect(sentBody(0).messages).toHaveLength(1);
+
+    fetchMock.mockResolvedValueOnce(sse([{ type: "text-delta", delta: "again" }]));
+    const turn2 = await agent.send({ text: "再说一次" }, c);
+    // user, assistant, user —— 全量历史重放
+    expect(sentBody(1).messages.map((m) => m.role)).toEqual(["user", "assistant", "user"]);
+    // 回归:mock 的响应消息 id 每轮都是 "m1"(有的应用真的会这样)。全新轮的文本必须完整
+    // 报出,不能被上一轮的已报进度按 id 误当成"已报过的前缀"截掉。
+    expect(turn2.events).toEqual([{ type: "message", role: "assistant", text: "again" }]);
+  });
+
+  it("工具 part 到 output-available → action.called + action.result", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    fetchMock.mockResolvedValueOnce(
+      sse([
+        { type: "tool-input-available", toolCallId: "c1", toolName: "get_weather", input: { city: "北京" } },
+        { type: "tool-output-available", toolCallId: "c1", output: { temp: 21 } },
+        { type: "text-delta", delta: "21 度" },
+      ]),
+    );
+    const turn = await agent.send({ text: "天气" }, ctx());
+    expect(turn.events).toEqual([
+      { type: "action.called", callId: "c1", name: "get_weather", input: { city: "北京" } },
+      { type: "action.result", callId: "c1", output: { temp: 21 }, status: "completed" },
+      { type: "message", role: "assistant", text: "21 度" },
+    ]);
+  });
+
+  it("HITL:approval-requested → waiting;approve 续跑改写 part 重放,拿到执行结果不重报旧事件", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    fetchMock.mockResolvedValueOnce(
+      sse([
+        { type: "tool-input-available", toolCallId: "c1", toolName: "calculate", input: { expr: "1+1" } },
+        { type: "tool-approval-request", toolCallId: "c1", approvalId: "ap1" },
+      ]),
+    );
+    const c = ctx();
+    const turn1 = await agent.send({ text: "算 1+1" }, c);
+    expect(turn1.status).toBe("waiting");
+    expect(turn1.events).toEqual([
+      {
+        type: "input.requested",
+        request: { id: "ap1", action: "calculate", input: { expr: "1+1" }, options: [{ id: "approve" }, { id: "deny" }] },
+      },
+    ]);
+
+    fetchMock.mockResolvedValueOnce(
+      sse([{ type: "tool-output-available", toolCallId: "c1", output: 2 }, { type: "text-delta", delta: "= 2" }]),
+    );
+    const turn2 = await agent.send({ text: "approve" }, c);
+    expect(turn2.status).toBe("completed");
+    expect(turn2.events).toEqual([
+      { type: "action.called", callId: "c1", name: "calculate", input: { expr: "1+1" } },
+      { type: "action.result", callId: "c1", output: 2, status: "completed" },
+      { type: "message", role: "assistant", text: "= 2" },
+    ]);
+    // 续跑请求:不追加新 user 消息,pending part 已改写成 approval-responded approved:true
+    const resumeBody = sentBody(1);
+    expect(resumeBody.messages.map((m) => m.role)).toEqual(["user", "assistant"]);
+    const mutated = resumeBody.messages[1]!.parts.find((p) => p.toolCallId === "c1")!;
+    expect(mutated.state).toBe("approval-responded");
+    expect(mutated.approval).toMatchObject({ id: "ap1", approved: true });
+    expect(mutated.approval!.reason).toBeUndefined();
+  });
+
+  it("HITL:deny 合成 rejected 的工具对,并带上劝退重试的 reason", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat", denyReason: "别重试" });
+    fetchMock.mockResolvedValueOnce(
+      sse([
+        { type: "tool-input-available", toolCallId: "c1", toolName: "calculate", input: { expr: "1+1" } },
+        { type: "tool-approval-request", toolCallId: "c1", approvalId: "ap1" },
+      ]),
+    );
+    const c = ctx();
+    await agent.send({ text: "算" }, c);
+
+    fetchMock.mockResolvedValueOnce(sse([{ type: "text-delta", delta: "好的,不算了" }]));
+    const turn2 = await agent.send({ text: "deny" }, c);
+    expect(turn2.status).toBe("completed");
+    expect(turn2.events).toEqual([
+      { type: "action.called", callId: "c1", name: "calculate", input: { expr: "1+1" } },
+      { type: "action.result", callId: "c1", status: "rejected" },
+      { type: "message", role: "assistant", text: "好的,不算了" },
+    ]);
+    const mutated = sentBody(1).messages[1]!.parts.find((p) => p.toolCallId === "c1")!;
+    expect(mutated.approval).toMatchObject({ approved: false, reason: "别重试" });
+  });
+
+  it("HITL:优先按 requestId 从 input.responses 读裁决,而不是猜 input.text——两者矛盾时以 responses 为准", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    fetchMock.mockResolvedValueOnce(
+      sse([
+        { type: "tool-input-available", toolCallId: "c1", toolName: "calculate", input: { expr: "1+1" } },
+        { type: "tool-approval-request", toolCallId: "c1", approvalId: "ap1" },
+      ]),
+    );
+    const c = ctx();
+    await agent.send({ text: "算 1+1" }, c);
+
+    fetchMock.mockResolvedValueOnce(sse([{ type: "text-delta", delta: "好的,不算了" }]));
+    // input.text 读起来像批准,但 responses 结构化裁决说 deny——必须以 responses 为准。
+    const turn2 = await agent.send({ text: "approve", responses: [{ requestId: "ap1", optionId: "deny" }] }, c);
+    expect(turn2.events).toEqual([
+      { type: "action.called", callId: "c1", name: "calculate", input: { expr: "1+1" } },
+      { type: "action.result", callId: "c1", status: "rejected" },
+      { type: "message", role: "assistant", text: "好的,不算了" },
+    ]);
+    const mutated = sentBody(1).messages[1]!.parts.find((p) => p.toolCallId === "c1")!;
+    expect(mutated.approval).toMatchObject({ approved: false });
+  });
+
+  it("HITL:没有 input.responses 时(旧 adapter 用法)退回从 input.text 猜裁决", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    fetchMock.mockResolvedValueOnce(
+      sse([
+        { type: "tool-input-available", toolCallId: "c1", toolName: "calculate", input: { expr: "1+1" } },
+        { type: "tool-approval-request", toolCallId: "c1", approvalId: "ap1" },
+      ]),
+    );
+    const c = ctx();
+    await agent.send({ text: "算 1+1" }, c);
+
+    fetchMock.mockResolvedValueOnce(
+      sse([{ type: "tool-output-available", toolCallId: "c1", output: 2 }, { type: "text-delta", delta: "= 2" }]),
+    );
+    const turn2 = await agent.send({ text: "approve" }, c); // 没有 responses 字段
+    expect(turn2.events).toEqual([
+      { type: "action.called", callId: "c1", name: "calculate", input: { expr: "1+1" } },
+      { type: "action.result", callId: "c1", output: 2, status: "completed" },
+      { type: "message", role: "assistant", text: "= 2" },
+    ]);
+  });
+
+  it("error 帧 → failed + error 事件", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    fetchMock.mockResolvedValueOnce(sse([{ type: "text-delta", delta: "部分" }, { type: "error", errorText: "boom" }]));
+    const turn = await agent.send({ text: "hi" }, ctx());
+    expect(turn.status).toBe("failed");
+    expect(turn.events.at(-1)).toEqual({ type: "error", message: "boom" });
+  });
+
+  it("非 2xx 响应:报错里带状态码和下一步提示", async () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    fetchMock.mockResolvedValueOnce(new Response("nope", { status: 500 }));
+    await expect(agent.send({ text: "hi" }, ctx())).rejects.toThrow(/500/);
+  });
+});

package/src/agents/ui-message-stream.ts

@@ -0,0 +1,372 @@
+// uiMessageStreamAgent():AI SDK UI Message Stream Protocol 的无侵入 HTTP adapter 工厂。
+//
+// 协议:https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol —— `useChat` 后端的标准 SSE
+// (`data: {UIMessageChunk}\n\n`,以 `data: [DONE]\n\n` 收尾)。这是「对着一个已部署的
+// AI SDK 应用的 HTTP 接口无侵入接入」:adapter 只 fetch,不 import 被测应用的任何代码。
+//
+//   · 会话:协议是服务端零状态、「客户端带全量历史」——工厂用 ctx.session.history() 存整份
+//     UIMessage[],每轮原样重放;ctx.session.id 未记录时开新 chat id 并 capture 回写。
+//   · 事件流:从归约后的 assistant 消息 parts 直构(text → message,tool part 的
+//     output-available / output-error / 审批拒绝 → action.called + action.result),
+//     不要求应用接 OTel;跨 resume 轮次按 callId / 已报文本长度去重。
+//   · HITL:v7 tool approval(`needsApproval` 工具)——part 停在 `approval-requested` 时
+//     整轮 `waiting` + `input.requested`;下一轮输入(approve / yes / 同意 / 批准 开头 =
+//     批准,其余拒绝)翻译成 `approval-responded` 原地改写该 part、原样重发 messages 触发
+//     服务端续跑 —— 和真实前端 `addToolApprovalResponse()` + `sendMessage()` 的协议行为
+//     完全一致,没有单独的 approve 端点。拒绝的调用协议里不会有任何 tool-output 帧
+//     (从没真正执行),由工厂合成 `status: "rejected"` 的 action.result。
+//   · chunk 归约用 `ai` 包官方导出的框架无关 reducer `readUIMessageStream`(`useChat`
+//     内部同款),保证重放回服务端的 UIMessage 形状协议正确 —— `ai` 是可选 peer 依赖,
+//     只在用到本工厂时需要安装。
+//
+// tracing / spanMapper 原样透传:应用有 OTel 时接上拿瀑布图(span 只进瀑布图,不喂断言),
+// 事件流始终从协议帧直构。
+
+import { randomUUID } from "node:crypto";
+
+import { defineAgent } from "../define.ts";
+import type { Agent, AgentContext, AgentTracing, InputResponse, JsonValue, SpanMapper, StreamEvent, TurnInput } from "../types.ts";
+
+// ───────────────────────── 协议的结构化类型(structural,不依赖 ai 包的类型) ─────────────────────────
+
+/** UIMessage 的最小结构面:只声明工厂真正要读的字段,其余原样透传。 */
+export interface UIMessageLike {
+  id: string;
+  role: string;
+  parts: UIMessagePartLike[];
+  [key: string]: unknown;
+}
+
+export interface UIMessagePartLike {
+  type: string;
+  state?: string;
+  text?: string;
+  toolCallId?: string;
+  toolName?: string;
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+  approval?: { id: string; approved?: boolean; reason?: string };
+  [key: string]: unknown;
+}
+
+interface UIMessageChunkLike {
+  type: string;
+  errorText?: string;
+  [key: string]: unknown;
+}
+
+type ReadUIMessageStream = (options: {
+  message?: UIMessageLike;
+  stream: ReadableStream<UIMessageChunkLike>;
+}) => AsyncIterable<UIMessageLike>;
+
+// ai 是可选 peer 依赖:动态 import,缺了就把「装什么」直接说清楚。
+// 说明符经变量传入,避免 TS 对字面量模块名做安装检查(niceeval 自身不依赖 ai)。
+let aiModule: Promise<{ readUIMessageStream: ReadUIMessageStream }> | undefined;
+function loadAi(): Promise<{ readUIMessageStream: ReadUIMessageStream }> {
+  if (!aiModule) {
+    const specifier = "ai";
+    aiModule = (import(specifier) as Promise<{ readUIMessageStream: ReadUIMessageStream }>).catch(() => {
+      aiModule = undefined;
+      throw new Error(
+        "uiMessageStreamAgent 需要 `ai` 包(AI SDK v5+,协议 reducer readUIMessageStream 来自它)。在你的 eval 项目里安装:npm install -D ai",
+      );
+    });
+  }
+  return aiModule;
+}
+
+// ───────────────────────── SSE 解析 ─────────────────────────
+
+async function* parseSseChunks(body: ReadableStream<Uint8Array>): AsyncGenerator<UIMessageChunkLike> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const sepIndex = buffer.indexOf("\n\n");
+    if (sepIndex !== -1) {
+      const rawEvent = buffer.slice(0, sepIndex);
+      buffer = buffer.slice(sepIndex + 2);
+      const line = rawEvent.split("\n").find((l) => l.startsWith("data: "));
+      if (line) {
+        const payload = line.slice("data: ".length);
+        if (payload !== "[DONE]") yield JSON.parse(payload) as UIMessageChunkLike;
+      }
+      continue;
+    }
+    const { value, done } = await reader.read();
+    if (done) return;
+    buffer += decoder.decode(value, { stream: true });
+  }
+}
+
+/** 把 SSE 包成 readUIMessageStream 要的 ReadableStream,顺带旁路探测(错误帧等)。 */
+function toChunkStream(
+  body: ReadableStream<Uint8Array>,
+  onChunk: (c: UIMessageChunkLike) => void,
+): ReadableStream<UIMessageChunkLike> {
+  const gen = parseSseChunks(body);
+  return new ReadableStream<UIMessageChunkLike>({
+    async pull(controller) {
+      const { value, done } = await gen.next();
+      if (done) {
+        controller.close();
+        return;
+      }
+      onChunk(value);
+      controller.enqueue(value);
+    },
+  });
+}
+
+// ───────────────────────── parts → 事件 ─────────────────────────
+
+function isToolPart(part: UIMessagePartLike): boolean {
+  return part.type === "dynamic-tool" || part.type.startsWith("tool-");
+}
+
+function toolNameOf(part: UIMessagePartLike): string {
+  if (part.type === "dynamic-tool") return part.toolName ?? "dynamic-tool";
+  return part.type.slice("tool-".length);
+}
+
+function isApprovalRequested(part: UIMessagePartLike): boolean {
+  return isToolPart(part) && part.state === "approval-requested";
+}
+
+/** 和 aiSdkAgent 同一词法:approve / yes / 同意 / 批准 开头 = 批准,其余一律拒绝。 */
+function isApproved(text: string): boolean {
+  return /^(approve|yes|同意|批准)/i.test(text.trim());
+}
+
+/**
+ * 优先按 requestId 从 input.responses 里取结构化裁决(`optionId === "approve"`);
+ * 拿不到 responses(旧 adapter / 手写 send 未接结构化回答)才退回从 input.text 猜的路径,
+ * 防御式保留,不删旧分支。
+ */
+function approvedFromResponse(
+  responses: readonly InputResponse[] | undefined,
+  requestId: string | undefined,
+  fallbackText: string,
+): boolean {
+  const matched = responses?.find((r) => r.requestId === requestId);
+  if (matched?.optionId !== undefined) return matched.optionId === "approve";
+  if (matched?.text !== undefined) return isApproved(matched.text);
+  return isApproved(fallbackText);
+}
+
+/** 已报告的进度:resume 续跑的是同一条 assistant 消息,跨轮去重靠它。 */
+interface ReportedState {
+  calls: Set<string>;
+  textLen: number;
+}
+
+/**
+ * 从归约后的最终消息派生本轮事件。工具事件按 part 顺序;文本合并成一条 message 事件
+ * (resume 轮只报新增的后缀)。停在 approval-requested 的调用不报 called —— 它还没执行,
+ * 裁决后那一轮才落成 completed(批准)或 rejected(拒绝)。
+ */
+function deriveTurnEvents(message: UIMessageLike, reported: ReportedState): StreamEvent[] {
+  const events: StreamEvent[] = [];
+  let fullText = "";
+  for (const part of message.parts) {
+    if (part.type === "text") {
+      fullText += part.text ?? "";
+      continue;
+    }
+    if (!isToolPart(part)) continue;
+    const callId = part.toolCallId ?? "";
+    if (!callId || reported.calls.has(callId)) continue;
+    const name = toolNameOf(part);
+    const input = (part.input ?? null) as JsonValue;
+    if (part.state === "output-available") {
+      events.push({ type: "action.called", callId, name, input });
+      events.push({ type: "action.result", callId, output: part.output as JsonValue, status: "completed" });
+      reported.calls.add(callId);
+    } else if (part.state === "output-error") {
+      events.push({ type: "action.called", callId, name, input });
+      events.push({ type: "action.result", callId, output: part.errorText, status: "failed" });
+      reported.calls.add(callId);
+    } else if (part.state === "approval-responded" && part.approval?.approved === false) {
+      // 拒绝的调用从没真正执行,协议里不会再有它的任何帧 —— 在裁决落地的这一轮合成。
+      events.push({ type: "action.called", callId, name, input });
+      events.push({ type: "action.result", callId, status: "rejected" });
+      reported.calls.add(callId);
+    }
+    // approval-requested(还没裁决)/ input-* 中间态:先不报,等它到终态。
+  }
+  const newText = fullText.slice(reported.textLen);
+  if (newText.trim()) events.push({ type: "message", role: "assistant", text: newText });
+  reported.textLen = fullText.length;
+  return events;
+}
+
+// ───────────────────────── 工厂 ─────────────────────────
+
+export interface UiMessageStreamAgentOptions {
+  /** agent 名(报告 / 结果聚合的身份)。默认 "ui-message-stream"。 */
+  name?: string;
+  /** 被测应用的 chat 端点(完整 URL,应用在哪部署就指哪);函数形式每轮解析。 */
+  url: string | ((ctx: AgentContext) => string | Promise<string>);
+  /** 附加请求头(鉴权等);`ctx.telemetry.headers`(traceparent)总会自动并入。 */
+  headers?: Record<string, string> | ((ctx: AgentContext) => Record<string, string>);
+  /** 除 `messages` 外并入请求体的字段,如 `(ctx) => ({ model: ctx.model })`(undefined 字段序列化时自动丢弃)。 */
+  body?: (ctx: AgentContext) => Record<string, JsonValue | undefined>;
+  /**
+   * 拒绝审批时随 `approval-responded` 带出的理由。应用/SDK 会把它作为模型看到的工具结果
+   * 文本 —— 写清楚「不要重试」能明显降低模型原样重发同一调用的概率(实测)。
+   */
+  denyReason?: string;
+  /** 流结束后再等这么久才返回(毫秒),给应用侧的观测导出(如 BatchSpanProcessor)留时间。 */
+  settleMs?: number;
+  /** 应用有 OTel 时的端点投递方式(拿瀑布图);事件流不依赖它。 */
+  tracing?: AgentTracing;
+  spanMapper?: SpanMapper;
+}
+
+const DEFAULT_DENY_REASON = "用户拒绝了这次调用,不要重试,直接告知用户操作未执行。";
+
+/**
+ * UI Message Stream Protocol(AI SDK `useChat` 后端的标准 SSE 协议)的内置无侵入 adapter。
+ * 对着已部署应用的 HTTP 端点收发,不 import 应用代码:
+ *
+ * ```typescript
+ * import { uiMessageStreamAgent } from "niceeval/adapter";
+ *
+ * export default uiMessageStreamAgent({
+ *   name: "my-assistant",
+ *   url: "https://my-app.example.com/api/chat",
+ *   body: (ctx) => ({ model: ctx.model }),   // 应用支持请求级选模型时,模型对比零改动
+ * });
+ * ```
+ */
+export function uiMessageStreamAgent(options: UiMessageStreamAgentOptions): Agent {
+  return defineAgent({
+    name: options.name ?? "ui-message-stream",
+    tracing: options.tracing,
+    spanMapper: options.spanMapper,
+
+    async send(input: TurnInput, ctx: AgentContext) {
+      const { readUIMessageStream } = await loadAi();
+
+      // 会话续接是「客户端带全量历史」模式:历史槽直接挂在 ctx.session 上,新线自然为空。
+      // chat id(useChat 协议要求请求带,每条会话线固定一个)和 reported(HITL 续跑时跨轮
+      // 去重要用)是本协议特有的簿记,存进 ctx.session.state(逃生舱,随会话线创建/丢弃)。
+      const history = ctx.session.history<UIMessageLike>();
+      const priorMessages = history.get();
+      const bookkeeping = ctx.session.state as { chatId?: string; reported?: ReportedState };
+      let id = bookkeeping.chatId;
+      if (!id) {
+        id = `uims-${randomUUID()}`;
+        bookkeeping.chatId = id;
+        ctx.session.capture(id); // 镜像:t.sessionId / 报告可见
+      }
+
+      const lastMessage = priorMessages.at(-1);
+      const pendingPart =
+        lastMessage?.role === "assistant" ? lastMessage.parts.find(isApprovalRequested) : undefined;
+
+      let messagesToSend: UIMessageLike[];
+      let resumeFrom: UIMessageLike | undefined;
+
+      if (pendingPart && lastMessage) {
+        // HITL 续跑:不追加新 user 消息 —— 把停在 approval-requested 的 part 原地改成
+        // approval-responded,原样重发,服务端续跑同一条被打断的 assistant 消息。
+        // 裁决优先按 requestId 从 input.responses 读 optionId;没有 responses 才退回猜文本。
+        const requestId = pendingPart.approval?.id ?? pendingPart.toolCallId;
+        const approved = approvedFromResponse(input.responses, requestId, input.text);
+        const mutatedParts = lastMessage.parts.map((part) =>
+          isApprovalRequested(part) && part.approval?.id === pendingPart.approval?.id
+            ? {
+                ...part,
+                state: "approval-responded",
+                approval: {
+                  id: pendingPart.approval!.id,
+                  approved,
+                  ...(approved ? {} : { reason: options.denyReason ?? DEFAULT_DENY_REASON }),
+                },
+              }
+            : part,
+        );
+        resumeFrom = { ...lastMessage, parts: mutatedParts };
+        messagesToSend = [...priorMessages.slice(0, -1), resumeFrom];
+      } else {
+        const parts: UIMessagePartLike[] = [{ type: "text", text: input.text }];
+        for (const f of input.files ?? []) {
+          parts.push({ type: "file", mediaType: f.mimeType, url: `data:${f.mimeType};base64,${f.dataBase64}` });
+        }
+        messagesToSend = [...priorMessages, { id: randomUUID(), role: "user", parts }];
+      }
+
+      const url = typeof options.url === "function" ? await options.url(ctx) : options.url;
+      const extraHeaders = typeof options.headers === "function" ? options.headers(ctx) : (options.headers ?? {});
+      let res: Response;
+      try {
+        res = await fetch(url, {
+          method: "POST",
+          // traceparent 随请求带过去:应用埋点支持 context 传播时,span 归属精确到本轮。
+          headers: { "content-type": "application/json", ...extraHeaders, ...ctx.telemetry?.headers },
+          body: JSON.stringify({ ...options.body?.(ctx), messages: messagesToSend }),
+          signal: ctx.signal,
+        });
+      } catch (err) {
+        if (ctx.signal.aborted) throw err;
+        const cause = err instanceof Error ? (err.cause instanceof Error ? err.cause.message : err.message) : String(err);
+        throw new Error(`连不上 ${url}(${cause})。被测应用在跑吗?先按它自己的方式启动,或用配置把 url 指向已部署实例。`);
+      }
+      if (!res.ok || !res.body) {
+        throw new Error(
+          `POST ${url} 失败:${res.status} ${await res.text().catch(() => "")}。确认应用在跑、端点是 UI Message Stream 协议(useChat 的后端)。`,
+        );
+      }
+
+      let sawError: string | undefined;
+      const chunkStream = toChunkStream(res.body, (c) => {
+        if (c.type === "error") sawError = c.errorText;
+      });
+
+      let finalMessage: UIMessageLike | undefined;
+      for await (const msg of readUIMessageStream({ message: resumeFrom, stream: chunkStream })) {
+        finalMessage = msg;
+      }
+      if (!finalMessage) {
+        throw new Error(`POST ${url} 的流结束了但一条 assistant 消息都没归约出来 —— 端点吐的不是 UI Message Stream 帧?`);
+      }
+
+      // 续跑轮:finalMessage 是同一条消息的完整版,替换末尾半成品;全新轮:追加。
+      history.commit(
+        resumeFrom ? [...messagesToSend.slice(0, -1), finalMessage] : [...messagesToSend, finalMessage],
+      );
+
+      const reported: ReportedState = resumeFrom && bookkeeping.reported ? bookkeeping.reported : { calls: new Set(), textLen: 0 };
+      bookkeeping.reported = reported;
+      const events = deriveTurnEvents(finalMessage, reported);
+
+      const request = finalMessage.parts.find(isApprovalRequested);
+      if (request) {
+        return {
+          status: "waiting" as const,
+          events: [
+            ...events,
+            {
+              type: "input.requested" as const,
+              request: {
+                id: request.approval?.id ?? request.toolCallId,
+                action: toolNameOf(request),
+                input: (request.input ?? null) as JsonValue,
+                options: [{ id: "approve" }, { id: "deny" }],
+              },
+            },
+          ],
+        };
+      }
+
+      if (options.settleMs) await new Promise((resolve) => setTimeout(resolve, options.settleMs));
+      return {
+        status: sawError ? ("failed" as const) : ("completed" as const),
+        events: [...events, ...(sawError ? [{ type: "error" as const, message: sawError }] : [])],
+      };
+    },
+  });
+}