@zhushanwen/pi-ask-user 0.0.3 → 0.1.0

package/src/__tests__/component.test.ts

@@ -288,7 +288,7 @@ describe("AskUserComponent — Other free-text editor", () => {
 		c.handleInput(ENTER);
 		const lines = c.render(60);
 		// freeform 模式：光标行（█）出现，editor 已在 Other 行原地渲染
-		expect(lines.some((l) => l.includes("█"))).toBe(true);
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(true);
 		// 不再独立 "Your answer" 提示块
 		expect(lines.some((l) => l.includes("Your answer"))).toBe(false);
 	});
@@ -300,7 +300,7 @@ describe("AskUserComponent — Other free-text editor", () => {
 		c.handleInput(TAB);
 		const lines = c.render(60);
 		// Tab 不再打开 Other 编辑器（仅 Enter）；单问题下 Tab 是 no-op
-		expect(lines.some((l) => l.includes("█"))).toBe(false);
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
 	});
 
 	it("C-27: editor accepts printable characters", () => {
@@ -334,7 +334,7 @@ describe("AskUserComponent — Other free-text editor", () => {
 		c.handleInput(ESC);
 		const lines = c.render(60);
 		// Back in options mode — no cursor block (freeform inactive)
-		expect(lines.some((l) => l.includes("█"))).toBe(false);
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
 	});
 
 	it("C-29: editor Enter with text saves and submits (single)", () => {
@@ -358,7 +358,7 @@ describe("AskUserComponent — Other free-text editor", () => {
 		expect(result.val).toBeUndefined();
 		// Back in options mode — no cursor block (freeform inactive)
 		const lines = c.render(60);
-		expect(lines.some((l) => l.includes("█"))).toBe(false);
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
 	});
 });
 
@@ -374,7 +374,7 @@ describe("AskUserComponent — multi-char paste in editor", () => {
 		c.handleInput(ENTER); // 打开 freeform 编辑器
 		c.handleInput("hello world"); // 一次粘贴多字符
 		const lines = c.render(60);
-		const editorLine = lines.find((l) => l.includes("█"));
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
 		expect(editorLine).toBeDefined();
 		// 完整文本保留（非仅首字符 "h"）
 		expect(editorLine).toContain("hello world");
@@ -388,7 +388,7 @@ describe("AskUserComponent — multi-char paste in editor", () => {
 		c.handleInput(ENTER);
 		c.handleInput("fix the 🐛 bug");
 		const lines = c.render(60);
-		const editorLine = lines.find((l) => l.includes("█"));
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
 		expect(editorLine).toBeDefined();
 		// emoji 完整保留，不丢失
 		expect(editorLine).toContain("fix the 🐛 bug");
@@ -403,7 +403,7 @@ describe("AskUserComponent — multi-char paste in editor", () => {
 		c.handleInput(ENTER);
 		c.handleInput("ab\tcd");
 		const lines = c.render(60);
-		const editorLine = lines.find((l) => l.includes("█"));
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
 		expect(editorLine).toBeDefined();
 		// 可打印字符保留，控制字符 \t 被过滤
 		expect(editorLine).toContain("abcd");
@@ -422,7 +422,7 @@ describe("AskUserComponent — multi-char paste in editor", () => {
 		expect(result.val).toBeUndefined();
 		expect(after).toEqual(before);
 		// 编辑器仍在（光标在），editorText 仍为空
-		expect(after.some((l) => l.includes("█"))).toBe(true);
+		expect(after.some((l) => l.includes("\x1b[7m"))).toBe(true);
 	});
 
 	it("C-PASTE-5: single printable char still works (backward-compat)", () => {
@@ -433,10 +433,43 @@ describe("AskUserComponent — multi-char paste in editor", () => {
 		c.handleInput(ENTER);
 		c.handleInput("x"); // 单字符
 		const lines = c.render(60);
-		const editorLine = lines.find((l) => l.includes("█"));
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
 		expect(editorLine).toBeDefined();
 		expect(editorLine).toContain("x");
 	});
+
+	it("C-PASTE-6: bracketed paste 序列被剥离，不残留 [200~/[201~", () => {
+		// 回归：启用 bracketed paste mode 的终端粘贴时会把内容包裹在
+		// \x1b[200~ ... \x1b[201~ 中。ESC 被守卫过滤，但 [200~/[201~ 可见字符
+		// 会残留。修复：handleEditorInput 先 replace 剥离这两个序列。
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER); // 打开 freeform
+		c.handleInput("\x1b[200~hello\x1b[201~");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toBeDefined();
+		expect(editorLine).toContain("hello");
+		expect(editorLine).not.toContain("[200~");
+		expect(editorLine).not.toContain("[201~");
+	});
+
+	it("C-PASTE-7: bracketed paste 跨 chunk 抵达时每个 chunk 独立剥离", () => {
+		// 边界：粘贴内容分多个 data chunk 抵达，每个 chunk 各自带始/末标记。
+		// 简单 replace 在此场景仍有效（每个 chunk 独立剥离自己的标记）。
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		c.handleInput("\x1b[200~foo ");
+		c.handleInput(" bar\x1b[201~");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("foo  bar");
+		expect(editorLine).not.toContain("[200~");
+		expect(editorLine).not.toContain("[201~");
+	});
 });
 
 // ── 5f. 评论流程（FR-4.6 / FR-11 / AC-6/12/17）─────────
@@ -559,6 +592,29 @@ describe("AskUserComponent — re-entry guard", () => {
 		c.handleInput(ENTER); // ignored
 		expect(result.val).toBeNull();
 	});
+
+	// FR-12 竞态：signal abort 可能在用户已 submit 后才触发，此时 cancel() 必须是
+	// no-op，避免二次调 done（用户已拿到 submit 结果，不应被 abort 覆盖为 null）。
+	it("C-FR12 (FR-12): cancel() after submit does not re-invoke done", () => {
+		const { c, result } = make([singleQ]);
+		c.handleInput(ENTER); // submit → done(result), _resolved=true
+		expect(result.val).toBeDefined();
+		expect(result.val!.cancelled).toBe(false);
+		const submitVal = result.val;
+		// 模拟 signal abort 在 submit 后触发 → cancel() 应被 _resolved 守卫拦截
+		c.cancel();
+		expect(result.val).toBe(submitVal); // 不变 —— done 未被二次调用
+	});
+
+	it("C-FR12b (FR-12): cancel() after cancel does not re-invoke done", () => {
+		const { c, result } = make([singleQ]);
+		c.handleInput(ESC); // overlay
+		c.handleInput(ESC); // cancel → done(null), _resolved=true
+		expect(result.val).toBeNull();
+		// 再次 cancel（模拟 abort 触发）应 no-op
+		c.cancel();
+		expect(result.val).toBeNull(); // 仍为 null，未触发异常
+	});
 });
 
 // ── 5h. 渲染缓存 ───────────────────────────────────────
@@ -765,7 +821,7 @@ describe("AskUserComponent — new behavior (post-refactor)", () => {
 		// 独立 "Your answer" 提示行已消失
 		expect(lines.some((l) => l.includes("Your answer"))).toBe(false);
 		// freeform cursor 出现
-		expect(lines.some((l) => l.includes("█"))).toBe(true);
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(true);
 		// 依然能看见 "Auth" "Search"（普通选项不变）
 		expect(lines.some((l) => l.includes("Auth"))).toBe(true);
 		expect(lines.some((l) => l.includes("Search"))).toBe(true);
@@ -859,4 +915,19 @@ describe("AskUserComponent — new behavior (post-refactor)", () => {
 		c.handleInput(ENTER);
 		expect(result.val).toBeUndefined();
 	});
+
+	it("C-TAB-NOLEAK: Tab in options mode with single question is no-op", () => {
+		const c = new AskUserComponent(
+			[{ question: "Pick one", options: [{ label: "A" }, { label: "B" }] }],
+			mockTui,
+			stubTheme,
+			() => {},
+		);
+		c.handleInput(DOWN);
+		c.handleInput(TAB);
+		// 不应 crash，选项仍可见
+		const lines = c.render(60);
+		expect(lines.some((l: string) => l.includes("A"))).toBe(true);
+		expect(lines.some((l: string) => l.includes("B"))).toBe(true);
+	});
 });

package/src/__tests__/fixtures.ts

@@ -1,6 +1,7 @@
 // src/__tests__/fixtures.ts
 // Shared test fixtures — stub theme, mock TUI, sample questions, key sequences.
-import type { Question, ThemeLike } from "../types";
+import { AskUserComponent } from "../component";
+import type { Question, Result, ThemeLike } from "../types";
 
 // ── Stub theme (passthrough — no ANSI codes, plain text) ──
 export const stubTheme: ThemeLike = {
@@ -14,7 +15,6 @@ export const mockTui = { requestRender: (): void => {} };
 
 // ── Key sequences (real terminal escape codes that matchesKey recognizes) ──
 export const ENTER = "\r";
-export const SPACE = " ";
 export const ESC = "\x1b";
 export const UP = "\x1b[A";
 export const DOWN = "\x1b[B";
@@ -22,6 +22,14 @@ export const RIGHT = "\x1b[C";
 export const LEFT = "\x1b[D";
 export const TAB = "\t";
 export const BKSP = "\x7f";
+export const BACKSPACE = "\x7f";
+export const HOME = "\x1b[H";
+export const END = "\x1b[F";
+export const INSERT = "\x1b[2~";
+export const PGUP = "\x1b[5~";
+export const PGDN = "\x1b[6~";
+export const F1 = "\x1bOP";
+export const DELETE = "\x1b[3~";
 
 // ── Sample questions ──
 export const singleQ: Question = {
@@ -66,3 +74,49 @@ export const multiQWithComment: Question[] = [
 	{ question: "Q1", header: "First", allowComment: true, options: [{ label: "A" }, { label: "B" }] },
 	{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
 ];
+
+// ── Aliases (PAGE_UP/PAGE_DOWN for W1 tests, PGUP/PGDN for W3 tests) ──
+export const PAGE_UP = "\x1b[5~";
+export const PAGE_DOWN = "\x1b[6~";
+
+// ── Modifier key sequences (ctrl/alt/shift/super + arrow/special) ──
+// CSI u encoding (Kitty/modifyOtherKeys mode 2): ESC [ <code> ; <mod> ~
+// mod = 1 + bitmask: shift=1, alt=2, ctrl=4, super=8
+export const CTRL_UP = "\x1b[1;5A";
+export const CTRL_DOWN = "\x1b[1;5B";
+export const CTRL_LEFT = "\x1b[1;5D";
+export const CTRL_RIGHT = "\x1b[1;5C";
+export const ALT_UP = "\x1b[1;3A";
+export const ALT_DOWN = "\x1b[1;3B";
+export const ALT_LEFT = "\x1b[1;3D";
+export const ALT_RIGHT = "\x1b[1;3C";
+export const SHIFT_UP = "\x1b[1;2A";
+export const SHIFT_DOWN = "\x1b[1;2B";
+export const SHIFT_LEFT = "\x1b[1;2D";
+export const SHIFT_RIGHT = "\x1b[1;2C";
+export const SUPER_UP = "\x1b[1;9A";
+export const SUPER_DOWN = "\x1b[1;9B";
+export const SUPER_LEFT = "\x1b[1;9D";
+export const SUPER_RIGHT = "\x1b[1;9C";
+export const CTRL_SHIFT_UP = "\x1b[1;6A";
+export const CTRL_SHIFT_DOWN = "\x1b[1;6B";
+
+// ── Unknown control sequences (terminal spontaneous, parseKey returns undefined) ──
+export const OSC_BEL = "\x1b]11;rgb:aa/bb/cc\x07"; // OSC, BEL 终止
+export const OSC_ST = "\x1b]11;rgb:aa/bb/cc\x1b\\"; // OSC, ST (ESC\\) 终止
+export const DA1 = "\x1b[?6c"; // DA1 响应
+export const DA2 = "\x1b[>0c"; // DA2 响应
+export const DCS = "\x1bP>|tmux 3.4\x1b\\"; // DCS XTVersion 响应
+export const APC = "\x1b_Gi=31\x1b\\"; // APC Kitty graphics 响应
+export const UNKNOWN_CSI = "\x1b[99~"; // 未知 CSI
+export const UNKNOWN_SS3 = "\x1bOZ"; // 未知 SS3
+
+// ── Component helpers ──
+
+/** 创建默认单问题组件，返回 { c, result } */
+export function make(questions?: Question[]): { c: AskUserComponent; result: { val: Result | null | undefined } } {
+	const qs = questions ?? [{ question: "Pick one", options: [{ label: "A" }, { label: "B" }] }];
+	const result = { val: undefined as Result | null | undefined };
+	const c = new AskUserComponent(qs, mockTui, stubTheme, (r: Result | null) => { result.val = r; });
+	return { c, result };
+}

package/src/__tests__/index.test.ts

@@ -208,7 +208,9 @@ describe("execute — signal abort (FR-10 / AC-14)", () => {
 		const ctx = makeCtx();
 		ctx.signal = controller.signal;
 		const result = await tool.execute("id", validSingle, controller.signal, undefined, ctx);
-		expect(result.content[0].text).toContain("cancelled");
+		// step3 是 agent abort（goal 取消/compact/session 切换），文案应明确告知 abort，
+		// 区别于 step5 的用户取消（A5）
+		expect(result.content[0].text).toContain("abort");
 		expect(result.details.cancelled).toBe(true);
 	});
 
@@ -477,3 +479,24 @@ describe("factory registration (FR-1)", () => {
 		expect(typeof tool.renderResult).toBe("function");
 	});
 });
+
+// ── FR-3: inline 渲染（不传 overlay）───────────────────────
+describe("execute — inline render (FR-3)", () => {
+	it("I-FR3: ui.custom called WITHOUT overlay options (inline, not modal)", async () => {
+		const tool = getTool();
+		let customArgCount = -1;
+		const ctx = {
+			hasUI: true,
+			signal: undefined as AbortSignal | undefined,
+			ui: {
+				custom: async (...args: unknown[]): Promise<null> => {
+					customArgCount = args.length;
+					return null; // cancelled — simplest resolve
+				},
+			},
+		};
+		await tool.execute("id", validSingle, undefined, undefined, ctx);
+		// FR-3: execute 调用 ui.custom 只传 factory（1 个参数），不传 overlay options
+		expect(customArgCount).toBe(1);
+	});
+});

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

@@ -2,13 +2,8 @@
 import { describe, expect, it } from "vitest";
 
 import { getSplitPaneWidths, renderQuestionView } from "../question-view";
-import { createQuestionState, type Question, type QuestionState, type ThemeLike } from "../types";
-
-const stubTheme: ThemeLike = {
-	fg: (_t: string, s: string) => s,
-	bg: (_t: string, s: string) => s,
-	bold: (s: string) => s,
-};
+import { createQuestionState, type Question, type QuestionState } from "../types";
+import { stubTheme } from "./fixtures";
 
 const singleQ: Question = {
 	question: "Which database?",
@@ -148,9 +143,10 @@ describe("renderQuestionView — Other editor mode", () => {
 			"my draft",
 		);
 		const t = text(lines);
-		// Other 行原地变 [ ] <input>█（freeform 模式不依赖 buildEditorBlock 独立编辑块）
-		expect(t).toContain("my draft");
-		expect(t).toContain("█");
+		// cursorIndex=2 → █ 在 "my" 和 " draft" 之间
+		expect(t).toContain("my");
+		expect(t).toContain("draft");
+		expect(t).toContain("\x1b[7m");
 		// 不再独立 "Your answer" 提示行
 		expect(t).not.toContain("Your answer");
 		// 需求4：Other 在 freeform 态也有编号前缀（与其他选项一致）。
@@ -177,8 +173,11 @@ describe("renderQuestionView — Other editor mode", () => {
 		// 多选 box [ ] + 编号 3. 都在编辑行上
 		expect(t).toContain("[ ]");
 		expect(t).toContain("3. ");
-		expect(t).toContain("custom");
-		expect(t).toContain("█");
+		// cursorIndex=2 → cursor 在 "s" 上: "cu\x1b[7ms\x1b[27mtom" — "stom" 被 cursor 打断
+		expect(t).toContain("cu");
+		expect(t).toContain("s");
+		expect(t).toContain("tom");
+		expect(t).toContain("\x1b[7m");
 	});
 
 	it("Q-16: Other with saved free-text shows checkmark + preview", () => {
@@ -227,10 +226,13 @@ describe("renderQuestionView — Other editor mode", () => {
 		expect(xCount).toBe(60);
 		expect(lines.some((l) => l.includes("x"))).toBe(true);
 		// 光标仍在末尾出现
-		expect(t).toContain("█");
-		// 每个含 x 的行都不超过总宽 width（stubTheme 无 ANSI，长度=可见宽）
+		expect(t).toContain("\x1b[7m");
+		// 每个含 x 的行可见宽度不超过 width（strip ANSI 后测量）
 		for (const l of lines) {
-			if (l.includes("x")) expect(l.length).toBeLessThanOrEqual(width);
+			if (l.includes("x")) {
+				const visible = l.replace(/\x1b\[[0-9;]*m/g, "");
+				expect(visible.length).toBeLessThanOrEqual(width);
+			}
 		}
 	});
 
@@ -252,7 +254,7 @@ describe("renderQuestionView — Other editor mode", () => {
 			input,
 		);
 		// 用 █ 定位编辑器行（help 行不含 █），排除 “submit” 含 a 的干扰
-		const editorLines = lines.filter((l) => l.includes("█"));
+		const editorLines = lines.filter((l) => l.includes("\x1b[7m"));
 		expect(editorLines.length).toBe(1);
 		// 全部 60 个 a 都在这一行（未被换行拆分）
 		const aCount = editorLines[0]!.split("").filter((c) => c === "a").length;
@@ -273,7 +275,8 @@ describe("renderQuestionView — Other editor mode", () => {
 		);
 		// 统计含输入内容的行数 = input 渲染行数（应被截到 5 行）
 		// 编号 "3. " 现在是 styled 内容的一部分，首行包裹段 "3." 不含 'y'
-		const inputLines = lines.filter((l) => l.includes("y") || l.includes("3."));
+		// 排除 help 行（含 "Type to add" 的提示行也含 'y'）
+		const inputLines = lines.filter((l) => (l.includes("y") || l.includes("3.")) && !l.includes("Type to add"));
 		expect(inputLines.length).toBe(5);
 		// 最后一行带省略号（表示还有更多，光标已被省略号取代）
 		expect(inputLines[inputLines.length - 1]).toContain("…");
@@ -374,6 +377,99 @@ describe("renderQuestionView — help line", () => {
 	});
 });
 
+// ── Q-32 ~ Q-35: Other 选项对齐（单选/多选 freeform、非 freeform、预览） ──
+describe("renderQuestionView — Other row alignment", () => {
+	it("Q-32: 单选 Other freeform 编辑行编号与普通选项对齐", () => {
+		// 回归：单选 freeform 占位从 \"  \"(2列) 改为 \" \"(1列)，编号列与普通单选对齐
+		const lines = renderQuestionView(
+			singleQ,
+			makeState({ mode: "freeform", cursorIndex: 2 }),
+			stubTheme,
+			60,
+			true,
+			"custom",
+		);
+		const normalLine = lines.find((l) => l.includes("Postgres"))!;
+		const otherLine = lines.find((l) => l.includes("\x1b[7m"))!;
+		// stubTheme 无 ANSI，indexOf 反映可见列位置。普通选项编号 idx === Other 编号 idx
+		expect(normalLine.indexOf("1.")).toBe(otherLine.indexOf("3."));
+	});
+
+	it("Q-33: 多选 Other（无 freeText）编号与普通选项对齐", () => {
+		// 回归：多选 Other 非 freeform 标记从 check(1列) 改为 box(3列)，编号列与普通多选对齐
+		const multiQ: Question = {
+			question: "Which features?",
+			multiSelect: true,
+			options: [{ label: "Auth" }, { label: "Search" }],
+		};
+		const lines = renderQuestionView(
+			multiQ,
+			makeState({ cursorIndex: 2 }),
+			stubTheme,
+			60,
+			true,
+			"",
+		);
+		const normalLine = lines.find((l) => l.includes("Auth"))!;
+		const otherLine = lines.find((l) => l.includes("Other") && l.includes("3."))!;
+		expect(normalLine.indexOf("1.")).toBe(otherLine.indexOf("3."));
+	});
+
+	it("Q-34: 单选 Other freeText 预览缩进对齐到 label 起始列", () => {
+		// 回归：预览 lead 从硬编码 6 列改为动态计算（单选个位 = 7 列）
+		const lines = renderQuestionView(
+			singleQ,
+			makeState({ cursorIndex: 2, freeTextValue: "saved" }),
+			stubTheme,
+			60,
+			true,
+			"",
+		);
+		const labelLine = lines.find((l) => l.includes("Other") && !l.includes('"'))!;
+		const previewLine = lines.find((l) => l.includes('"saved"'))!;
+		expect(labelLine.indexOf("Other")).toBe(previewLine.indexOf('"'));
+	});
+
+	it("Q-35: 多选 Other freeText 预览缩进对齐到 label 起始列", () => {
+		// 回归：多选 marker=3列，预览 lead 应 = 9 列（个位编号），与 label 对齐
+		const multiQ: Question = {
+			question: "Which features?",
+			multiSelect: true,
+			options: [{ label: "Auth" }, { label: "Search" }],
+		};
+		const lines = renderQuestionView(
+			multiQ,
+			makeState({ cursorIndex: 2, freeTextValue: "saved" }),
+			stubTheme,
+			60,
+			true,
+			"",
+		);
+		const labelLine = lines.find((l) => l.includes("Other") && !l.includes('"'))!;
+		const previewLine = lines.find((l) => l.includes('"saved"'))!;
+		expect(labelLine.indexOf("Other")).toBe(previewLine.indexOf('"'));
+	});
+
+	it("Q-35b: 两位数编号时预览缩进随编号宽度自适应", () => {
+		// 10 个选项 + Other = 第 11 项，编号 \"11.\" 占 3 列，预览 lead 应比个位多 1 列
+		const bigQ: Question = {
+			question: "Q",
+			options: Array.from({ length: 10 }, (_, k) => ({ label: `Opt${k + 1}` })),
+		};
+		const lines = renderQuestionView(
+			bigQ,
+			makeState({ cursorIndex: 10, freeTextValue: "x" }),
+			stubTheme,
+			60,
+			true,
+			"",
+		);
+		const labelLine = lines.find((l) => l.includes("Other") && !l.includes('"'))!;
+		const previewLine = lines.find((l) => l.includes('"x"'))!;
+		expect(labelLine.indexOf("Other")).toBe(previewLine.indexOf('"'));
+	});
+});
+
 // ── Q-24 ~ Q-25: 上下文 ─────────────────────────────────
 describe("renderQuestionView — context", () => {
 	it("Q-24: renders context when present", () => {

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

@@ -0,0 +1,111 @@
+// src/__tests__/sdk-contract.test.ts
+//
+// SDK 契约测试：验证 ask-user 扩展的工厂函数和注册接口与 SDK 类型兼容。
+// 核心断言：
+//   1. default export 是接受 ExtensionAPI 的工厂函数
+//   2. registerTool 注册名为 "ask_user" 的 tool，含 description/execute/renderCall/renderResult
+//   3. renderCall 参数数量 >= 1（args）
+//   4. renderResult 参数数量 >= 2（result, options）
+//   5. validateInput 校验逻辑正确
+
+import { describe, expect, it } from "vitest";
+
+import { validateInput } from "../validate";
+import askUserExtension from "../index";
+
+describe("ask-user SDK contract", () => {
+	it("default export is a function accepting ExtensionAPI", () => {
+		expect(typeof askUserExtension).toBe("function");
+		// 工厂函数应接受 1 个参数 (pi: ExtensionAPI)
+		expect(askUserExtension.length).toBe(1);
+	});
+
+	it("registerTool receives a valid ToolDefinition named 'ask_user'", () => {
+		let toolDef: Record<string, unknown> | undefined;
+		const mockPi = {
+			registerTool(def: Record<string, unknown>) {
+				toolDef = def;
+			},
+			on() {},
+			registerCommand() {},
+			getAllTools() { return []; },
+			setActiveTools() {},
+		} as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI;
+
+		askUserExtension(mockPi);
+
+		expect(toolDef).toBeDefined();
+		expect(toolDef!.name).toBe("ask_user");
+		expect(typeof toolDef!.description).toBe("string");
+		expect(typeof toolDef!.execute).toBe("function");
+		expect(typeof toolDef!.renderCall).toBe("function");
+		expect(typeof toolDef!.renderResult).toBe("function");
+		// parameters schema 应存在
+		expect(toolDef!.parameters).toBeDefined();
+	});
+
+	it("renderCall accepts >= 1 args (args, [theme])", () => {
+		let toolDef: Record<string, unknown> | undefined;
+		const mockPi = {
+			registerTool(def: Record<string, unknown>) { toolDef = def; },
+			on() {},
+			registerCommand() {},
+			getAllTools() { return []; },
+			setActiveTools() {},
+		} as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI;
+		askUserExtension(mockPi);
+		expect(toolDef!.renderCall!.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it("renderResult accepts >= 2 args (result, options, [theme])", () => {
+		let toolDef: Record<string, unknown> | undefined;
+		const mockPi = {
+			registerTool(def: Record<string, unknown>) { toolDef = def; },
+			on() {},
+			registerCommand() {},
+			getAllTools() { return []; },
+			setActiveTools() {},
+		} as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI;
+		askUserExtension(mockPi);
+		expect(toolDef!.renderResult!.length).toBeGreaterThanOrEqual(2);
+	});
+
+	it("validateInput accepts empty questions array (schema-level, not runtime)", () => {
+		// validateInput 是运行时校验，不检查数组长度（minItems 由 typebox schema 层强制）
+		expect(validateInput([])).toBeNull();
+	});
+
+	it("validateInput accepts empty options array (schema-level, not runtime)", () => {
+		// 同上：options 长度由 schema 层校验
+		expect(
+			validateInput([
+				{ question: "Q?", options: [] },
+			] as unknown as import("../types").Question[]),
+		).toBeNull();
+	});
+
+	it("validateInput rejects duplicate question text", () => {
+		expect(
+			validateInput([
+				{ question: "Same?", options: [{ label: "A" }, { label: "B" }] },
+				{ question: "Same?", header: "Dup", options: [{ label: "X" }, { label: "Y" }] },
+			] as import("../types").Question[]),
+		).toBeTruthy();
+	});
+
+	it("validateInput rejects empty option label", () => {
+		expect(
+			validateInput([
+				{ question: "Q?", options: [{ label: "" }, { label: "B" }] },
+			] as import("../types").Question[]),
+		).toBeTruthy();
+	});
+
+	it("validateInput accepts a valid single question", () => {
+		expect(
+			validateInput([
+				{ question: "Q1?", options: [{ label: "A" }, { label: "B" }] },
+			] as import("../types").Question[]),
+		).toBeNull();
+	});
+});

package/src/__tests__/validate.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/validate.test.ts
 import { describe, expect, it } from "vitest";
 
-import type { Question } from "../types";
+import { HEADER_MAX_CHARS, type Question } from "../types";
 import { validateInput } from "../validate";
 
 const q = (overrides: Partial<Question> = {}): Question => ({
@@ -121,4 +121,17 @@ describe("validateInput", () => {
 			expect(result).toContain("control characters");
 		}
 	});
+
+	// V-15: header 超过 HEADER_MAX_CHARS(12) 上限被拒绝（A3：补 validate 层校验）
+	it("rejects header exceeding HEADER_MAX_CHARS (12)", () => {
+		const result = validateInput([q({ header: "This header is too long" })]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("Header exceeds");
+		expect(result).toContain(`${HEADER_MAX_CHARS}`);
+	});
+
+	// V-16: header 恰好 12 字符（边界值，合法）
+	it("accepts header at exactly HEADER_MAX_CHARS (12)", () => {
+		expect(validateInput([q({ header: "123456789012" })])).toBeNull();
+	});
 });