@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.0

package/src/execution/__tests__/ui-channels.test.ts

@@ -0,0 +1,187 @@
+// src/__tests__/ui-channels.test.ts
+//
+// W1 红灯测试：ui-channels.ts — channel 提取（marker 解析）+ channel 注册表。
+//
+// 测试对象：extensions/subagent-workflow/src/execution/ui-channels.ts（新建）
+// 契约来源：.fix-plans/00-master-summary.md §一 冲突 2「维度 2：channel 注册表」
+//
+// parseChannel(req): ExtensionUiRequest → { channel?, channelPayload? }
+//   - select → 从 title 解析 NUL 前缀（parseFromMarkerString）
+//   - setWidget → 从 widgetLines[0] 解析 NUL 前缀（parseFromMarkerArray）
+//   - 其他 method → {}（无 channel）
+//
+// marker 格式：\0<UPPER_CASE_ID>[:]<JSON-payload?>
+//   - ASK_USER_MARKER = "\0XYZ_ASK_USER"，payload 在 options[0]
+//   - GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:" + JSON，payload 在同行
+// channel 名规范化：去 "XYZ_" 前缀，小写化（XYZ_ASK_USER → ask_user）
+//
+// UiChannelRegistry:
+//   - register(channel, handler) / resolve(channel) / list()
+//
+// 边界：无 NUL 前缀 → {}；JSON parse 失败 → {}（不抛）；字段缺失 → {}
+//
+// 红灯原因：ui-channels.ts 尚未创建，import 失败。
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createUiChannelRegistry,
+  type ExtensionUiRequestLike,
+  parseChannel,
+} from "../ui-channels.ts";
+
+// ── 测试 fixture 构造助手 ────────────────────────────────────
+// ExtensionUiRequestLike 是 parseChannel 入参的最小形状（method + 对应字段）。
+
+function selectReq(title: string, options?: string[]): ExtensionUiRequestLike {
+  return { method: "select", title, options };
+}
+
+function setWidgetReq(widgetKey: string, widgetLines: string[] | undefined): ExtensionUiRequestLike {
+  return { method: "setWidget", widgetKey, widgetLines };
+}
+
+// ── ASK_USER_MARKER 样本（真实 Pi 协议格式） ─────────────────
+// title = "\0XYZ_ASK_USER"，options[0] = JSON.stringify({questions, allowCancel})
+const ASK_USER_MARKER = "\0XYZ_ASK_USER";
+const askUserPayload = {
+  questions: [{ question: "Pick one", options: [{ label: "A" }, { label: "B" }] }],
+  allowCancel: true,
+};
+
+// ── GUI_WIDGET_MARKER 样本（真实 Pi 协议格式） ───────────────
+// widgetLines[0] = "\0XYZ_GUI_WIDGET:" + JSON.stringify({component:{...}})
+const GUI_WIDGET_MARKER_PREFIX = "\0XYZ_GUI_WIDGET:";
+const guiWidgetPayload = { component: { name: "StatusCard", props: { ok: true } } };
+
+describe("parseChannel — select method（从 title 解析 NUL 前缀）", () => {
+  it("title 含 ASK_USER_MARKER → channel='ask_user' + payload 从 options[0] 解析", () => {
+    const req = selectReq(ASK_USER_MARKER, [JSON.stringify(askUserPayload)]);
+    const result = parseChannel(req);
+    expect(result.channel).toBe("ask_user");
+    expect(result.channelPayload).toEqual(askUserPayload);
+  });
+
+  it("title 无 NUL 前缀 → {}（普通 select，无 channel）", () => {
+    const req = selectReq("Choose a plan", ["basic", "pro"]);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+    expect(result.channelPayload).toBeUndefined();
+  });
+
+  it("title 含 marker 但 options 缺失 → channel 解析但 payload undefined", () => {
+    // marker 在 title，但 options 为空 → channel 名仍可提取，payload 无来源
+    const req = selectReq(ASK_USER_MARKER);
+    const result = parseChannel(req);
+    expect(result.channel).toBe("ask_user");
+  });
+});
+
+describe("parseChannel — setWidget method（从 widgetLines[0] 解析 NUL 前缀）", () => {
+  it("widgetLines[0] 含 GUI_WIDGET_MARKER → channel='gui_widget' + payload", () => {
+    const req = setWidgetReq("w1", [GUI_WIDGET_MARKER_PREFIX + JSON.stringify(guiWidgetPayload)]);
+    const result = parseChannel(req);
+    expect(result.channel).toBe("gui_widget");
+    expect(result.channelPayload).toEqual(guiWidgetPayload);
+  });
+
+  it("widgetLines 无 NUL 前缀 → {}（普通 setWidget）", () => {
+    const req = setWidgetReq("w1", ["plain content line"]);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("widgetLines 为 undefined → {}", () => {
+    const req = setWidgetReq("w1", undefined);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("widgetLines 为空数组 → {}", () => {
+    const req = setWidgetReq("w1", []);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+  });
+});
+
+describe("parseChannel — 其他 method（无 channel 提取位置）", () => {
+  it("confirm → {}", () => {
+    const result = parseChannel({ method: "confirm", title: "t", message: "m" });
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("input → {}", () => {
+    const result = parseChannel({ method: "input", title: "t" });
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("notify → {}", () => {
+    const result = parseChannel({ method: "notify", message: "hi" });
+    expect(result.channel).toBeUndefined();
+  });
+});
+
+describe("parseChannel — channel 名规范化规则", () => {
+  it("去 XYZ_ 命名空间前缀 + 小写化（XYZ_ASK_USER → ask_user）", () => {
+    const req = selectReq("\0XYZ_ASK_USER", [JSON.stringify({ x: 1 })]);
+    expect(parseChannel(req).channel).toBe("ask_user");
+  });
+
+  it("XYZ_GUI_WIDGET: 带冒号后缀 → gui_widget（去前缀 + 去冒号 + 小写）", () => {
+    const req = setWidgetReq("k", ["\0XYZ_GUI_WIDGET:" + JSON.stringify({ y: 2 })]);
+    expect(parseChannel(req).channel).toBe("gui_widget");
+  });
+});
+
+describe("parseChannel — 边界（不抛错）", () => {
+  it("marker 后 payload 非法 JSON → 不抛错，channel 仍解析（payload undefined）", () => {
+    const req = selectReq(ASK_USER_MARKER, ["not-valid-json{"]);
+    expect(() => parseChannel(req)).not.toThrow();
+    const result = parseChannel(req);
+    expect(result.channel).toBe("ask_user");
+  });
+
+  it("GUI_WIDGET_MARKER 后非法 JSON → 不抛错", () => {
+    const req = setWidgetReq("k", [GUI_WIDGET_MARKER_PREFIX + "broken{json"]);
+    expect(() => parseChannel(req)).not.toThrow();
+  });
+});
+
+// ── UiChannelRegistry ────────────────────────────────────────
+
+describe("UiChannelRegistry — 注册 + 解析 + 列举", () => {
+  it("register 后 resolve 返回注册的 handler", () => {
+    const registry = createUiChannelRegistry();
+    const handler = vi.fn();
+    registry.register("ask_user", handler);
+    expect(registry.resolve("ask_user")).toBe(handler);
+  });
+
+  it("未注册的 channel resolve 返回 undefined", () => {
+    const registry = createUiChannelRegistry();
+    expect(registry.resolve("unknown")).toBeUndefined();
+  });
+
+  it("list 返回所有已注册 channel 名", () => {
+    const registry = createUiChannelRegistry();
+    registry.register("ask_user", vi.fn());
+    registry.register("gui_widget", vi.fn());
+    const names = registry.list().sort();
+    expect(names).toEqual(["ask_user", "gui_widget"]);
+  });
+
+  it("list 空注册表返回 []", () => {
+    const registry = createUiChannelRegistry();
+    expect(registry.list()).toEqual([]);
+  });
+
+  it("重复 register 同名 channel 覆盖旧 handler", () => {
+    const registry = createUiChannelRegistry();
+    const old = vi.fn();
+    const fresh = vi.fn();
+    registry.register("ask_user", old);
+    registry.register("ask_user", fresh);
+    expect(registry.resolve("ask_user")).toBe(fresh);
+    expect(registry.list()).toEqual(["ask_user"]);
+  });
+});

package/src/execution/__tests__/ui-interaction-model.test.ts

@@ -0,0 +1,67 @@
+// src/__tests__/ui-interaction-model.test.ts
+//
+// W1 红灯测试：ui-interaction-model.ts — method 交互模型分类。
+//
+// 测试对象：extensions/subagent-workflow/src/execution/ui-interaction-model.ts（新建）
+// 契约来源：.fix-plans/00-master-summary.md §一 冲突 2「维度 1：透传判定规则」
+//
+// isDialogMethod(method):
+//   - dialog（占输入焦点，等响应，需透传+排队）：select / confirm / input / editor → true
+//   - fire-and-forget（纯展示/写入，不等响应）：notify / setStatus / setWidget /
+//     setTitle / set_editor_text / 未知 method → false
+//
+// 红灯原因：ui-interaction-model.ts 尚未创建，import 失败。
+
+import { describe, expect, it } from "vitest";
+
+import { isDialogMethod } from "../ui-interaction-model.ts";
+
+describe("isDialogMethod — dialog 类 method（占输入焦点）", () => {
+  it("select → true（含 ask_user channel 借道 select）", () => {
+    expect(isDialogMethod("select")).toBe(true);
+  });
+
+  it("confirm → true", () => {
+    expect(isDialogMethod("confirm")).toBe(true);
+  });
+
+  it("input → true", () => {
+    expect(isDialogMethod("input")).toBe(true);
+  });
+
+  it("editor → true", () => {
+    expect(isDialogMethod("editor")).toBe(true);
+  });
+});
+
+describe("isDialogMethod — fire-and-forget 类 method（纯展示/写入）", () => {
+  it("notify → false", () => {
+    expect(isDialogMethod("notify")).toBe(false);
+  });
+
+  it("setStatus → false", () => {
+    expect(isDialogMethod("setStatus")).toBe(false);
+  });
+
+  it("setWidget → false（含 gui_widget channel 借道 setWidget）", () => {
+    expect(isDialogMethod("setWidget")).toBe(false);
+  });
+
+  it("setTitle → false", () => {
+    expect(isDialogMethod("setTitle")).toBe(false);
+  });
+
+  it("set_editor_text → false", () => {
+    expect(isDialogMethod("set_editor_text")).toBe(false);
+  });
+});
+
+describe("isDialogMethod — 未知 method 默认 fire-and-forget", () => {
+  it("未知 method 名 → false（未来 Pi 新增 method 不误判为 dialog）", () => {
+    expect(isDialogMethod("some_future_method")).toBe(false);
+  });
+
+  it("空字符串 → false", () => {
+    expect(isDialogMethod("")).toBe(false);
+  });
+});

package/src/execution/__tests__/ui-request-handler-factory.test.ts

@@ -0,0 +1,166 @@
+// src/__tests__/ui-request-handler-factory.test.ts
+//
+// C1 测试：ui-request-handler-factory.ts — createUiRequestHandlerForMode 透传矩阵。
+//
+// 透传矩阵（createUiRequestHandlerForMode 返回的 handler 行为）：
+//   - headless（json/print/undefined）：返回 undefined（不注入 handler）
+//   - TUI：fire-and-forget 回 ack 不透传；dialog 进 dialogQueue 串行
+//   - GUI（rpc）：fire-and-forget 直接调 realHandler；dialog 进 dialogQueue 串行
+// realHandler 路由：channel 命中 → channelHandler（经 coerceUiResponse 形变）；未命中 → defaultDialogForward（cancelled）。
+// 测接口契约，不测实现细节。
+
+import type { ExtensionContext, ExtensionMode } from "@mariozechner/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DialogGlobalQueue, type UiRequest } from "../dialog-queue.ts";
+import { type ChannelHandler,createUiChannelRegistry } from "../ui-channels.ts";
+import { createUiRequestHandlerForMode } from "../ui-request-handler-factory.ts";
+
+// mock ExtensionContext 已补 mode 字段（host-mode.ts 读它分流）。最小形状构造。
+function makeCtx(mode: ExtensionMode): ExtensionContext {
+  return {
+    cwd: "/tmp/test",
+    mode,
+    sessionManager: {
+      getSessionId: () => "s1",
+      getSessionFile: () => undefined,
+      getSessionDir: () => "/tmp/test/sessions",
+    },
+    modelRegistry: undefined,
+    model: undefined,
+  } as ExtensionContext;
+}
+
+function dialogReq(id: string, channel?: string): UiRequest {
+  return { method: "select", id, title: `q-${id}`, ...(channel ? { channel } : {}) };
+}
+
+function fireAndForgetReq(id: string): UiRequest {
+  return { method: "notify", id, message: `n-${id}` };
+}
+
+// dialog 路径用 fake timers 推进 processNext；静默 console.warn/error（stub 故意 warn）。
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("createUiRequestHandlerForMode — headless 返回 undefined", () => {
+  it("mode='json' → undefined（不注入 handler）", () => {
+    const queue = new DialogGlobalQueue();
+    expect(createUiRequestHandlerForMode(makeCtx("json"), createUiChannelRegistry(), queue))
+      .toBeUndefined();
+  });
+
+  it("mode='print' → undefined", () => {
+    const queue = new DialogGlobalQueue();
+    expect(createUiRequestHandlerForMode(makeCtx("print"), createUiChannelRegistry(), queue))
+      .toBeUndefined();
+  });
+});
+
+describe("createUiRequestHandlerForMode — TUI 模式透传", () => {
+  it("fire-and-forget（notify）→ {ack:true}，不调 realHandler / 不入队", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("tui"), registry, queue)!;
+    const resp = await handler(fireAndForgetReq("f1"));
+
+    expect(resp).toEqual({ ack: true });
+    expect(console.warn).not.toHaveBeenCalled(); // realHandler（defaultDialogForward）未走
+    expect(enqueueSpy).not.toHaveBeenCalled();
+  });
+
+  it("dialog（select 无 channel）→ 进 dialogQueue（enqueue 被调，defaultDialogForward stub cancelled）", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("tui"), registry, queue)!;
+    const pending = handler(dialogReq("d1"));
+
+    expect(enqueueSpy).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(0);
+    await expect(pending).resolves.toEqual({ cancelled: true });
+  });
+});
+
+describe("createUiRequestHandlerForMode — GUI（rpc）模式透传", () => {
+  it("fire-and-forget（notify）→ 直接调 realHandler，不入队", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, queue)!;
+    // notify 无 channel → realHandler → defaultDialogForward（cancelled）
+    const resp = await handler(fireAndForgetReq("f1"));
+
+    expect(enqueueSpy).not.toHaveBeenCalled();
+    expect(resp).toEqual({ cancelled: true });
+  });
+
+  it("dialog（select 无 channel）→ 进 dialogQueue", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, queue)!;
+    const pending = handler(dialogReq("d1"));
+
+    expect(enqueueSpy).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(0);
+    await expect(pending).resolves.toEqual({ cancelled: true });
+  });
+});
+
+describe("createUiRequestHandlerForMode — channel 业务路由", () => {
+  it("channel 命中 registry → 调注册的 channelHandler（不走 defaultDialogForward）", async () => {
+    const registry = createUiChannelRegistry();
+    const channelHandler: ChannelHandler = vi.fn(async () => ({ value: "from-channel" }));
+    registry.register("ask_user", channelHandler);
+
+    // GUI fire-and-forget 直接调 realHandler，绕过队列；channel 命中立即生效
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, new DialogGlobalQueue())!;
+    const resp = await handler({ method: "notify", id: "f1", message: "m", channel: "ask_user" });
+
+    expect(channelHandler).toHaveBeenCalledTimes(1);
+    expect(resp).toEqual({ value: "from-channel" });
+  });
+
+  it("channel 未命中 → defaultDialogForward（stub cancelled）", async () => {
+    const handler = createUiRequestHandlerForMode(
+      makeCtx("rpc"), createUiChannelRegistry(), new DialogGlobalQueue())!;
+    const resp = await handler({ method: "notify", id: "f1", message: "m", channel: "unknown" });
+    expect(resp).toEqual({ cancelled: true });
+  });
+});
+
+// coerceUiResponse 形变（通过 channelHandler 返回不同 shape 间接测）
+describe("createUiRequestHandlerForMode — coerceUiResponse 形变", () => {
+  async function callWithChannel(raw: unknown) {
+    const registry = createUiChannelRegistry();
+    registry.register("ask_user", (async () => raw) as ChannelHandler);
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, new DialogGlobalQueue())!;
+    return handler({ method: "notify", id: "f1", message: "m", channel: "ask_user" });
+  }
+
+  it("channelHandler 返回 {value:'x'} → {value:'x'}", async () => {
+    expect(await callWithChannel({ value: "x" })).toEqual({ value: "x" });
+  });
+
+  it("channelHandler 返回 {confirmed:true} → {confirmed:true}", async () => {
+    expect(await callWithChannel({ confirmed: true })).toEqual({ confirmed: true });
+  });
+
+  it("channelHandler 返回 null（非法）→ 降级 {cancelled:true}", async () => {
+    expect(await callWithChannel(null)).toEqual({ cancelled: true });
+  });
+});

