pi-ask-user 0.2.1 → 0.4.0

package/README.md

@@ -14,6 +14,11 @@ High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
 - Multi-select option lists
 - Optional freeform responses
 - Context display support
+- Overlay mode — dialog floats over conversation, preserving context
+- Custom TUI rendering for tool calls and results
+- System prompt integration via `promptSnippet` and `promptGuidelines`
+- Optional timeout for auto-dismiss (fallback input mode)
+- Structured `details` on all results for session state reconstruction
 - Graceful fallback when interactive UI is unavailable
 - Bundled `ask-user` skill for mandatory decision-gating in high-stakes or ambiguous tasks
 
@@ -46,6 +51,17 @@ The registered tool name is:
 
 - `ask_user`
 
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `question` | `string` | *required* | The question to ask the user |
+| `context` | `string?` | — | Relevant context summary shown before the question |
+| `options` | `(string \| {title, description?})[]?` | `[]` | Multiple-choice options |
+| `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
+| `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
+| `timeout` | `number?` | — | Auto-dismiss after N ms (applies to fallback input mode) |
+
 ## Example usage shape
 
 ```json
@@ -60,3 +76,32 @@ The registered tool name is:
   "allowFreeform": true
 }
 ```
+
+## Result details
+
+All tool results include a structured `details` object for rendering and session state reconstruction:
+
+```typescript
+interface AskToolDetails {
+  question: string;
+  context?: string;
+  options: QuestionOption[];
+  answer: string | null;
+  cancelled: boolean;
+  wasCustom?: boolean;
+}
+```
+
+## Changelog
+
+### 0.3.0
+
+- Added `promptSnippet` and `promptGuidelines` for better LLM tool selection in the system prompt
+- Added `renderCall` and `renderResult` for custom TUI rendering (compact tool call display, ✓/Cancelled result indicators)
+- Added overlay mode — dialog now floats over the conversation instead of clearing the screen
+- Added `timeout` parameter for auto-dismiss in fallback input mode (when no options are provided)
+- Added structured `details` (`AskToolDetails`) to all result paths for session state reconstruction and branching support
+
+### 0.2.1
+
+- Initial public release

package/index.ts

@@ -15,14 +15,13 @@ import {
 	type EditorTheme,
 	Key,
 	matchesKey,
-	SelectList,
-	type SelectItem,
 	Spacer,
 	Text,
 	type TUI,
 	truncateToWidth,
 	wrapTextWithAnsi,
 } from "@mariozechner/pi-tui";
