@zhushanwen/pi-ask-user 7.0.9 → 7.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.0.9",
+  "version": "7.0.11",
   "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",
@@ -26,11 +26,12 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "^0.4.0"
+    "@xyz-agent/extension-protocol": "0.5.0"
   },
   "devDependencies": {
     "@earendil-works/pi-tui": "*",
     "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "fast-check": "^4.9.0",
     "typebox": "*",
     "vitest": "^4.1.8"
@@ -38,15 +39,11 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
-    "typebox": "*",
-    "@zhushanwen/pi-subagent-workflow": "7.4.0"
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {
       "optional": true
-    },
-    "@zhushanwen/pi-subagent-workflow": {
-      "optional": true
     }
   },
   "scripts": {

package/src/__tests__/index.test.ts

@@ -139,102 +139,90 @@ const validSingle = {
 };
 
 // ── I-1 ~ I-4: 参数校验（AC-8/13）──────────────────────
+// W4：错误路径 throw（pi 只对 execute throw 置 isError:true，返回值 isError 被丢弃）
 describe("execute — validation (FR-2 / AC-8 / AC-13)", () => {
-	it("I-1: duplicate question → isError", async () => {
+	it("I-1: duplicate question → throw", async () => {
 		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			{
-				questions: [
-					{ question: "Same", options: [{ label: "A" }, { label: "B" }] },
-					{ question: "Same", options: [{ label: "C" }, { label: "D" }] },
-				],
-			},
-			undefined,
-			undefined,
-			makeCtx(),
-		);
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("Duplicate");
-	});
-
-	it("I-2: duplicate option label → isError", async () => {
-		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			{
-				questions: [
-					{ question: "Q", options: [{ label: "A" }, { label: "A" }] },
-				],
-			},
-			undefined,
-			undefined,
-			makeCtx(),
-		);
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("Duplicate option");
+		await expect(
+			tool.execute(
+				"id",
+				{
+					questions: [
+						{ question: "Same", options: [{ label: "A" }, { label: "B" }] },
+						{ question: "Same", options: [{ label: "C" }, { label: "D" }] },
+					],
+				},
+				undefined,
+				undefined,
+				makeCtx(),
+			),
+		).rejects.toThrow("Duplicate");
 	});
 
-	it("I-3: multi-question missing header → isError", async () => {
+	it("I-2: duplicate option label → throw", async () => {
 		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			{
-				questions: [
-					{ question: "Q1", header: "H1", options: [{ label: "A" }, { label: "B" }] },
-					{ question: "Q2", options: [{ label: "C" }, { label: "D" }] },
-				],
-			},
-			undefined,
-			undefined,
-			makeCtx(),
-		);
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("header");
+		await expect(
+			tool.execute(
+				"id",
+				{
+					questions: [
+						{ question: "Q", options: [{ label: "A" }, { label: "A" }] },
+					],
+				},
+				undefined,
+				undefined,
+				makeCtx(),
+			),
+		).rejects.toThrow("Duplicate option");
 	});
 
-	it("I-4: validation error details.cancelled = true", async () => {
+	it("I-3: multi-question missing header → throw", async () => {
 		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			{ questions: [{ question: "Q", options: [{ label: "A" }, { label: "A" }] }] },
-			undefined,
-			undefined,
-			makeCtx(),
-		);
-		expect(result.details.cancelled).toBe(true);
+		await expect(
+			tool.execute(
+				"id",
+				{
+					questions: [
+						{ question: "Q1", header: "H1", options: [{ label: "A" }, { label: "B" }] },
+						{ question: "Q2", options: [{ label: "C" }, { label: "D" }] },
+					],
+				},
+				undefined,
+				undefined,
+				makeCtx(),
+			),
+		).rejects.toThrow("header");
 	});
 
-	it("I-4b: string options (schema-relaxed) → execute → validateInput catches → isError + Correct hint", async () => {
+	it("I-4b: string options (schema-relaxed) → execute → validateInput catches → throw + Correct hint", async () => {
 		// 端到端证明：schema 放宽（Union([OptionSchema, string])）后 string options
-		// 能穿过 TypeCompiler.Check、抵达 execute → validateInput 友好拦截。
+		// 能穿过 TypeCompiler.Check、抵达 execute → validateInput 友好拦截（W4 后以 throw
+		// 表达，pi catch 后文案进 toolResult content）。
 		// test-coverage reviewer 点名的“execute wiring 未测”缺口。
 		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			{ questions: [{ question: "Q", options: ["A", "B"] }] },
-			undefined,
-			undefined,
-			makeCtx(),
-		);
-		expect(result.isError).toBe(true);
-		expect(result.details.cancelled).toBe(true);
-		expect(result.content[0].text).toContain("not strings");
-		expect(result.content[0].text).toContain("Correct");
+		await expect(
+			tool.execute(
+				"id",
+				{ questions: [{ question: "Q", options: ["A", "B"] }] },
+				undefined,
+				undefined,
+				makeCtx(),
+			),
+		).rejects.toThrow(/not strings[\s\S]*Correct/);
 	});
 });
 
 // ── I-5 ~ I-7: Headless（FR-8 / AC-7）──────────────────
-// 真 headless：hasUI=false 且 ui 上无 select（print 模式），askUserInteract 抛错 → 禁用工具。
+// 真 headless：hasUI=false 且 ui 上无 select（print 模式）→ 禁用工具 + throw（W4）。
 describe("execute — headless (FR-8 / AC-7)", () => {
-	it("I-5: headless (no select) → isError with disabled message", async () => {
+	it("I-5: headless (no select) → throw with disabled message", async () => {
 		const tool = getTool();
-		const result = await tool.execute("id", validSingle, undefined, undefined, makeHeadlessCtx());
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("disabled");
+		await expect(
+			tool.execute("id", validSingle, undefined, undefined, makeHeadlessCtx()),
+		).rejects.toThrow(/disabled/);
 	});
 
-	it("I-6: headless disables ask_user tool via setActiveTools", async () => {
+	it("I-6: headless disables ask_user tool via setActiveTools (收尾先于 throw)", async () => {
 		let captured: string[] | null = null;
 		const tool2 = getTool({
 			getAllTools: () => [{ name: "ask_user" }, { name: "other" }],
@@ -242,17 +230,12 @@ describe("execute — headless (FR-8 / AC-7)", () => {
 				captured = names;
 			},
 		});
-		await tool2.execute("id", validSingle, undefined, undefined, makeHeadlessCtx());
+		await expect(
+			tool2.execute("id", validSingle, undefined, undefined, makeHeadlessCtx()),
+		).rejects.toThrow();
 		expect(captured).not.toContain("ask_user");
 		expect(captured).toContain("other");
 	});
-
-	it("I-7: headless details.cancelled = true", async () => {
-		const tool = getTool();
-		const result = await tool.execute("id", validSingle, undefined, undefined, makeHeadlessCtx());
-		// headless 走 step 2 提前返回：cancelled Result（禁用工具，不进交互分支）
-		expect(result.details.cancelled).toBe(true);
-	});
 });
 
 // ── I-8 ~ I-9: Signal abort（FR-10 / AC-14）────────────
@@ -295,31 +278,20 @@ describe("execute — signal abort (FR-10 / AC-14)", () => {
 });
 
 // ── I-10 ~ I-11: 错误兜底（FR-13 / AC-15）─────────────
+// W4：错误路径 throw（原 return {isError, details.error} 的 details 在 pi catch 后
+// 不再产出——pi createErrorToolResult 只保留 content）
 describe("execute — error fallback (FR-13 / AC-15)", () => {
-	it("I-10: ui.custom throws → isError with 'ask_user failed'", async () => {
-		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			validSingle,
-			undefined,
-			undefined,
-			makeCtx({ customThrows: new Error("boom") }),
-		);
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("ask_user failed");
-		expect(result.content[0].text).toContain("boom");
-	});
-
-	it("I-11: error details contains error message", async () => {
-		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			validSingle,
-			undefined,
-			undefined,
-			makeCtx({ customThrows: new Error("crash") }),
-		);
-		expect(result.details.error).toBe("crash");
+	it("I-10: ui.custom throws → throw with 'ask_user failed'", async () => {
+		const tool = getTool();
+		await expect(
+			tool.execute(
+				"id",
+				validSingle,
+				undefined,
+				undefined,
+				makeCtx({ customThrows: new Error("boom") }),
+			),
+		).rejects.toThrow(/ask_user failed[\s\S]*boom/);
 	});
 });
 
@@ -677,18 +649,17 @@ describe("execute — RPC mode (askUserInteract via select channel)", () => {
 		expect(result.details.cancelled).toBe(true);
 	});
 
-	it("R-6: select throws → isError + disabled (not retriable)", async () => {
+	it("R-6: select throws → throw + disabled message (not retriable; W4)", async () => {
 		const tool = getTool();
-		const result = await tool.execute(
-			"id",
-			validSingle,
-			undefined,
-			undefined,
-			makeCtx({ mode: "rpc", selectThrows: new Error("channel broken") }),
-		);
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("disabled");
-		expect(result.details.error).toBe("channel broken");
+		await expect(
+			tool.execute(
+				"id",
+				validSingle,
+				undefined,
+				undefined,
+				makeCtx({ mode: "rpc", selectThrows: new Error("channel broken") }),
+			),
+		).rejects.toThrow(/channel broken[\s\S]*disabled/);
 	});
 
 	it("R-7: header used as answers key when provided", async () => {

package/src/channel-handler.ts

@@ -122,7 +122,10 @@ async function runTuiProtoInteraction(
 			return comp;
 		},
 	);
-	if (result === null || result.cancelled) return null;
+	// json/print 模式 ctx.ui 是 noOpUIContext，custom 返回 undefined（TUI 返回 Result | null）。
+	// 显式 undefined 守卫：裸 result.cancelled 对 undefined 会抛 TypeError（W4 修复前
+	// 靠 dialog-queue 兜底为 {cancelled:true}，现源头短路，语义等价且不再依赖兜底）。
+	if (result === null || result === undefined || result.cancelled) return null;
 	return encodeTuiResultToProto(protoQuestions, result);
 }
 

package/src/index.ts

@@ -17,7 +17,6 @@ import { answerValueText } from "./submit-view";
 import {
 	type AnswerValue,
 	type AskUserDetails,
-	type ErrorDetails,
 	HEADER_MAX_CHARS,
 	InputSchema,
 	type Option,
@@ -28,10 +27,13 @@ import {
 import { validateInput } from "./validate";
 
 /**
- * execute 的返回形状：复用 SDK AgentToolResult<AskUserDetails>，叠加运行时使用的 isError 标记。
- * SDK 的 AgentToolResult 类型未声明 isError（运行时通过它标记错误），这里显式补齐。
+ * execute 的返回形状：复用 SDK AgentToolResult<AskUserDetails>。
+ * SDK 的 AgentToolResult 类型未声明 isError（pi-agent-core types.d.ts:316-334）——
+ * 因为 pi 契约里返回值不携带错误标记：execute 只有 throw 才被置 isError:true
+ * （agent-loop.js:453-483），返回值里的 isError 字段会被丢弃（W4 修复前曾误用）。
+ * 取消（用户取消 / abort）不是错误，正常返回 cancelled result。
  */
-type ExecuteResult = AgentToolResult<AskUserDetails> & { isError?: boolean };
+type ExecuteResult = AgentToolResult<AskUserDetails>;
 
 /** 禁用 ask_user 工具（headless / RPC 通道不可用时调用，防 LLM 反复重试）。 */
 function disableAskUser(pi: ExtensionAPI): void {
@@ -43,11 +45,10 @@ function disableAskUser(pi: ExtensionAPI): void {
 	);
 }
 
-/** 构造 cancelled 结果（用户取消 / abort / 校验失败共用）。 */
-function cancelledResult(questions: Question[], text: string, isError = false): ExecuteResult {
+/** 构造 cancelled 结果（用户取消 / abort 共用；错误路径已改为 throw，不走此函数）。 */
+function cancelledResult(questions: Question[], text: string): ExecuteResult {
 	return {
 		content: [{ type: "text" as const, text }],
-		isError: isError || undefined,
 		details: { questions, answers: {}, cancelled: true } satisfies Result,
 	};
 }
@@ -268,16 +269,17 @@ Don't:
 			// validateInput 会先拦截 string options 再跑其余校验。通过后 questions 已是干净 Question[]。
 			const validationError = validateInput(questions);
 			if (validationError) {
-				return cancelledResult(questions, `Error: ${validationError}`, true);
+				// 错误路径 throw（W4）：pi 只对 execute throw 置 isError:true，
+				// return {isError:true} 会被 agent-loop 丢弃（错误轮被标成功）。
+				throw new Error(`Error: ${validationError}`);
 			}
 
-			// 2. Headless 检查（spec FR-8）：mode 非 tui 非 rpc = 无交互通道
+			// 2. Headless 检查（spec FR-8）：mode 非 tui 非 rpc = 无交互通道。
+			// 先 disableAskUser 收尾（防 LLM 反复重试），再 throw——pi catch 后文案原样进 toolResult。
 			if (ctx.mode !== "tui" && ctx.mode !== "rpc") {
 				disableAskUser(pi);
-				return cancelledResult(
-					questions,
+				throw new Error(
 					"Error: ask_user requires an interactive session. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.",
-					true,
 				);
 			}
 
@@ -303,18 +305,14 @@ Don't:
 			} catch (err) {
 				// RPC 通道不可用（真 headless / select 缺失）→ 禁用工具（spec FR-8）。
 				// TUI 分支不禁用——custom 抛错通常是组件临时故障，允许 LLM 重试。
+				// 禁用收尾先行，再 throw（W4）：pi catch 后文案原样成为 toolResult content。
 				const message = err instanceof Error ? err.message : String(err);
 				if (useRpc) disableAskUser(pi);
-				return {
-					content: [{
-						type: "text" as const,
-						text: useRpc
-							? `ask_user failed: ${message}. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.`
-							: `ask_user failed: ${message}. Treat as cancelled — do not assume an answer; retry the call with corrected parameters, or proceed with a defensible decision if the user cannot be reached.`,
-					}],
-					isError: true,
-					details: { error: message } satisfies ErrorDetails,
-				};
+				throw new Error(
+					useRpc
+						? `ask_user failed: ${message}. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.`
+						: `ask_user failed: ${message}. Treat as cancelled — do not assume an answer; retry the call with corrected parameters, or proceed with a defensible decision if the user cannot be reached.`,
+				);
 			}
 
 			// 5. 取消（null / cancelled）