1/**
  2 * Ask User Tool
  3 *
  4 * Allows the AI to ask the user a question and wait for their response.
  5 * Supports free-form text input, single-choice suggestions, and
  6 * multi-select checkboxes.
  7 *
  8 * Usage by the AI:
  9 *   ask_user({ question: "Which database should I use?" })
 10 *   ask_user({ question: "How should I handle errors?", suggestions: ["retry", "fail fast", "log and continue"] })
 11 *   ask_user({ question: "Which features?", suggestions: ["auth", "logging", "caching"], multiSelect: true })
 12 */
 13
 14import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 15import { DynamicBorder, getSettingsListTheme } from "@mariozechner/pi-coding-agent";
 16import { Container, type SettingItem, SettingsList, Text } from "@mariozechner/pi-tui";
 17import { Type } from "@sinclair/typebox";
 18
 19export default function (pi: ExtensionAPI) {
 20	pi.registerTool({
 21		name: "AskUserQuestion",
 22		label: "Ask User",
 23		description:
 24			"Ask the user a question and wait for their response. Use when you need clarification, a decision, or user input to proceed. Supports optional suggestions the user can pick from or ignore.",
 25		promptGuidelines: [
 26			"Use ask_user when you need user input, clarification, or a decision before proceeding.",
 27			"Prefer ask_user over guessing when the choice significantly affects the outcome.",
 28			"Keep questions concise and specific. Provide suggestions when there are obvious options.",
 29			"Use multiSelect: true when the user may want to pick more than one option from the suggestions.",
 30		],
 31		parameters: Type.Object({
 32			question: Type.String({ description: "The question to ask the user" }),
 33			suggestions: Type.Optional(
 34				Type.Array(Type.String(), {
 35					description:
 36						"Optional list of suggested answers. User can pick one or type their own response.",
 37				}),
 38			),
 39			multiSelect: Type.Optional(
 40				Type.Boolean({
 41					description:
 42						"If true, user can select multiple suggestions (checkbox-style). Requires suggestions to be provided.",
 43				}),
 44			),
 45		}),
 46
 47		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 48			if (!ctx.hasUI) {
 49				return {
 50					content: [
 51						{
 52							type: "text",
 53							text: "Error: Cannot ask user — running in non-interactive mode",
 54						},
 55					],
 56					details: { question: params.question, answer: null },
 57				};
 58			}
 59
 60			const { question, suggestions, multiSelect } = params;
 61			const hasSuggestions = suggestions && suggestions.length > 0;
 62
 63			let answer: string | undefined;
 64
 65			if (multiSelect && hasSuggestions) {
 66				// Multi-select: checkbox-style toggles using SettingsList
 67				const selected = new Set<string>();
 68
 69				const result = await ctx.ui.custom<string[] | null>((tui, theme, _kb, done) => {
 70					const container = new Container();
 71
 72					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
 73					container.addChild(new Text(theme.fg("accent", theme.bold(question)), 1, 0));
 74					container.addChild(new Text(theme.fg("dim", "Space/Enter toggle • Tab confirm • Esc cancel"), 1, 0));
 75
 76					const items: SettingItem[] = suggestions.map((s) => ({
 77						id: s,
 78						label: s,
 79						currentValue: "☐",
 80						values: ["☐", "☑"],
 81					}));
 82
 83					const settingsList = new SettingsList(
 84						items,
 85						Math.min(items.length + 2, 15),
 86						getSettingsListTheme(),
 87						(id, newValue) => {
 88							if (newValue === "☑") {
 89								selected.add(id);
 90							} else {
 91								selected.delete(id);
 92							}
 93						},
 94						() => done(null), // Esc → cancel
 95					);
 96					container.addChild(settingsList);
 97
 98					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
 99
100					return {
101						render: (w) => container.render(w),
102						invalidate: () => container.invalidate(),
103						handleInput: (data) => {
104							// Tab = confirm selections
105							if (data === "\t") {
106								done(Array.from(selected));
107								return;
108							}
109							settingsList.handleInput(data);
110							tui.requestRender();
111						},
112					};
113				});
114
115				if (result === null || result.length === 0) {
116					return {
117						content: [{ type: "text", text: "User cancelled — did not select any options." }],
118						details: { question, suggestions, multiSelect: true, answer: null, selected: [] },
119					};
120				}
121
122				answer = result.join(", ");
123				return {
124					content: [{ type: "text", text: `User selected: ${answer}` }],
125					details: { question, suggestions, multiSelect: true, answer, selected: result },
126				};
127			} else if (hasSuggestions) {
128				// Single-select: show suggestions as selectable options + free-form input
129				const freeFormOption = "✎ Type a different answer…";
130				const options = [...suggestions, freeFormOption];
131				const choice = await ctx.ui.select(question, options);
132
133				if (choice === undefined) {
134					return {
135						content: [{ type: "text", text: "User cancelled — did not answer the question." }],
136						details: { question, suggestions, answer: null },
137					};
138				}
139
140				if (choice === freeFormOption) {
141					answer = await ctx.ui.input(question);
142				} else {
143					answer = choice;
144				}
145			} else {
146				// Free-form text input
147				answer = await ctx.ui.input(question);
148			}
149
150			if (answer === undefined || answer.trim() === "") {
151				return {
152					content: [{ type: "text", text: "User cancelled — did not answer the question." }],
153					details: { question, suggestions, answer: null },
154				};
155			}
156
157			return {
158				content: [{ type: "text", text: `User answered: ${answer}` }],
159				details: { question, suggestions, answer },
160			};
161		},
162	});
163}