@henryqw/pi-ask-question 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# `@henryqw/pi-ask-question`
+
+Pi extension exposing `ask_question`, an interactive tool for asking user one question. Tool shows one to three supplied options, marks first as recommended, then adds `Something else.` for custom answer.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-ask-question
+```
+
+Tool accepts:
+
+```json
+{
+  "question": "Which database should we use?",
+  "options": [
+    { "label": "PostgreSQL", "description": "Shared server database" },
+    { "label": "SQLite", "description": "Local, embedded storage" },
+    { "label": "File", "description": "Plain file storage" }
+  ]
+}
+```
+
+Supply one to three meaningful options in preference order; UI adds `(Recommended)` to first label. Number keys select options directly. Empty questions, blank or duplicate labels, empty lists, more than three options, and non-interactive sessions return error result. Aborting tool call closes pending question.
+
+Remove with:
+
+```bash
+pi remove npm:@henryqw/pi-ask-question
+```
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run pack:check
+```
+
+Run manual model/TUI check outside CI:
+
+```bash
+npm run test:manual
+```
+
+Pass criteria:
+
+1. Agent calls `ask_question` instead of asking in plain text.
+2. UI shows one to three useful choices, first marked `(Recommended)`, plus `Something else.`.
+3. Option descriptions explain tradeoffs without repeating labels.
+4. Number key selects matching option; custom choice accepts typed answer; `Esc` cancels.

package/extensions/ask-question.ts

