@zhushanwen/pi-ask-user 0.2.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview, inline editor, and optional comments.",
   "type": "module",
   "main": "index.ts",
@@ -37,11 +37,15 @@
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@sinclair/typebox": "*",
+    "@zhushanwen/pi-subagent-workflow": "*"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-tui": {
       "optional": true
+    },
+    "@zhushanwen/pi-subagent-workflow": {
+      "optional": true
     }
   },
   "scripts": {

package/src/__tests__/channel-handler.test.ts

@@ -0,0 +1,286 @@
+// src/__tests__/channel-handler.test.ts
+//
+// Tests createAskUserChannelHandler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
+//
+// 覆盖：
+//   - RPC 路径（ctx.mode === 'rpc'）：转发器——handler 内部调 askUserInteract（select 通道），
+//     把 proto answers JSON.stringify 成 {value} 返回，子进程 JSON.parse(value) 正确 decode。
+//   - TUI 路径（ctx.mode === 'tui'）：handler 走 ctx.ui.custom（mock 成返回预设 Result），
+//     验证内部 Result → proto AskUserAnswers 重新编码（single/multi/Other/comment 四种答案形态）。
+//   - 取消（askUserInteract/custom 返回 null 或 cancelled）→ {cancelled: true}
+//   - 输入校验（channelPayload 缺失/无 questions）→ {cancelled: true}
+import type { AskUserQuestion } from "@xyz-agent/extension-protocol";
+import { describe, expect, it } from "vitest";
+
+import { createAskUserChannelHandler } from "../channel-handler";
+import type { Result } from "../types";
+
+// ── Mock ctx ───────────────────────────────────────────
+// RPC：ctx.ui.select 模拟前端回传的 proto answers（JSON.stringify(AskUserAnswers)）。
+// TUI：ctx.ui.custom 模拟 AskUserComponent 产出的内部 Result。
+type CtxMode = "tui" | "rpc";
+
+interface MockCtxOpts {
+	mode: CtxMode;
+	/** RPC：select 返回的 value（JSON.stringify 后的 proto answers）；undefined = 取消 */
+	selectResult?: string | undefined;
+	/** TUI：custom 返回的内部 Result；null = 用户取消 */
+	customResult?: Result | null;
+}
+
+function makeCtx(opts: MockCtxOpts): {
+	mode: CtxMode;
+	hasUI: boolean;
+	ui: {
+		select?: (title: string, options: string[], o?: { signal?: AbortSignal }) => Promise<string | undefined>;
+		custom: <T = void>(factory: unknown) => Promise<T>;
+	};
+} {
+	const { mode, selectResult, customResult } = opts;
+	const hasUI = true;
+	if (mode === "rpc") {
+		return {
+			mode,
+			hasUI,
+			ui: {
+				select: async (): Promise<string | undefined> => selectResult,
+				custom: async <T = void>(): Promise<T> => undefined as T,
+			},
+		};
+	}
+	// TUI
+	return {
+		mode,
+		hasUI,
+		ui: {
+			custom: async <T = void>(): Promise<T> => customResult as T,
+		},
+	};
+}
+
+// ── 样例 proto questions（handler 收到的格式） ──────────
+const singleProto: AskUserQuestion = {
+	question: "Which DB?",
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
+const multiProto: AskUserQuestion = {
+	question: "Which tools?",
+	header: "Tools",
+	multiSelect: true,
+	options: [
+		{ label: "A", value: "A" },
+		{ label: "B", value: "B" },
+		{ label: "C", value: "C" },
+	],
+};
+
+const commentProto: AskUserQuestion = {
+	question: "Which DB?",
+	allowComment: true,
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
+// ── Tests ───────────────────────────────────────────────
+
+describe("createAskUserChannelHandler", () => {
+	it("RPC: single-select proto answers → {value: JSON.stringify(answers)}", async () => {
+		// 前端回传 proto answers：{[key]: value}，key = question 全文（无 header）
+		const protoAnswers = { "Which DB?": "Postgres" };
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
+	});
+
+	it("RPC: multi-select proto answers (JSON array value) → 透传", async () => {
+		const protoAnswers = { Tools: JSON.stringify(["A", "C"]) };
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
+	});
+
+	it("RPC: Other + comment proto answers → 透传", async () => {
+		const protoAnswers = {
+			"Which DB?": "Postgres",
+			"Which DB?__other": "Custom DB",
+			"Which DB?__comment": "prod constraint",
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [commentProto] } });
+		expect(resp).toEqual({ value: JSON.stringify(protoAnswers) });
+	});
+
+	it("RPC: user cancel (select undefined) → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("TUI: internal Result single-select → 重新编码为 proto answers", async () => {
+		// 内部 Result.answers：key = question 全文，value = 选中 label
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		// 期望：proto answers { "Which DB?": "Postgres" }
+		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
+	});
+
+	it("TUI: multi-select internal Result → proto JSON array value", async () => {
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which tools?": "A, C" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		// 期望：key=header "Tools"，value = JSON.stringify(["A","C"])
+		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
+	});
+
+	it("TUI: value≠label single-select → encodeTuiResultToProto 回查 proto option value（PR #85 #8 回归守护）", async () => {
+		// value≠label 是 #8 修复的核心场景：TUI 渲染用 label，但 proto 期望回传 option.value。
+		// 若 #8 修复回归（直接 push label），此测试会失败：返回 "显示名A" 而非 "val_a"。
+		const valueNeqLabelProto: AskUserQuestion = {
+			question: "选哪个?",
+			options: [
+				{ label: "显示名A", value: "val_a" },
+				{ label: "显示名B", value: "val_b" },
+			],
+		};
+		// 内部 Result.answers：用户在 TUI 选了"显示名A"（label）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "选哪个?": "显示名A" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [valueNeqLabelProto] } });
+		// 期望：proto answers 回查 value，返回 "val_a"（不是 label "显示名A"）
+		expect(resp).toEqual({ value: JSON.stringify({ "选哪个?": "val_a" }) });
+	});
+
+	it("TUI: value≠label multi-select → proto JSON 数组元素回查 value（PR #85 #8 回归守护）", async () => {
+		// 多选路径同样依赖 #8 修复：selected.push(opt?.value ?? t)，多选会 JSON.stringify 数组。
+		const valueNeqLabelMultiProto: AskUserQuestion = {
+			question: "选哪些?",
+			header: "Opts",
+			multiSelect: true,
+			options: [
+				{ label: "显示名A", value: "val_a" },
+				{ label: "显示名B", value: "val_b" },
+			],
+		};
+		const internalResult: Result = {
+			questions: [],
+			answers: { "选哪些?": "显示名A, 显示名B" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [valueNeqLabelMultiProto] } });
+		// 期望：多选 JSON 数组，每个元素回查 value（["val_a","val_b"]，不是 label）
+		expect(resp).toEqual({ value: JSON.stringify({ Opts: JSON.stringify(["val_a", "val_b"]) }) });
+	});
+
+	it("TUI: Other free text → ${key}__other", async () => {
+		// 内部 Result：selected label + Other 文本逗号拼接（与 getAnswerText 语义一致）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres, Custom DB" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__other": "Custom DB" }),
+		});
+	});
+
+	it("TUI: comment → ${key}__comment", async () => {
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres — prod constraint" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [commentProto] } });
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__comment": "prod constraint" }),
+		});
+	});
+
+	it("TUI: user cancel (custom returns null) → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: null }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("TUI: custom returns cancelled Result → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({
+				mode: "tui",
+				customResult: { questions: [], answers: {}, cancelled: true },
+			}) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: channelPayload missing → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({});
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: questions empty array → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({ channelPayload: { questions: [] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: questions not an array → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({ channelPayload: { questions: "not-array" } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: req is null/undefined → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		expect(await handler(null)).toEqual({ cancelled: true });
+		expect(await handler(undefined)).toEqual({ cancelled: true });
+	});
+
+	it("RPC: allowCancel passed through to askUserInteract (default true)", async () => {
+		// allowCancel 默认 true：验证不抛错（select mock 返回 undefined=取消）
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+});

package/src/__tests__/channel-registry-register.test.ts

@@ -0,0 +1,180 @@
+// src/__tests__/channel-registry-register.test.ts
+//
+// Tests registerAskUserChannelHandler：ask-user 侧的 globalThis Symbol 握手注册纯函数。
+//
+// 覆盖（PR #85 #M4 + #M5）：
+//   - 空 globalThis → 建 slot（仅 pending），handler 入 pending；**slot.registry === undefined**
+//     （M4 核心断言：ask-user 永不创建 registry 实例）
+//   - slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）
+//   - slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)，pending 不增长
+//   - 重复调用：registry 就绪时 register 多次（同名覆盖幂等）；未就绪时 pending.length 增长
+//   - version !== 1 → warn + 重建为新 slot，旧 pending 丢弃
+//
+// 隔离：每个用例前 Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY)。
+import { beforeEach,describe, expect, it, vi } from "vitest";
+
+import type { ChannelHandler } from "../channel-handler";
+import {
+	CHANNEL_HANDSHAKE_KEY,
+	type ChannelRegistryHandshake,
+	registerAskUserChannelHandler,
+} from "../channel-registry-register";
+
+// 拿到当前 slot（cast any 安全：测试控制 slot 写入，结构已知）
+function readSlot(): ChannelRegistryHandshake | undefined {
+	return Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as
+		| ChannelRegistryHandshake
+		| undefined;
+}
+
+/** 塞一个指定 version 的 slot（手动构造，绕过 registerAskUserChannelHandler）。 */
+function writeSlot(slot: ChannelRegistryHandshake): void {
+	Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
+}
+
+/** 用 spy 构造 mock registry：register 是 vi.fn，pending flush 时可断言调用。 */
+function makeMockRegistry(): {
+	register: ReturnType<typeof vi.fn>;
+	resolve: ReturnType<typeof vi.fn>;
+	list: ReturnType<typeof vi.fn>;
+} {
+	return {
+		register: vi.fn(),
+		resolve: vi.fn().mockReturnValue(undefined),
+		list: vi.fn().mockReturnValue([]),
+	};
+}
+
+// 占位 handler——测试只关心调用计数和参数，handler 实体不重要
+const noopHandler: ChannelHandler = async () => undefined;
+
+describe("registerAskUserChannelHandler", () => {
+	beforeEach(() => {
+		Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY);
+	});
+
+	it("空 globalThis → 建 slot，handler 入 pending，slot.registry === undefined（M4 核心）", () => {
+		expect(readSlot()).toBeUndefined();
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		expect(slot).toBeDefined();
+		expect(slot!.version).toBe(1);
+		// M4 核心断言：ask-user 永不创建 registry 实例
+		expect(slot!.registry).toBeUndefined();
+		expect(slot!.pending).toHaveLength(1);
+		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: noopHandler });
+	});
+
+	it("slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）", () => {
+		// 预置 slot：version=1，pending=[]，registry 缺失（模拟 subagent-workflow 尚未 session_start）
+		const preSlot: ChannelRegistryHandshake = { version: 1, pending: [] };
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		expect(slot).toBe(preSlot); // 同一对象，未重建
+		expect(slot!.registry).toBeUndefined();
+		expect(slot!.pending).toHaveLength(1);
+		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: noopHandler });
+	});
+
+	it("slot 存在且 registry 就绪 → 调 registry.register，pending 不增长", () => {
+		const mockRegistry = makeMockRegistry();
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: [],
+		};
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		expect(mockRegistry.register).toHaveBeenCalledWith("ask_user", noopHandler);
+		// pending 不增长（直接 register，不进队列）
+		expect(preSlot.pending).toHaveLength(0);
+	});
+
+	it("registry 就绪时重复 register → register 被调多次（同名覆盖幂等，pending 始终 0）", () => {
+		const mockRegistry = makeMockRegistry();
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: [],
+		};
+		writeSlot(preSlot);
+
+		const h1: ChannelHandler = async () => "a";
+		const h2: ChannelHandler = async () => "b";
+		registerAskUserChannelHandler(h1);
+		registerAskUserChannelHandler(h2);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(2);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(1, "ask_user", h1);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(2, "ask_user", h2);
+		expect(preSlot.pending).toHaveLength(0); // 幂等：不进 pending
+	});
+
+	it("registry 未就绪时多次 register → pending.length 增长（顺序保留）", () => {
+		// 第 1 次：空 globalThis → 建 slot + pending[0]
+		const h1: ChannelHandler = async () => "a";
+		registerAskUserChannelHandler(h1);
+		// 第 2 次：slot 已存在、registry 仍 undefined → pending[1]
+		const h2: ChannelHandler = async () => "b";
+		registerAskUserChannelHandler(h2);
+
+		const slot = readSlot();
+		expect(slot!.registry).toBeUndefined();
+		expect(slot!.pending).toHaveLength(2);
+		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: h1 });
+		expect(slot!.pending[1]).toEqual({ channel: "ask_user", handler: h2 });
+	});
+
+	it("version !== 1 → warn + 重建为新 slot，旧 pending 丢弃", () => {
+		// 塞一个 version=2 的旧 slot（模拟未来协议升级 / 脏数据）
+		const spyWarn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		const legacyPending = [{ channel: "stale", handler: noopHandler }];
+		const legacySlot = {
+			version: 2 as const,
+			registry: makeMockRegistry() as unknown as ChannelRegistryHandshake["registry"],
+			pending: legacyPending,
+		};
+		writeSlot(legacySlot as unknown as ChannelRegistryHandshake);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		// 旧 slot 被替换（version 退回 1，pending 重置为仅含本次注册）
+		expect(slot).not.toBe(legacySlot);
+		expect(slot!.version).toBe(1);
+		expect(slot!.pending).toEqual([{ channel: "ask_user", handler: noopHandler }]);
+		// warn 被调用（包含 version mismatch 提示）
+		expect(spyWarn).toHaveBeenCalledTimes(1);
+		expect(spyWarn.mock.calls[0]![0]).toContain("version mismatch");
+
+		spyWarn.mockRestore();
+	});
+
+	it("registry 就绪但 slot 已预置 pending → 仍走 register 路径（pending 不被本函数消费）", () => {
+		// 边界：subagent-workflow flush 后理论上 pending 应为空，但若 flush 漏了，
+		// 新 handler 来时仍应直接 register（不消费遗留 pending——那是 subagent-workflow 的职责）。
+		const mockRegistry = makeMockRegistry();
+		const preExistingPending = [{ channel: "ask_user", handler: noopHandler }];
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: preExistingPending,
+		};
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		// 遗留 pending 未被消费（长度不变）
+		expect(preSlot.pending).toHaveLength(1);
+		expect(preSlot.pending).toBe(preExistingPending);
+	});
+});