+import { renderSingleSelectRows } from "./single-select-layout";
 
 interface QuestionOption {
 	title: string;
@@ -37,6 +36,16 @@ interface AskParams {
 	options?: AskOptionInput[];
 	allowMultiple?: boolean;
 	allowFreeform?: boolean;
+	timeout?: number;
+}
+
+interface AskToolDetails {
+	question: string;
+	context?: string;
+	options: QuestionOption[];
+	answer: string | null;
+	cancelled: boolean;
+	wasCustom?: boolean;
 }
 
 function normalizeOptions(options: AskOptionInput[]): QuestionOption[] {
@@ -83,6 +92,9 @@ function createEditorTheme(theme: Theme): EditorTheme {
 
 type AskMode = "select" | "freeform";
 
+const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
+const ASK_OVERLAY_WIDTH = "92%";
+
 class MultiSelectList implements Component {
 	private options: QuestionOption[];
 	private allowFreeform: boolean;
@@ -252,6 +264,135 @@ class MultiSelectList implements Component {
 	}
 }
 
+class WrappedSingleSelectList implements Component {
+	private options: QuestionOption[];
+	private allowFreeform: boolean;
+	private theme: Theme;
+	private selectedIndex = 0;
+	private maxVisibleRows = 12;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	public onCancel?: () => void;
+	public onSubmit?: (result: string) => void;
+	public onEnterFreeform?: () => void;
+
+	constructor(options: QuestionOption[], allowFreeform: boolean, theme: Theme) {
+		this.options = options;
+		this.allowFreeform = allowFreeform;
+		this.theme = theme;
+	}
+
+	setMaxVisibleRows(rows: number): void {
+		const next = Math.max(1, Math.floor(rows));
+		if (next !== this.maxVisibleRows) {
+			this.maxVisibleRows = next;
+			this.invalidate();
+		}
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	private getItemCount(): number {
+		return this.options.length + (this.allowFreeform ? 1 : 0);
+	}
+
+	private isFreeformRow(index: number): boolean {
+		return this.allowFreeform && index === this.options.length;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.onCancel?.();
+			return;
+		}
+
+		const count = this.getItemCount();
+		if (count === 0) {
+			this.onCancel?.();
+			return;
+		}
+
+		if (matchesKey(data, Key.up) || matchesKey(data, Key.shift("tab"))) {
+			this.selectedIndex = this.selectedIndex === 0 ? count - 1 : this.selectedIndex - 1;
+			this.invalidate();
+			return;
+		}
+
+		if (matchesKey(data, Key.down) || matchesKey(data, Key.tab)) {
+			this.selectedIndex = this.selectedIndex === count - 1 ? 0 : this.selectedIndex + 1;
+			this.invalidate();
+			return;
+		}
+
+		const numMatch = data.match(/^[1-9]$/);
+		if (numMatch) {
+			const idx = Number.parseInt(numMatch[0], 10) - 1;
+			if (idx >= 0 && idx < count) {
+				this.selectedIndex = idx;
+				this.invalidate();
+			}
+			return;
+		}
+
+		if (matchesKey(data, Key.enter)) {
+			if (this.isFreeformRow(this.selectedIndex)) {
+				this.onEnterFreeform?.();
+				return;
+			}
+
+			const result = this.options[this.selectedIndex]?.title;
+			if (result) this.onSubmit?.(result);
+			else this.onCancel?.();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) {
+			return this.cachedLines;
+		}
+
+		const count = this.getItemCount();
+		if (count === 0) {
+			this.cachedLines = [this.theme.fg("warning", "No options")];
+			this.cachedWidth = width;
+			return this.cachedLines;
+		}
+
+		const lines = renderSingleSelectRows({
+			options: this.options,
+			selectedIndex: this.selectedIndex,
+			width,
+			allowFreeform: this.allowFreeform,
+			maxRows: this.maxVisibleRows,
+		}).map((line) => {
+			const trimmed = line.trim();
+			let styled = line;
+
+			if (trimmed.startsWith("(")) {
+				styled = this.theme.fg("dim", line);
+			} else if (line.startsWith("      ")) {
+				styled = this.theme.fg("muted", line);
+			} else if (line.startsWith("→")) {
+				styled = this.theme.fg("accent", this.theme.bold(line));
+			} else if (trimmed.startsWith("Type something.")) {
+				styled = this.theme.fg("text", line);
+			} else {
+				styled = this.theme.fg("text", line);
+			}
+
+			return truncateToWidth(styled, width, "");
+		});
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+}
+
 /**
  * Interactive ask UI. Uses a root Container for layout and swaps the center
  * component between SelectList/MultiSelectList and an Editor (freeform mode).
@@ -276,7 +417,7 @@ class AskComponent extends Container {
 	private helpText: Text;
 
 	// Mode components
-	private selectList?: SelectList;
+	private singleSelectList?: WrappedSingleSelectList;
 	private multiSelectList?: MultiSelectList;
 	private editor?: Editor;
 
@@ -354,11 +495,32 @@ class AskComponent extends Container {
 	}
 
 	override render(width: number): string[] {
+		if (this.mode === "select" && !this.allowMultiple) {
+			const overlayMaxHeight = Math.max(12, Math.floor(this.tui.terminal.rows * ASK_OVERLAY_MAX_HEIGHT_RATIO));
+			const staticLines = this.countStaticLines(width);
+			const availableOptionRows = Math.max(4, overlayMaxHeight - staticLines);
+			this.ensureSingleSelectList().setMaxVisibleRows(availableOptionRows);
+		}
+
 		// Defensive: ensure no line exceeds width, otherwise pi-tui will hard-crash.
 		const lines = super.render(width);
 		return lines.map((l) => truncateToWidth(l, width, ""));
 	}
 
+	private countWrappedLines(text: string, width: number): number {
+		return Math.max(1, wrapTextWithAnsi(text, Math.max(10, width - 2)).length);
+	}
+
+	private countStaticLines(width: number): number {
+		const titleLines = 1;
+		const questionLines = this.countWrappedLines(this.question, width);
+		const contextLines = this.context ? 1 + this.countWrappedLines(this.context, width) : 0;
+		const helpLines = 1;
+		const borderLines = 2;
+		const spacerLines = this.context ? 6 : 5;
+		return borderLines + spacerLines + titleLines + questionLines + contextLines + helpLines;
+	}
+
 	private updateStaticText(): void {
 		const theme = this.theme;
 		this.titleText.setText(theme.fg("accent", theme.bold("Question")));
@@ -387,43 +549,16 @@ class AskComponent extends Container {
 		}
 	}
 
-	private buildSingleSelectItems(): SelectItem[] {
-		const items: SelectItem[] = this.options.map((o, idx) => ({
-			value: String(idx),
-			label: o.title,
-			description: o.description,
-		}));
-
-		if (this.allowFreeform) {
-			items.push({
-				value: FREEFORM_VALUE,
-				label: "Type something.",
-				description: "Enter a custom response",
-			});
-		}
+	private ensureSingleSelectList(): WrappedSingleSelectList {
+		if (this.singleSelectList) return this.singleSelectList;
 
-		return items;
-	}
-
-	private ensureSingleSelectList(): SelectList {
-		if (this.selectList) return this.selectList;
-
-		const items = this.buildSingleSelectItems();
-		const selectList = new SelectList(items, Math.min(items.length, 10), createSelectListTheme(this.theme));
-
-		selectList.onSelect = (item) => {
-			if (item.value === FREEFORM_VALUE) {
-				this.showFreeformMode();
-				return;
-			}
-			const idx = Number.parseInt(item.value, 10);
-			const option = this.options[idx];
-			this.onDone(option?.title ?? null);
-		};
-		selectList.onCancel = () => this.onDone(null);
+		const list = new WrappedSingleSelectList(this.options, this.allowFreeform, this.theme);
+		list.onSubmit = (result) => this.onDone(result);
+		list.onCancel = () => this.onDone(null);
+		list.onEnterFreeform = () => this.showFreeformMode();
 
-		this.selectList = selectList;
-		return selectList;
+		this.singleSelectList = list;
+		return list;
 	}
 
 	private ensureMultiSelectList(): MultiSelectList {
@@ -534,6 +669,12 @@ export default function (pi: ExtensionAPI) {
 		label: "Ask User",
 		description:
 			"Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Before calling, gather context with tools (read/exa/ref) and pass a short summary via the context field.",
+		promptSnippet:
+			"Ask the user a question with optional multiple-choice answers to gather information interactively",
+		promptGuidelines: [
+			"Before calling ask_user, gather context with tools (read/exa/ref) and pass a short summary via the context field.",
+			"Use ask_user when the user's intent is ambiguous, when a decision requires explicit user input, or when multiple valid options exist.",
+		],
 		parameters: Type.Object({
 			question: Type.String({ description: "The question to ask the user" }),
 			context: Type.Optional(
@@ -561,11 +702,17 @@ export default function (pi: ExtensionAPI) {
 			allowFreeform: Type.Optional(
 				Type.Boolean({ description: "Add a freeform text option. Default: true" }),
 			),
+			timeout: Type.Optional(
+				Type.Number({ description: "Auto-dismiss after N milliseconds (applies to fallback input mode when no options are provided)" }),
+			),
 		}),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			if (signal?.aborted) {
-				return { content: [{ type: "text", text: "Cancelled" }] };
+				return {
+					content: [{ type: "text", text: "Cancelled" }],
+					details: { question: params.question, options: [], answer: null, cancelled: true } as AskToolDetails,
+				};
 			}
 
 			const {
@@ -574,6 +721,7 @@ export default function (pi: ExtensionAPI) {
 				options: rawOptions = [],
 				allowMultiple = false,
 				allowFreeform = true,
+				timeout,
 			} = params as AskParams;
 			const options = normalizeOptions(rawOptions);
 			const normalizedContext = context?.trim() || undefined;
@@ -590,36 +738,53 @@ export default function (pi: ExtensionAPI) {
 						},
 					],
 					isError: true,
-					details: { question, context: normalizedContext, options },
+					details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
 				};
 			}
 
 			// If no options provided, fall back to freeform input prompt.
 			if (options.length === 0) {
 				const prompt = normalizedContext ? `${question}\n\nContext:\n${normalizedContext}` : question;
-				const answer = await ctx.ui.input(prompt, "Type your answer...");
+				const answer = await ctx.ui.input(prompt, "Type your answer...", timeout ? { timeout } : undefined);
 
 				if (!answer) {
-					return { content: [{ type: "text", text: "User cancelled the question" }] };
+					return {
+						content: [{ type: "text", text: "User cancelled the question" }],
+						details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
+					};
 				}
 
-				return { content: [{ type: "text", text: `User answered: ${answer}` }] };
+				return {
+					content: [{ type: "text", text: `User answered: ${answer}` }],
+					details: { question, context: normalizedContext, options, answer, cancelled: false, wasCustom: true } as AskToolDetails,
+				};
 			}
 
 			let result: string | null;
 			try {
-				result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-					return new AskComponent(
-						question,
-						normalizedContext,
-						options,
-						allowMultiple,
-						allowFreeform,
-						tui,
-						theme,
-						done,
-					);
-				});
+				result = await ctx.ui.custom<string | null>(
+					(tui, theme, _kb, done) => {
+						return new AskComponent(
+							question,
+							normalizedContext,
+							options,
+							allowMultiple,
+							allowFreeform,
+							tui,
+							theme,
+							done,
+						);
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							anchor: "center",
+							width: ASK_OVERLAY_WIDTH,
+							maxHeight: "85%",
+							margin: 1,
+						},
+					},
+				);
 			} catch (error) {
 				const message =
 					error instanceof Error ? `${error.message}\n${error.stack ?? ""}` : String(error);
@@ -631,10 +796,56 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (result === null) {
-				return { content: [{ type: "text", text: "User cancelled the question" }] };
+				return {
+					content: [{ type: "text", text: "User cancelled the question" }],
+					details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
+				};
 			}
 
-			return { content: [{ type: "text", text: `User answered: ${result}` }] };
+			return {
+				content: [{ type: "text", text: `User answered: ${result}` }],
+				details: { question, context: normalizedContext, options, answer: result, cancelled: false } as AskToolDetails,
+			};
+		},
+
+		renderCall(args, theme) {
+			const question = (args.question as string) || "";
+			const rawOptions = Array.isArray(args.options) ? args.options : [];
+			let text = theme.fg("toolTitle", theme.bold("ask_user "));
+			text += theme.fg("muted", question);
+			if (rawOptions.length > 0) {
+				const labels = rawOptions.map((o: unknown) =>
+					typeof o === "string" ? o : (o as QuestionOption)?.title ?? "",
+				);
+				text += "\n" + theme.fg("dim", `  ${rawOptions.length} option(s): ${labels.join(", ")}`);
+			}
+			if (args.allowMultiple) {
+				text += theme.fg("dim", " [multi-select]");
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as (AskToolDetails & { error?: string }) | undefined;
+
+			// Error state
+			if (details?.error) {
+				return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
+			}
+
+			// Cancelled / no details
+			if (!details || details.cancelled) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+
+			// Success
+			const answer = details.answer ?? "";
+			let text = theme.fg("success", "✓ ");
+			if (details.wasCustom) {
+				text += theme.fg("muted", "(wrote) ");
+			}
+			text += theme.fg("accent", answer);
+			return new Text(text, 0, 0);
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Interactive ask_user tool for pi-coding-agent with multi-select and freeform input UI",
   "type": "module",
   "keywords": [
@@ -35,6 +35,7 @@
   },
   "files": [
     "index.ts",
+    "single-select-layout.ts",
     "skills",
     "README.md",
     "LICENSE"

package/single-select-layout.ts

@@ -0,0 +1,172 @@
+export interface QuestionOption {
+	title: string;
+	description?: string;
+}
+
+export interface RenderSingleSelectRowsParams {
+	options: QuestionOption[];
+	selectedIndex: number;
+	width: number;
+	allowFreeform: boolean;
+	maxRows?: number;
+}
+
+function wrapText(text: string, width: number): string[] {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (!normalized) return [""];
+	if (width <= 1) return normalized.split("");
+
+	const words = normalized.split(" ");
+	const lines: string[] = [];
+	let current = "";
+
+	for (const word of words) {
+		if (!current) {
+			if (word.length <= width) {
+				current = word;
+			} else {
+				for (let i = 0; i < word.length; i += width) {
+					lines.push(word.slice(i, i + width));
+				}
+			}
+			continue;
+		}
+
+		const candidate = `${current} ${word}`;
+		if (candidate.length <= width) {
+			current = candidate;
+			continue;
+		}
+
+		lines.push(current);
+		if (word.length <= width) {
+			current = word;
+		} else {
+			for (let i = 0; i < word.length; i += width) {
+				const chunk = word.slice(i, i + width);
+				if (chunk.length === width || i + width < word.length) lines.push(chunk);
+				else current = chunk;
+			}
+			if (!current || current.length === width) current = "";
+		}
+	}
+
+	if (current) lines.push(current);
+	return lines;
+}
+
+function padLine(prefix: string, content: string): string {
+	return `${prefix}${content}`.trimEnd();
+}
+
+interface ItemBlock {
+	itemIndex: number;
+	lines: string[];
+}
+
+function buildItemBlocks(
+	options: QuestionOption[],
+	width: number,
+	allowFreeform: boolean,
+	selectedIndex: number,
+): ItemBlock[] {
+	const normalizedWidth = Math.max(12, width);
+	const freeformLabel = "Type something. — Enter a custom response";
+	const allItems = options.map((option) => ({ type: "option" as const, option }));
+	if (allowFreeform) {
+		allItems.push({ type: "freeform" as const, option: { title: freeformLabel } });
+	}
+
+	return allItems.map((item, itemIndex) => {
+		const pointer = itemIndex === selectedIndex ? "→" : " ";
+		const lines: string[] = [];
+
+		if (item.type === "freeform") {
+			const prefix = `${pointer}   `;
+			const wrapped = wrapText(item.option.title, Math.max(8, normalizedWidth - prefix.length));
+			wrapped.forEach((line, lineIndex) => {
+				lines.push(padLine(lineIndex === 0 ? prefix : " ".repeat(prefix.length), line));
+			});
+			return { itemIndex, lines };
+		}
+
+		const numberPrefix = `${pointer} ${itemIndex + 1}. `;
+		const continuationPrefix = " ".repeat(numberPrefix.length);
+		const titleLines = wrapText(item.option.title, Math.max(8, normalizedWidth - numberPrefix.length));
+		titleLines.forEach((line, lineIndex) => {
+			lines.push(padLine(lineIndex === 0 ? numberPrefix : continuationPrefix, line));
+		});
+
+		if (item.option.description) {
+			const descriptionPrefix = "      ";
+			const descriptionLines = wrapText(
+				item.option.description,
+				Math.max(8, normalizedWidth - descriptionPrefix.length),
+			);
+			descriptionLines.forEach((line) => {
+				lines.push(padLine(descriptionPrefix, line));
+			});
+		}
+
+		return { itemIndex, lines };
+	});
+}
+
+function flatten(blocks: ItemBlock[]): string[] {
+	return blocks.flatMap((block) => block.lines);
+}
+
+export function renderSingleSelectRows({
+	options,
+	selectedIndex,
+	width,
+	allowFreeform,
+	maxRows,
+}: RenderSingleSelectRowsParams): string[] {
+	const itemCount = options.length + (allowFreeform ? 1 : 0);
+	const blocks = buildItemBlocks(options, width, allowFreeform, selectedIndex);
+	const allRows = flatten(blocks);
+
+	if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || allRows.length <= maxRows) {
+		return allRows;
+	}
+
+	const safeMaxRows = Math.max(1, Math.floor(maxRows));
+	const selectedBlock = blocks[selectedIndex] ?? blocks[0];
+	if (!selectedBlock) return [];
+
+	const indicator = `  (${selectedIndex + 1}/${itemCount})`;
+	const availableRows = safeMaxRows > 1 ? safeMaxRows - 1 : 1;
+
+	if (selectedBlock.lines.length >= availableRows) {
+		const visible = selectedBlock.lines.slice(0, availableRows);
+		if (safeMaxRows > 1) visible.push(indicator);
+		return visible.slice(0, safeMaxRows);
+	}
+
+	let start = selectedIndex;
+	let end = selectedIndex + 1;
+	let usedRows = selectedBlock.lines.length;
+
+	while (true) {
+		const nextCanFit = end < blocks.length && usedRows + blocks[end]!.lines.length <= availableRows;
+		if (nextCanFit) {
+			usedRows += blocks[end]!.lines.length;
+			end += 1;
+			continue;
+		}
+
+		const prevCanFit = start > 0 && usedRows + blocks[start - 1]!.lines.length <= availableRows;
+		if (prevCanFit) {
+			start -= 1;
+			usedRows += blocks[start]!.lines.length;
+			continue;
+		}
+
+		break;
+	}
+
+	const visible = flatten(blocks.slice(start, end));
+	visible.push(indicator);
+	return visible.slice(0, safeMaxRows);
+}