@@ -0,0 +1,249 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	Editor,
+	type EditorTheme,
+	Key,
+	matchesKey,
+	Text,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+interface QuestionOption {
+	label: string;
+	description?: string;
+}
+
+type DisplayOption = QuestionOption & { isOther?: boolean };
+
+const NUMBER_KEYS = ["1", "2", "3", "4"] as const;
+
+interface QuestionDetails {
+	question: string;
+	options: string[];
+	answer: string | null;
+	wasCustom?: boolean;
+	selectedIndex?: number;
+}
+
+const QuestionOptionSchema = Type.Object({
+	label: Type.String({ description: "Display label for the option", minLength: 1 }),
+	description: Type.Optional(Type.String({ description: "Optional description shown below label", minLength: 1 })),
+});
+
+const AskQuestionParams = Type.Object({
+	question: Type.String({ description: "Question to ask user", minLength: 1 }),
+	options: Type.Array(QuestionOptionSchema, {
+		description: "One to three meaningful options, ordered with recommended option first",
+		minItems: 1,
+		maxItems: 3,
+	}),
+});
+
+export default function askQuestionExtension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_question",
+		label: "Ask Question",
+		description: "Ask user one question with up to three options or a custom answer. First option is shown as recommended. Use when user input is needed to proceed.",
+		promptSnippet: "Ask user one interactive question with up to three options or a custom answer",
+		promptGuidelines: [
+			"Use ask_question instead of plain assistant text whenever user input is needed to proceed.",
+			"Give ask_question one to three concise, meaningful options without inventing filler, put recommended option first, and omit '(Recommended)' from its label.",
+			"Give ask_question option descriptions only when they explain meaningful tradeoffs; never repeat option labels.",
+		],
+		parameters: AskQuestionParams,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const question = params.question.trim();
+			const suppliedOptions = params.options.map((option) => ({
+				label: option.label.trim(),
+				...(option.description === undefined ? {} : { description: option.description.trim() }),
+			}));
+			const options = suppliedOptions.map((option) => option.label);
+			if (ctx.mode !== "tui") {
+				return {
+					content: [{ type: "text" as const, text: "Error: UI not available (running in non-interactive mode)" }],
+					details: { question, options, answer: null } satisfies QuestionDetails,
+				};
+			}
+			let validationError: string | undefined;
+			if (suppliedOptions.length < 1 || suppliedOptions.length > 3) validationError = "1 to 3 options required";
+			else if (!question) validationError = "Question must not be blank";
+			else if (suppliedOptions.some((option) => !option.label)) validationError = "Option labels must not be blank";
+			else if (new Set(options.map((option) => option.toLowerCase())).size !== options.length) validationError = "Option labels must be unique";
+			if (validationError) {
+				return {
+					content: [{ type: "text" as const, text: `Error: ${validationError}` }],
+					details: { question, options, answer: null } satisfies QuestionDetails,
+				};
+			}
+
+			const allOptions: DisplayOption[] = [...suppliedOptions, { label: "Something else.", isOther: true }];
+			const result = await ctx.ui.custom<{ answer: string; wasCustom: boolean; index?: number } | null>(
+				(tui, theme, _kb, done) => {
+					let optionIndex = 0;
+					let editMode = false;
+					let cachedLines: string[] | undefined;
+					const editorTheme: EditorTheme = {
+						borderColor: (text) => theme.fg("accent", text),
+						selectList: {
+							selectedPrefix: (text) => theme.fg("accent", text),
+							selectedText: (text) => theme.fg("accent", text),
+							description: (text) => theme.fg("muted", text),
+							scrollInfo: (text) => theme.fg("dim", text),
+							noMatch: (text) => theme.fg("warning", text),
+						},
+					};
+					const editor = new Editor(tui, editorTheme);
+
+					function refresh(): void {
+						cachedLines = undefined;
+						tui.requestRender();
+					}
+
+					editor.onSubmit = (value) => {
+						const answer = value.trim();
+						if (answer) done({ answer, wasCustom: true });
+						else {
+							editMode = false;
+							editor.setText("");
+							refresh();
+						}
+					};
+
+					function selectOption(): void {
+						const selected = allOptions[optionIndex]!;
+						if (selected.isOther) editMode = true;
+						else done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 });
+					}
+
+					function handleInput(data: string): void {
+						if (editMode) {
+							if (matchesKey(data, Key.escape)) {
+								editMode = false;
+								editor.setText("");
+								refresh();
+								return;
+							}
+							editor.handleInput(data);
+							refresh();
+							return;
+						}
+
+						const numberIndex = NUMBER_KEYS.findIndex((key, index) => index < allOptions.length && matchesKey(data, key));
+						if (numberIndex >= 0) {
+							optionIndex = numberIndex;
+							selectOption();
+						} else if (matchesKey(data, Key.up)) optionIndex = Math.max(0, optionIndex - 1);
+						else if (matchesKey(data, Key.down)) optionIndex = Math.min(allOptions.length - 1, optionIndex + 1);
+						else if (matchesKey(data, Key.enter)) selectOption();
+						else if (matchesKey(data, Key.escape)) {
+							done(null);
+							return;
+						} else return;
+						refresh();
+					}
+
+					function render(width: number): string[] {
+						if (cachedLines) return cachedLines;
+						const lines: string[] = [];
+						const renderWidth = Math.max(1, width);
+						const addWrapped = (text: string): void => { lines.push(...wrapTextWithAnsi(text, renderWidth)); };
+						const addWrappedWithPrefix = (prefix: string, text: string): void => {
+							const prefixWidth = visibleWidth(prefix);
+							if (prefixWidth >= renderWidth) {
+								addWrapped(prefix + text);
+								return;
+							}
+							const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
+							const continuationPrefix = " ".repeat(prefixWidth);
+							for (let index = 0; index < wrapped.length; index++) {
+								lines.push(`${index === 0 ? prefix : continuationPrefix}${wrapped[index]}`);
+							}
+						};
+
+						lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+						addWrappedWithPrefix(" ", theme.fg("text", question));
+						lines.push("");
+						for (let index = 0; index < allOptions.length; index++) {
+							const option = allOptions[index]!;
+							const selected = index === optionIndex;
+							const prefix = selected ? theme.fg("accent", "> ") : "  ";
+							const label = `${index + 1}. ${option.label}${index === 0 ? " (Recommended)" : ""}${option.isOther && editMode ? " ✎" : ""}`;
+							addWrappedWithPrefix(prefix, theme.fg(selected || (option.isOther && editMode) ? "accent" : "text", label));
+							if (option.description) addWrappedWithPrefix("     ", theme.fg("muted", option.description));
+						}
+						if (editMode) {
+							lines.push("");
+							addWrappedWithPrefix(" ", theme.fg("muted", "Your answer:"));
+							for (const line of editor.render(Math.max(1, renderWidth - 2))) lines.push(` ${line}`);
+						}
+						lines.push("");
+						addWrappedWithPrefix(" ", theme.fg("dim", editMode ? "Enter to submit • Esc to go back" : `↑↓ navigate • 1–${allOptions.length} or Enter to select • Esc to cancel`));
+						lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+						cachedLines = lines;
+						return lines;
+					}
+
+					const abort = (): void => done(null);
+					if (signal?.aborted) abort();
+					else signal?.addEventListener("abort", abort, { once: true });
+
+					return {
+						render,
+						invalidate: () => { cachedLines = undefined; },
+						handleInput,
+						dispose: () => signal?.removeEventListener("abort", abort),
+					};
+				},
+			);
+
+			if (!result) {
+				return {
+					content: [{ type: "text" as const, text: "User cancelled question" }],
+					details: { question, options, answer: null } satisfies QuestionDetails,
+				};
+			}
+			return {
+				content: [{
+					type: "text" as const,
+					text: result.wasCustom ? `User wrote: ${result.answer}` : `User selected: ${result.index}. ${result.answer}`,
+				}],
+				details: {
+					question,
+					options,
+					answer: result.answer,
+					wasCustom: result.wasCustom,
+					selectedIndex: result.index,
+				} satisfies QuestionDetails,
+			};
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("ask_question ")) + theme.fg("muted", args.question);
+			const options = Array.isArray(args.options) ? args.options : [];
+			if (options.length) {
+				const labels = options.map((option: QuestionOption) => option.label);
+				const numbered = [...labels, "Something else."].map((option, index) => `${index + 1}. ${option}${index === 0 ? " (Recommended)" : ""}`);
+				text += `\n${theme.fg("dim", `  Options: ${numbered.join(", ")}`)}`;
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as QuestionDetails | undefined;
+			if (!details) {
+				const content = result.content[0];
+				return new Text(content?.type === "text" ? content.text : "", 0, 0);
+			}
+			if (details.answer === null) return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			if (details.wasCustom) {
+				return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "(wrote) ") + theme.fg("accent", details.answer), 0, 0);
+			}
+			const display = details.selectedIndex ? `${details.selectedIndex}. ${details.answer}` : details.answer;
+			return new Text(theme.fg("success", "✓ ") + theme.fg("accent", display), 0, 0);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@henryqw/pi-ask-question",
+  "version": "0.1.0",
+  "description": "Ask Pi users one interactive question with choices or a custom answer.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "question",
+    "interactive"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "test:manual": "pi --no-extensions -e ./extensions/ask-question.ts --tools ask_question --no-session \"We need storage for a small team app. Before making changes, ask me to choose storage.\"",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/ask-question.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.1",
+    "@earendil-works/pi-tui": ">=0.84.1",
+    "typebox": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-ask-question"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/ask-question.ts"
+    ]
+  }
+}