package/src/__tests__/e2e-harness.ts

@@ -16,6 +16,8 @@ interface PiShape {
 	registerTool(t: unknown): void;
 	getAllTools(): { name: string }[];
 	setActiveTools(names: string[]): void;
+	// session_start handler（factory 注册透传 channel 用）；测试不覆盖透传，空实现。
+	on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 
 export interface E2EApi {
@@ -48,6 +50,9 @@ export function makeE2E(questions: Question[], opts: E2EOptions = {}): E2EApi {
 		setActiveTools(names) {
 			this.activeTools = names;
 		},
+		on() {
+			// no-op：session_start handler（透传 channel 注册），测试不覆盖
+		},
 	};
 
 	factory(pi as never);

package/src/__tests__/e2e.test.ts

@@ -75,9 +75,9 @@ describe("E2E-3: single question + allowComment — Enter in comment skips", ()
 		expect(details.cancelled).toBe(false);
 		// 不含 " — " 分隔符
 		expect(details.answers["Which DB?"]).toBe("Postgres");
-			expect(details.answers["Which DB?"]).not.toContain("—");
-		});
+		expect(details.answers["Which DB?"]).not.toContain("—");
 	});
+});
 
 // ── E2E-4: 多问题提交 — 逐题选择后 Submit tab 提交（S-11）──────
 describe("E2E-4: multi-question submit — answer each then Submit tab", () => {

package/src/__tests__/index.test.ts

@@ -44,6 +44,9 @@ interface MockPi {
 	getAllTools(): { name: string }[];
 	activeTools?: string[] | null;
 	setActiveTools(names: string[]): void;
+	// session_start handler：factory 注册 ask_user channel handler 时调用（透传功能）。
+	// 测试不验证透传，提供空 on 让 factory 不抛错。
+	on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 
 /** Runs the factory, returns the captured registered tool. */
@@ -58,6 +61,10 @@ const getTool = (overrides: Partial<MockPi> = {}): RegisteredTool => {
 		setActiveTools(names) {
 			this.activeTools = names;
 		},
+		on() {
+			// no-op：session_start handler 注册透传 channel（subagent-workflow 可选），
+			// 测试不覆盖透传路径
+		},
 		...overrides,
 	};
 	factory(pi as never);

package/src/__tests__/question-view.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/question-view.test.ts
 import { describe, expect, it } from "vitest";
 
-import { getSplitPaneWidths, renderQuestionView, type RenderContext } from "../question-view";
+import { getSplitPaneWidths, type RenderContext,renderQuestionView } from "../question-view";
 import { createQuestionState, type Question, type QuestionState } from "../types";
 import { stubTheme } from "./fixtures";
 

package/src/__tests__/sdk-contract.test.ts

@@ -10,8 +10,8 @@
 
 import { describe, expect, it } from "vitest";
 
-import { validateInput } from "../validate";
 import askUserExtension from "../index";
+import { validateInput } from "../validate";
 
 describe("ask-user SDK contract", () => {
 	it("default export is a function accepting ExtensionAPI", () => {

package/src/channel-handler.ts

@@ -0,0 +1,215 @@
+// src/channel-handler.ts
+//
+// ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI 渲染。
+//
+// 设计（关键决策）：askUserInteract（@xyz-agent/extension-protocol）只在 RPC 模式可用
+// （内部 isGuiCapable 检查 mode==='rpc'，TUI 下抛错）。所以 handler 按 ctx.mode 分流：
+//   - RPC：转发器——调 askUserInteract(guiCtx, protoQuestions)，复用 select 通道 +
+//     ASK_USER_MARKER 契约，主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，
+//     不循环）。返回 {value: JSON.stringify(answers)} 让子进程 JSON.parse(value) decode。
+//   - TUI：走 ctx.ui.custom + AskUserComponent。三步：(1) protoQuestions → 内部 Question[]，
+//     (2) ctx.ui.custom 渲染拿内部 Result，(3) 内部 Result.answers（key=question 全文，
+//     value="label1, label2 — comment"）→ 重新编码为 proto AskUserAnswers（key=header/question，
+//     单选=value，多选=JSON 数组，Other→__other，comment→__comment），让子进程 decode 一致。
+//
+// handler 收到的 req.channelPayload = {questions: AskUserQuestion[], allowCancel}（proto 格式，
+// 由子进程 askUserInteract 编码、subagent-workflow parseChannel 解析 options[0] JSON 得到）。
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+	type AskUserAnswers,
+	askUserInteract,
+	type AskUserQuestion,
+} from "@xyz-agent/extension-protocol";
+
+import { AskUserComponent } from "./component";
+import { ANSWER_COMMENT_SEPARATOR, type Option, type Question, type Result, type ThemeLike } from "./types";
+
+/**
+ * channel handler 签名——与 subagent-workflow 的 UiChannelRegistry.ChannelHandler 一致
+ *（(req: unknown) => Promise<unknown>）。本文件不静态 import subagent-workflow（它是可选
+ * peerDep，未安装时静态 import 会导致整个 ask-user 加载失败）；注册时通过动态 import 拿
+ * registry，handler 签名用本地等价类型，运行时结构兼容。
+ */
+export type ChannelHandler = (req: unknown) => Promise<unknown>;
+
+/** handler 返回给 subagent-workflow 的 UiResponse 形状（dialog-queue.ts 定义）。
+ *  - {value}: select 的回传值（子进程 JSON.parse(value) 得 answers）
+ *  - {cancelled}: 用户取消 / 子进程 close / handler 抛错 */
+type ChannelResponse = { value: string } | { cancelled: true };
+
+/** handler 收到的 req 形状收窄（ChannelHandler 签名是 unknown，按形状 as 收窄）。
+ *  channelPayload 由 subagent-workflow parseChannel 填充。 */
+interface ChannelRequest {
+	channelPayload?: { questions?: AskUserQuestion[]; allowCancel?: boolean };
+}
+
+/** proto AskUserQuestion → 内部 Question（AskUserComponent 接受内部格式）。
+ *  proto options 可选（无 options=纯自由文本），内部 options 必填——无 options 的 protoQuestion
+ *  这里仍映射出 options（从子进程 ask-user 调用方保证 protoQuestions 总带 options；若缺则返 [] 由调用方判）。 */
+function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[] {
+	return protoQuestions.map((pq: AskUserQuestion): Question => {
+		const opts: Option[] = (pq.options ?? []).map((o: { label: string; description?: string }): Option => ({
+			label: o.label,
+			...(o.description !== undefined ? { description: o.description } : {}),
+		}));
+		return {
+			question: pq.question,
+			...(pq.header !== undefined ? { header: pq.header } : {}),
+			...(pq.context !== undefined ? { context: pq.context } : {}),
+			options: opts,
+			...(pq.multiSelect !== undefined ? { multiSelect: pq.multiSelect } : {}),
+			...(pq.allowComment !== undefined ? { allowComment: pq.allowComment } : {}),
+		};
+	});
+}
+
+/**
+ * 把 TUI 路径产出的内部 Result.answers 重新编码为 proto AskUserAnswers。
+ *
+ * 内部 Result.answers：key = question 全文，value = "label1, label2 — comment"
+ * （Other 自由文本与 selected 标签逗号拼接，comment 用 ANSWER_COMMENT_SEPARATOR 分隔）。
+ *
+ * proto AskUserAnswers 契约（@xyz-agent/extension-protocol）：
+ *   - key = question.header ?? question 全文
+ *   - 单选：value = 选中项 value string
+ *   - 多选：value = JSON.stringify(选中项 value 数组)
+ *   - Other 自由文本：单独 key `${header}__other`
+ *   - comment：单独 key `${header}__comment`
+ *
+ * 解码（无信息丢失）：用 protoQuestion.options 的 label 集合精确匹配 selected；
+ * 不匹配的 token = Other 自由文本；comment 由 ANSWER_COMMENT_SEPARATOR 切出。
+ */
+function encodeTuiResultToProto(
+	protoQuestions: AskUserQuestion[],
+	result: Result,
+): AskUserAnswers {
+	const answers: AskUserAnswers = {};
+	for (const pq of protoQuestions) {
+		const key = pq.header ?? pq.question;
+		const internalText = result.answers[pq.question];
+		if (internalText === undefined) continue; // 该问题未答（protoAnswersToResult 也跳过未答）
+
+		// 已知选项 label 集合（protoQuestion.options 的 label/value 都作候选——value 缺失时用 label）
+		const knownLabels = new Set<string>();
+		for (const o of pq.options ?? []) {
+			knownLabels.add(o.label);
+			if (o.value !== undefined) knownLabels.add(o.value);
+		}
+
+		// 切 body / comment（comment 在 ANSWER_COMMENT_SEPARATOR 之后）
+		const sepIdx = internalText.indexOf(ANSWER_COMMENT_SEPARATOR);
+		const body = sepIdx >= 0 ? internalText.slice(0, sepIdx) : internalText;
+		const comment = sepIdx >= 0
+			? internalText.slice(sepIdx + ANSWER_COMMENT_SEPARATOR.length).trim() || undefined
+			: undefined;
+
+		// body tokens：匹配 knownLabels 的为 selected，其余为 Other 自由文本
+		const tokens = body.split(/[,，]/).map((t: string) => t.trim()).filter((t: string) => t !== "");
+		const selected: string[] = [];
+		const otherTokens: string[] = [];
+		for (const t of tokens) {
+			if (knownLabels.has(t)) {
+				// 回查 proto option 的 value（PR #85 #8）：TUI 渲染用 label，但 RPC 路径
+				// （askUserInteract）回传的是 option.value。value≠label 时若直接 push label，
+				// TUI/RPC 两条路径产出分裂。value 缺失时 fallback label（保持 ask-user 自身
+				// toProtoQuestions 的 value=label 语义，以及历史行为）。
+				const opt = pq.options?.find(o => o.label === t || o.value === t);
+				selected.push(opt?.value ?? t);
+			} else {
+				otherTokens.push(t);
+			}
+		}
+		const otherText = otherTokens.join(", ") || undefined;
+
+		// 主 key：单选 = 首个选中 value；多选 = JSON 数组（即便为空也写入，与 RPC 契约一致）
+		if (pq.multiSelect) {
+			answers[key] = JSON.stringify(selected);
+		} else if (selected.length > 0) {
+			answers[key] = selected[0]!;
+		}
+
+		if (otherText) answers[`${key}__other`] = otherText;
+		if (comment) answers[`${key}__comment`] = comment;
+	}
+	return answers;
+}
+
+/** TUI 路径：ctx.ui.custom + AskUserComponent 渲染，返回 proto answers 或 null（取消）。
+ *
+ *  allowCancel 透传预留（PR #85 #12）：AskUserComponent 构造函数暂未接收 allowCancel，
+ *  Esc 取消始终可用（component.ts 的 escBackOrConfirm / cancel 无条件生效）。待组件升级
+ *  支持禁用 Esc 后，应把 allowCancel 下传给 AskUserComponent 构造函数。当前 allowCancel=false
+ *  时 TUI 与 RPC 路径仍有分裂，但 handler 层已不再吞掉 allowCancel（修复分裂的第一步）。 */
+async function runTuiProtoInteraction(
+	protoQuestions: AskUserQuestion[],
+	ctx: ExtensionContext,
+	allowCancel: boolean,
+): Promise<AskUserAnswers | null> {
+	const questions = protoToInternalQuestions(protoQuestions);
+	// 预留：组件升级后此处改为 new AskUserComponent(questions, tui, theme, done, allowCancel)
+	void allowCancel;
+	const result = await ctx.ui.custom<Result | null>(
+		(tui: unknown, theme: unknown, _kb: unknown, done: (r: Result | null) => void) => {
+			const comp = new AskUserComponent(
+				questions,
+				tui as { requestRender(): void },
+				theme as ThemeLike,
+				done,
+			);
+			return comp;
+		},
+	);
+	if (result === null || result.cancelled) return null;
+	return encodeTuiResultToProto(protoQuestions, result);
+}
+
+/**
+ * 创建 ask_user channel handler。
+ *
+ * @param ctx 主进程 ExtensionContext（session_start 时注入）
+ * @returns ChannelHandler——req.channelPayload = {questions, allowCancel}（proto 格式），
+ *          返回 {value: JSON.stringify(answers)} 或 {cancelled: true}
+ */
+export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandler {
+	return async (req: unknown): Promise<unknown> => {
+		// req 正常是 subagent-workflow 构造的 UiRequest 对象；防御性收窄 null/undefined/
+		// 非 object（handler 抛错会被 dialog-queue 兜底为 {cancelled:true}，但这里直接返回更干净）
+		if (req === null || typeof req !== "object") {
+			return { cancelled: true } satisfies ChannelResponse;
+		}
+		const r = req as ChannelRequest;
+		const payload = r.channelPayload;
+		if (!payload || !Array.isArray(payload.questions) || payload.questions.length === 0) {
+			return { cancelled: true } satisfies ChannelResponse;
+		}
+		const { questions, allowCancel } = payload;
+
+		// 按 ctx.mode 分流（PR #85 #13 / #M6）：rpc 走 askUserInteract（select 通道+sidecar），
+		// 其余（tui/json/print/undefined）走 ctx.ui.custom+AskUserComponent。
+		// 用 ctx.mode === "rpc" 二值判定（与 index.ts execute 的 useRpc 判定一致）；
+		// 三值分类不需要——handler 只关心「rpc 转发」vs「TUI 内部渲染」两条路径。
+		const answers =
+			ctx.mode === "rpc"
+				? await runRpcForward(questions, ctx, allowCancel ?? true)
+				: await runTuiProtoInteraction(questions, ctx, allowCancel ?? true);
+
+		if (answers === null) return { cancelled: true } satisfies ChannelResponse;
+		return { value: JSON.stringify(answers) } satisfies ChannelResponse;
+	};
+}
+
+/** RPC 转发器：主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，不循环）。
+ *  完整复用 askUserInteract 的 encode/decode 契约。 */
+async function runRpcForward(
+	questions: AskUserQuestion[],
+	ctx: ExtensionContext,
+	allowCancel: boolean,
+): Promise<AskUserAnswers | null> {
+	const guiCtx = {
+		mode: ctx.mode,
+		hasUI: ctx.hasUI,
+		ui: { select: ctx.ui.select.bind(ctx.ui) },
+	};
+	return askUserInteract(guiCtx, questions, { allowCancel });
+}

package/src/channel-registry-register.ts

@@ -0,0 +1,108 @@
+// src/channel-registry-register.ts
+//
+// ask-user 侧的 channel handler 握手注册纯函数。
+//
+// 设计动机（PR #85 #M4 修复）：原实现 ask-user 先 session_start 时会自建简化 Map-based
+// registry 占据 canonical 槽位，劫持 subagent-workflow 后续 getOrCreateChannelRegistry 拿到的
+// 实例（subagent-workflow 的 createUiChannelRegistry 才是 canonical——它带排队、dialog 队列
+// 等完整能力）。修复后的握手协议改为「带 version 的 slot」：
+//   - subagent-workflow session_start 时往 slot 写 {version, registry, pending:[]}
+//   - ask-user session_start 时只读 slot，registry 就绪则调 registry.register，未就绪则 push pending
+//   - ask-user **永不**创建 registry 实例，**永不**写 slot.registry
+//
+// 这是 ask-user 侧的注册入口；canonical registry 由 subagent-workflow 创建。本模块永不创建
+// registry 实例——仅往 slot 写 pending 或调 slot.registry.register。
+
+import type { ChannelHandler } from "./channel-handler";
+
+/**
+ * 进程级 channel registry 握手的 globalThis key（Symbol.for 跨模块共享）。
+ *
+ * ⚠️ 必须与 extensions/subagent-workflow/src/execution/channel-registry-access.ts 的字面量
+ * 完全一致——两边用同一字符串确保拿到同一 slot 实例。改名必须两侧同步。
+ */
+export const CHANNEL_HANDSHAKE_KEY = Symbol.for(
+	"@zhushanwen/pi-subagents.channelHandshake",
+);
+
+/** 握手协议版本号。读写 slot 时校验 version !== 1 视为不兼容（warn + 重建 slot）。 */
+const HANDSHAKE_VERSION = 1;
+
+/** channel 名称（ask-user 固定注册 "ask_user"）。 */
+const ASK_USER_CHANNEL = "ask_user";
+
+/**
+ * channel registry 的本地等价接口（与 subagent-workflow UiChannelRegistry 形状一致）。
+ * 本模块不静态 import subagent-workflow（它是可选 peerDep，未安装时静态 import 会致整个
+ * ask-user 加载失败）；运行时结构兼容即可。
+ */
+interface ChannelRegistry {
+	register(channel: string, handler: ChannelHandler): void;
+	resolve(channel: string): ChannelHandler | undefined;
+	list(): string[];
+}
+
+/** pending 队列元素：channel + handler。subagent-workflow flush 时遍历调用 registry.register。 */
+interface PendingEntry {
+	channel: string;
+	handler: ChannelHandler;
+}
+
+/**
+ * globalThis slot 的形状。
+ *
+ * - `version`：握手协议版本（运行时校验，不兼容则丢弃重建）
+ * - `registry`：canonical 实例，**仅 subagent-workflow 创建**；缺失表示 registry 未就绪，
+ *   ask-user 把 handler 入 pending 队列等待 flush
+ * - `pending`：未消费的注册请求（registry 就绪后由 subagent-workflow 一次性 flush）
+ */
+export interface ChannelRegistryHandshake {
+	version: 1;
+	registry?: ChannelRegistry;
+	pending: PendingEntry[];
+}
+
+/** 从 globalThis 读 slot；version !== 1 视为无 slot（返回 undefined）。 */
+function readSlot(): ChannelRegistryHandshake | undefined {
+	const slot = Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as
+		| ChannelRegistryHandshake
+		| undefined;
+	if (slot === undefined) return undefined;
+	if (slot.version !== HANDSHAKE_VERSION) {
+		console.warn(
+			`[ask-user] channel handshake slot version mismatch: expected ${HANDSHAKE_VERSION}, got ${slot.version}; discarding and rebuilding slot`,
+		);
+		return undefined;
+	}
+	return slot;
+}
+
+/** 在 globalThis 上建一个空 slot（仅 pending，无 registry——ask-user 永不建 registry）。 */
+function ensureSlot(): ChannelRegistryHandshake {
+	const slot: ChannelRegistryHandshake = { version: HANDSHAKE_VERSION, pending: [] };
+	Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
+	return slot;
+}
+
+/**
+ * 注册 ask_user channel handler 到 globalThis 握手 slot。
+ *
+ * 行为：
+ *   1. slot 不存在或 version 不兼容 → 建 slot（仅 pending），handler 入 pending；
+ *      **slot.registry 保持 undefined**（M4 核心：ask-user 不建 registry）
+ *   2. slot 存在但 registry 未就绪 → handler 入 pending
+ *   3. slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)
+ *
+ * 多次调用幂等：registry 就绪时 register 同名覆盖；未就绪时 pending.length 增长
+ * （subagent-workflow flush 时一次性消费所有 pending）。
+ *
+ * @param handler ask_user channel handler（createAskUserChannelHandler 产出）
+ */
+export function registerAskUserChannelHandler(handler: ChannelHandler): void {
+	const slot = readSlot() ?? ensureSlot();
+	if (slot.registry !== undefined) {
+		slot.registry.register(ASK_USER_CHANNEL, handler);
+		return;
+	}
+	slot.pending.push({ channel: ASK_USER_CHANNEL, handler });
+}

package/src/index.ts

@@ -11,8 +11,10 @@ import {
 	getAskUserOther,
 } from "@xyz-agent/extension-protocol";
 
-import { AskUserComponent } from "./component";
 import { formatAnswer, parseAnswerParts } from "./answer-format";
+import { createAskUserChannelHandler } from "./channel-handler";
+import { registerAskUserChannelHandler } from "./channel-registry-register";
+import { AskUserComponent } from "./component";
 import {
 	type AskUserDetails,
 	type ErrorDetails,
@@ -208,6 +210,22 @@ async function runRpcInteraction(
 }
 
 export default function (pi: ExtensionAPI): void {
+	// 注册 ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
+	//
+	// 跨扩展握手协议（PR #85 #M4）：通过 globalThis Symbol.for 约定 slot 形状
+	//（CHANNEL_HANDSHAKE_KEY，与 subagent-workflow/src/execution/channel-registry-access.ts
+	// 用同一字符串 key），不依赖 dynamic import npm 包名（两个扩展都通过
+	// ~/.pi/agent/extensions/ symlink 加载，互相之间无法用 npm 包名 import）。
+	//
+	// 握手流程（registerAskUserChannelHandler 内部完成）：
+	//   1. 读 slot；不存在或 version 不兼容 → 建 slot（仅 pending，**永不建 registry**）
+	//   2. slot.registry 就绪（subagent-workflow 先到）→ 直接调 registry.register
+	//   3. slot.registry 未就绪 → handler 入 pending，等 subagent-workflow flush
+	// ask-user 永不创建 registry 实例——canonical registry 仅 subagent-workflow 创建。
+	pi.on("session_start", (_event, ctx) => {
+		registerAskUserChannelHandler(createAskUserChannelHandler(ctx));
+	});
+
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",