package/src/execution/__tests__/ui-request-handler.test.ts

@@ -0,0 +1,204 @@
+// src/__tests__/ui-request-handler.test.ts
+//
+// W2 测试（TC-W2 / SR-2）：UI 请求处理 —— Pi 原生协议格式。
+//
+// 测试对象：session-runner.ts 的 handleUiRequest + spawn-event-adapter.ts 的 parseSpawnLine
+// 契约来源：.fix-plans/00-master-summary.md §二 2.1（ExtensionUiRequest）+ 2.2（UiRequest/channel）
+//          + 2.3（stdin 回写 extension_ui_response 格式）+ §一冲突 2（channel 提取在 session-runner 层）
+//
+// 修复原因（FR-12/SR-2）：
+//   旧测试用错误的 JSON-RPC 2.0 格式 mock（jsonrpc:"2.0" + params.marker:"ASK_USER"
+//   + params.questions），测试绿但生产红（Pi 实际发 {type, method, title, options} 平铺）。
+//   改为 Pi 真实格式 + channel/channelPayload 断言 + extension_ui_response 回写格式。
+//
+// 红灯原因：handleUiRequest 签名仍是旧的 (child, id, params, ctx, signal)
+//   + parseChannel 未接入 session-runner，编译失败。W2 改完签名后转绿。
+
+import { PassThrough } from "node:stream";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { ASK_USER_RPC_PROMPT } from "../session-runner.ts";
+import { parseSpawnLine } from "../spawn-event-adapter.ts";
+import { parseChannel } from "../ui-channels.ts";
+import { createUiRequestQueue, type UiRequest, type UiRequestHandler } from "../ui-request-queue.ts";
+
+// ── Pi 原生协议样本构造 ────────────────────────────────────
+// 真实格式：{type:"extension_ui_request", id, method:"select",
+//           title:"\0XYZ_ASK_USER", options:[JSON.stringify({questions, allowCancel})]}
+// 无 jsonrpc 字段、无 params 包裹、method 在顶层（非 method:"extension_ui_request"）。
+
+const ASK_USER_MARKER = "\0XYZ_ASK_USER";
+const askUserPayload = {
+  questions: [
+    {
+      question: "What is your preference?",
+      options: [{ label: "Option A" }, { label: "Option B" }],
+    },
+  ],
+  allowCancel: true,
+};
+
+function askUserLine(id: string): string {
+  return JSON.stringify({
+    type: "extension_ui_request",
+    id,
+    method: "select",
+    title: ASK_USER_MARKER,
+    options: [JSON.stringify(askUserPayload)],
+  });
+}
+
+// ── 解析：Pi 原生格式 → ExtensionUiRequest（method 平铺，无 params） ─────
+
+describe("parseSpawnLine — ask_user 请求解析（Pi 原生格式）", () => {
+  it("ask_user 行被识别为 extension_ui_request kind", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    expect(result?.kind).toBe("extension_ui_request");
+  });
+
+  it("request.method === 'select'（ask_user 借道 select dialog 通道）", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") {
+      expect.fail("expected extension_ui_request kind");
+      return;
+    }
+    expect(result.request.method).toBe("select");
+  });
+
+  it("request.title === ASK_USER_MARKER（NUL 前缀 marker 原样保留，由 parseChannel 提取）", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    expect(result.request.title).toBe(ASK_USER_MARKER);
+  });
+
+  it("id 被正确提取（用于 response 关联）", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    expect(result.id).toBe("ui-req-001");
+  });
+});
+
+// ── channel 提取（session-runner 层消费 parseChannel） ──────────────
+// adapter 层只做协议解析（method + 字段平铺），channel 提取在 session-runner 层。
+// 对 select.title 的 NUL 前缀解析出 channel='ask_user' + payload={questions, allowCancel}。
+
+describe("parseChannel — ask_user channel 提取（session-runner 层）", () => {
+  it("select.title 含 ASK_USER_MARKER → channel='ask_user'", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    const channel = parseChannel(result.request);
+    expect(channel.channel).toBe("ask_user");
+  });
+
+  it("channelPayload 已 parse 为 {questions, allowCancel}", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    const channel = parseChannel(result.request);
+    expect(channel.channelPayload).toEqual(askUserPayload);
+  });
+});
+
+// ── stdin 回写格式：extension_ui_response（非 JSON-RPC 2.0 result） ─────
+
+describe("handleUiRequest — stdin 回写 extension_ui_response（Pi 原生格式）", () => {
+  it("handler 返回 {value} → stdin 写入 {type:extension_ui_response, id, value}", async () => {
+    const stdin = new PassThrough();
+    const written: string[] = [];
+    stdin.on("data", (chunk: Buffer) => written.push(chunk.toString()));
+
+    const child = { stdin, on: vi.fn(), removeListener: vi.fn() } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[0];
+
+    const handler: UiRequestHandler = vi.fn(
+      async (req: UiRequest) => ({ value: `answer-for-${req.id}` }),
+    );
+    const ctx = { uiRequestHandler: handler } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+
+    const enqueue = createUiRequestQueue(child, ctx);
+    // W2 新签名：enqueue(id, request) —— request 是 ExtensionUiRequest（method 平铺）
+    enqueue("ui-req-002", {
+      method: "select",
+      title: ASK_USER_MARKER,
+      options: [JSON.stringify(askUserPayload)],
+    });
+
+    // 等微任务 + stdin flush
+    await new Promise((r) => setImmediate(r));
+
+    const raw = written.join("");
+    expect(raw).toContain('"type":"extension_ui_response"');
+    expect(raw).toContain('"id":"ui-req-002"');
+    expect(raw).toContain('"value":"answer-for-ui-req-002"');
+    // 旧 JSON-RPC 2.0 格式不应出现
+    expect(raw).not.toContain('"jsonrpc"');
+    expect(raw).not.toContain('"result"');
+  });
+});
+
+// ── handler 抛错兜底（M5）：catch → 回 cancelled → 写 stdin ─────
+// session-runner.ts:489-494 的 catch 分支：handler reject 时兜底写 cancelled。
+
+describe("handleUiRequest — handler 抛错兜底回 cancelled", () => {
+  it("handler reject(new Error('boom')) → stdin 写入 cancelled:true", async () => {
+    const stdin = new PassThrough();
+    const written: string[] = [];
+    stdin.on("data", (chunk: Buffer) => written.push(chunk.toString()));
+
+    const child = { stdin, on: vi.fn(), removeListener: vi.fn() } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[0];
+
+    // handler 抛错（reject）
+    const handler: UiRequestHandler = vi.fn(
+      async () => Promise.reject(new Error("boom")),
+    );
+    const ctx = { uiRequestHandler: handler } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+
+    const enqueue = createUiRequestQueue(child, ctx);
+    enqueue("ui-req-err", {
+      method: "select",
+      title: ASK_USER_MARKER,
+      options: [JSON.stringify(askUserPayload)],
+    });
+
+    // 等微任务 + stdin flush
+    await new Promise((r) => setImmediate(r));
+
+    const raw = written.join("");
+    expect(raw).toContain('"type":"extension_ui_response"');
+    expect(raw).toContain('"id":"ui-req-err"');
+    expect(raw).toContain('"cancelled":true');
+  });
+});
+
+// ── W4 提示词（保留，不受格式修复影响） ──────────────────────────
+
+describe("W4: ask_user RPC 系统提示词注入", () => {
+  it("ASK_USER_RPC_PROMPT 常量已导出且非空", () => {
+    expect(ASK_USER_RPC_PROMPT).toBeDefined();
+    expect(typeof ASK_USER_RPC_PROMPT).toBe("string");
+    expect(ASK_USER_RPC_PROMPT.length).toBeGreaterThan(0);
+  });
+
+  it("提示词包含 ask_user 工具说明", () => {
+    expect(ASK_USER_RPC_PROMPT).toContain("ask_user");
+    expect(ASK_USER_RPC_PROMPT).toContain("Tool Availability");
+  });
+
+  it("提示词告知 LLM ask_user 走 RPC 转发", () => {
+    expect(ASK_USER_RPC_PROMPT).toContain("RPC");
+    expect(ASK_USER_RPC_PROMPT).toContain("main agent");
+    expect(ASK_USER_RPC_PROMPT).toContain("forwarded");
+  });
+
+  it("提示词说明用户在主 agent 界面回答", () => {
+    expect(ASK_USER_RPC_PROMPT).toContain("user");
+    expect(ASK_USER_RPC_PROMPT).toContain("answers");
+  });
+});