@agnishc/edb-ask-user 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Initial release: `ask_user` tool with text and choice question types
+- Single-question focused UI and multi-question tabbed wizard
+- `allowOther` inline editor for choice questions
+- Submit review tab showing all answers before submission

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agnish Chakraborty
+
+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,43 @@
+# @agnishc/edb-ask-user
+
+A Pi CLI extension that registers an `ask_user` tool — lets the LLM ask the user structured questions directly in the terminal UI without an extra model round-trip.
+
+## Question types
+
+| Type | UI | Use when |
+|------|----|----------|
+| `text` | Inline editor | Free-form answer needed |
+| `choice` | Numbered option list | Picking from a known set |
+
+Mix both types freely in one call. Single questions show a focused UI; multiple questions show a **tabbed wizard** with a Submit review tab.
+
+## Install
+
+```bash
+pi install npm:@agnishc/edb-ask-user
+```
+
+## Features
+
+- **No extra LLM call** — answers are collected immediately and returned to the model
+- **`allowOther`** on choice questions — adds a "Type something" option that opens an inline editor
+- **Multi-step wizard** — tab bar with answered/unanswered indicators and a Submit review tab
+- **Pre-filled answers** — revisiting a tab restores the previously entered value
+
+## Example
+
+```json
+{
+  "questions": [
+    { "id": "env",     "label": "Environment", "type": "choice",
+      "prompt": "Deploy to which environment?",
+      "options": [{ "value": "dev", "label": "Development" }, { "value": "prod", "label": "Production" }] },
+    { "id": "message", "label": "Message",     "type": "text",
+      "prompt": "Describe this deployment:" }
+  ]
+}
+```
+
+## License
+
+[MIT](LICENSE) © Agnish Chakraborty

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@agnishc/edb-ask-user",
+	"version": "0.1.0",
+	"description": "Pi extension: ask_user tool for structured questions — text, choice, and multi-step wizard",
+	"keywords": ["pi-package", "pi-extension", "edb"],
+	"type": "module",
+	"license": "MIT",
+	"author": "Agnish Chakraborty",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agnishcc/pi-extention-monorepo.git",
+		"directory": "packages/edb-ask-user"
+	},
+	"homepage": "https://github.com/agnishcc/pi-extention-monorepo/tree/main/packages/edb-ask-user#readme",
+	"bugs": { "url": "https://github.com/agnishcc/pi-extention-monorepo/issues" },
+	"publishConfig": { "access": "public" },
+	"scripts": { "test": "vitest run" },
+	"files": ["src", "README.md", "LICENSE", "CHANGELOG.md"],
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-ai": "*",
+		"@mariozechner/pi-coding-agent": "*",
+		"@mariozechner/pi-tui": "*",
+		"typebox": "*"
+	}
+}

package/src/component.ts

@@ -0,0 +1,382 @@
+import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
+import type { Answer, AskQuestion, AskResult, RenderOption } from "./types";
+
+// ── Component factory ──────────────────────────────────────────────────────────
+
+/**
+ * Builds and returns the TUI component object for the ask_user dialog.
+ * Handles both single-question (focused) and multi-question (tabbed wizard) UIs.
+ */
+export function createAskUserComponent(
+	tui: any,
+	theme: any,
+	done: (result: AskResult) => void,
+	questions: AskQuestion[],
+) {
+	const isMulti = questions.length > 1;
+	const totalTabs = questions.length + 1; // questions + Submit tab
+
+	// ── Shared state ──────────────────────────────────────────────────────────
+	let currentTab = 0;
+	let optionIndex = 0;
+	let inputMode = false;
+	let inputQuestionId: string | null = null;
+	let cachedLines: string[] | undefined;
+
+	const answers = new Map<string, Answer>();
+
+	// ── Inline editor ─────────────────────────────────────────────────────────
+	const editorTheme: EditorTheme = {
+		borderColor: (s) => theme.fg("accent", s),
+		selectList: {
+			selectedPrefix: (t) => theme.fg("accent", t),
+			selectedText: (t) => theme.fg("accent", t),
+			description: (t) => theme.fg("muted", t),
+			scrollInfo: (t) => theme.fg("dim", t),
+			noMatch: (t) => theme.fg("warning", t),
+		},
+	};
+	const editor = new Editor(tui, editorTheme);
+
+	// ── Helpers ───────────────────────────────────────────────────────────────
+
+	function refresh() {
+		cachedLines = undefined;
+		tui.requestRender();
+	}
+
+	function submitAll(cancelled: boolean) {
+		done({ questions, answers: Array.from(answers.values()), cancelled });
+	}
+
+	function currentQuestion(): AskQuestion | undefined {
+		return questions[currentTab];
+	}
+
+	function currentOptions(): RenderOption[] {
+		const q = currentQuestion();
+		if (!q || q.type !== "choice") return [];
+		const opts: RenderOption[] = [...(q.options ?? [])];
+		if (q.allowOther !== false) opts.push({ value: "__other__", label: "Type something.", isOther: true });
+		return opts;
+	}
+
+	function allAnswered(): boolean {
+		return questions.every((q) => answers.has(q.id));
+	}
+
+	function advanceAfterAnswer() {
+		if (!isMulti) {
+			submitAll(false);
+			return;
+		}
+		for (let i = currentTab + 1; i < questions.length; i++) {
+			if (!answers.has(questions[i]!.id)) {
+				switchToTab(i);
+				return;
+			}
+		}
+		switchToTab(questions.length);
+	}
+
+	function saveAnswer(questionId: string, value: string, label: string, wasCustom: boolean, optIndex?: number) {
+		const q = questions.find((x) => x.id === questionId);
+		answers.set(questionId, {
+			id: questionId,
+			value,
+			label,
+			type: q?.type ?? "text",
+			wasCustom,
+			optionIndex: optIndex,
+		});
+	}
+
+	function switchToTab(tabIndex: number) {
+		currentTab = tabIndex;
+		optionIndex = 0;
+		const q = questions[tabIndex];
+		if (q && q.type === "text") {
+			inputMode = true;
+			inputQuestionId = q.id;
+			const existing = answers.get(q.id);
+			editor.setText(existing ? existing.label : "");
+		} else {
+			inputMode = false;
+			inputQuestionId = null;
+			editor.setText("");
+		}
+		refresh();
+	}
+
+	editor.onSubmit = (value) => {
+		if (!inputQuestionId) return;
+		const trimmed = value.trim() || "(no response)";
+		saveAnswer(inputQuestionId, trimmed, trimmed, true);
+		inputMode = false;
+		inputQuestionId = null;
+		editor.setText("");
+		advanceAfterAnswer();
+	};
+
+	// ── Input handler ─────────────────────────────────────────────────────────
+
+	function handleInput(data: string) {
+		// ── Editor is active ───────────────────────────────────────────────
+		if (inputMode) {
+			if (matchesKey(data, Key.escape)) {
+				const q = currentQuestion();
+				if (q?.type === "text") {
+					submitAll(true);
+				} else {
+					inputMode = false;
+					inputQuestionId = null;
+					editor.setText("");
+					refresh();
+				}
+				return;
+			}
+			editor.handleInput(data);
+			refresh();
+			return;
+		}
+
+		// ── Tab bar navigation (multi-question only) ───────────────────────
+		if (isMulti) {
+			if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+				switchToTab((currentTab + 1) % totalTabs);
+				return;
+			}
+			if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+				switchToTab((currentTab - 1 + totalTabs) % totalTabs);
+				return;
+			}
+		}
+
+		// ── Submit tab ─────────────────────────────────────────────────────
+		if (isMulti && currentTab === questions.length) {
+			const submitItems = questions.length + 1;
+			if (matchesKey(data, Key.up)) {
+				optionIndex = Math.max(0, optionIndex - 1);
+				refresh();
+				return;
+			}
+			if (matchesKey(data, Key.down)) {
+				optionIndex = Math.min(submitItems - 1, optionIndex + 1);
+				refresh();
+				return;
+			}
+			if (matchesKey(data, Key.enter)) {
+				if (optionIndex < questions.length) {
+					switchToTab(optionIndex);
+				} else if (allAnswered()) {
+					submitAll(false);
+				}
+				return;
+			}
+			if (matchesKey(data, Key.escape)) {
+				submitAll(true);
+			}
+			return;
+		}
+
+		const q = currentQuestion();
+
+		// ── Choice question: option navigation ─────────────────────────────
+		if (q?.type === "choice") {
+			const opts = currentOptions();
+			if (matchesKey(data, Key.up)) {
+				optionIndex = Math.max(0, optionIndex - 1);
+				refresh();
+				return;
+			}
+			if (matchesKey(data, Key.down)) {
+				optionIndex = Math.min(opts.length - 1, optionIndex + 1);
+				refresh();
+				return;
+			}
+			if (matchesKey(data, Key.enter)) {
+				const opt = opts[optionIndex];
+				if (!opt) return;
+				if (opt.isOther) {
+					inputMode = true;
+					inputQuestionId = q.id;
+					const existing = answers.get(q.id);
+					editor.setText(existing?.wasCustom ? existing.label : "");
+					refresh();
+				} else {
+					saveAnswer(q.id, opt.value, opt.label, false, optionIndex + 1);
+					advanceAfterAnswer();
+				}
+				return;
+			}
+			if (matchesKey(data, Key.escape)) {
+				submitAll(true);
+				return;
+			}
+		}
+	}
+
+	// ── Renderer ──────────────────────────────────────────────────────────────
+
+	function render(width: number): string[] {
+		if (cachedLines) return cachedLines;
+
+		const lines: string[] = [];
+		const add = (s: string) => lines.push(truncateToWidth(s, width));
+		const hr = () => add(theme.fg("accent", "─".repeat(width)));
+		hr();
+
+		const canSubmit = allAnswered();
+
+		// ── Tab bar ─────────────────────────────────────────────────────────
+		if (isMulti) {
+			const parts: string[] = ["  "];
+			for (let i = 0; i < questions.length; i++) {
+				const isActive = i === currentTab;
+				const isAnswered = answers.has(questions[i]!.id);
+				const bullet = isAnswered ? "■" : "□";
+				const color: "success" | "muted" = isAnswered ? "success" : "muted";
+				const lbl = ` ${bullet} ${questions[i]!.label} `;
+				parts.push(isActive ? `${theme.bg("selectedBg", theme.fg("text", lbl))} ` : `${theme.fg(color, lbl)} `);
+			}
+			const isSubmitActive = currentTab === questions.length;
+			const submitLabel = " ✓ Submit ";
+			parts.push(
+				isSubmitActive
+					? theme.bg("selectedBg", theme.fg("text", submitLabel))
+					: theme.fg(canSubmit ? "success" : "dim", submitLabel),
+			);
+			add(parts.join(""));
+			lines.push("");
+		}
+
+		// ── Content ─────────────────────────────────────────────────────────
+		const q = currentQuestion();
+		const opts = currentOptions();
+
+		if (isMulti && currentTab === questions.length) {
+			// Submit tab
+			add(theme.fg("accent", theme.bold(" Review your answers")));
+			lines.push("");
+			for (let i = 0; i < questions.length; i++) {
+				const question = questions[i]!;
+				const ans = answers.get(question.id);
+				const sel = optionIndex === i;
+				const prefix = sel ? theme.fg("accent", "> ") : "  ";
+				add(prefix + (sel ? theme.fg("accent", question.prompt) : theme.fg("text", question.prompt)));
+				if (ans) {
+					const pre = ans.wasCustom ? theme.fg("muted", "(wrote) ") : theme.fg("dim", `${ans.optionIndex}. `);
+					add(`    ${theme.fg("success", "✓ ")}${pre}${theme.fg(sel ? "accent" : "muted", ans.label)}`);
+				} else {
+					add(
+						`    ${theme.fg("warning", "✗ unanswered")}${sel ? theme.fg("dim", " — press Enter to answer") : ""}`,
+					);
+				}
+				lines.push("");
+			}
+			const submitSel = optionIndex === questions.length;
+			const submitPrefix = submitSel ? theme.fg("accent", "> ") : "  ";
+			if (canSubmit) {
+				add(
+					submitPrefix +
+						(submitSel ? theme.fg("accent", theme.bold("✓ Submit All")) : theme.fg("success", "✓ Submit All")),
+				);
+			} else {
+				const missing = questions
+					.filter((x) => !answers.has(x.id))
+					.map((x) => x.label)
+					.join(", ");
+				add(`  ${theme.fg("dim", "✓ Submit All")} ${theme.fg("warning", `(unanswered: ${missing})`)}`);
+			}
+			lines.push("");
+			add(theme.fg("dim", " ↑↓ navigate • Enter to edit answer or submit • Tab/←→ switch tab • Esc cancel"));
+		} else if (q?.type === "text") {
+			add(theme.fg("text", ` ${q.prompt}`));
+			if (q.placeholder) add(theme.fg("dim", `   ${q.placeholder}`));
+			lines.push("");
+			for (const line of editor.render(width - 2)) add(` ${line}`);
+			lines.push("");
+			add(theme.fg("dim", " Enter to submit • Esc to cancel"));
+		} else if (q?.type === "choice") {
+			add(theme.fg("text", ` ${q.prompt}`));
+			lines.push("");
+			if (inputMode) {
+				// Inline "other" editor inside option list
+				for (let i = 0; i < opts.length; i++) {
+					const opt = opts[i]!;
+					const selected = i === optionIndex;
+					const prefix = selected ? theme.fg("accent", "> ") : "  ";
+					if (opt.isOther) {
+						add(prefix + theme.fg("accent", `${i + 1}. ${opt.label} ✎`));
+					} else {
+						add(
+							prefix +
+								(selected
+									? theme.fg("accent", `${i + 1}. ${opt.label}`)
+									: theme.fg("text", `${i + 1}. ${opt.label}`)),
+						);
+						if (opt.description) add(`     ${theme.fg("muted", opt.description)}`);
+					}
+				}
+				lines.push("");
+				add(theme.fg("muted", " Your answer:"));
+				for (const line of editor.render(width - 2)) add(` ${line}`);
+				lines.push("");
+				add(theme.fg("dim", " Enter to submit • Esc to go back"));
+			} else {
+				for (let i = 0; i < opts.length; i++) {
+					const opt = opts[i]!;
+					const selected = i === optionIndex;
+					const isAnswered =
+						!opt.isOther && answers.get(q.id)?.value === opt.value && !answers.get(q.id)?.wasCustom;
+					const prefix = selected ? theme.fg("accent", "> ") : "  ";
+					const checkmark = isAnswered ? theme.fg("success", " ✓") : "";
+					add(
+						prefix +
+							(selected
+								? theme.fg("accent", `${i + 1}. ${opt.label}`)
+								: theme.fg("text", `${i + 1}. ${opt.label}`)) +
+							checkmark,
+					);
+					if (opt.description) add(`     ${theme.fg("muted", opt.description)}`);
+				}
+				const existing = answers.get(q.id);
+				if (existing?.wasCustom) {
+					lines.push("");
+					add(
+						theme.fg("dim", "   Current: ") +
+							theme.fg("success", "✓ ") +
+							theme.fg("muted", "(wrote) ") +
+							theme.fg("accent", existing.label),
+					);
+				}
+				lines.push("");
+				add(
+					theme.fg(
+						"dim",
+						isMulti
+							? " ↑↓ navigate • Enter select • Tab/←→ switch tab • Esc cancel"
+							: " ↑↓ navigate • Enter select • Esc cancel",
+					),
+				);
+			}
+		}
+
+		lines.push("");
+		hr();
+
+		cachedLines = lines;
+		return lines;
+	}
+
+	// ── Bootstrap: activate first tab ─────────────────────────────────────────
+	switchToTab(0);
+
+	return {
+		render,
+		invalidate: () => {
+			cachedLines = undefined;
+		},
+		handleInput,
+	};
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * pi-ask-user
+ *
+ * Provides an `ask_user` tool that lets the LLM ask the user structured
+ * questions directly in the terminal UI — without an extra model round-trip.
+ *
+ * Supports three question modes (freely mixed in one call):
+ *   - text   : free-form text input via inline editor
+ *   - choice : pick from a numbered option list (+ optional "Type something")
+ *
+ * Single question  → focused UI, no tab bar, immediate return
+ * Multiple questions → tab-based wizard with a Submit tab
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createAskUserComponent } from "./component";
+import { renderCall, renderResult } from "./render";
+import { AskUserParams } from "./schemas";
+import type { AskQuestion, AskResult } from "./types";
+
+// ── Extension ──────────────────────────────────────────────────────────────────
+
+export default function askUserExtension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask User",
+		description:
+			"Ask the user one or more structured questions directly in the terminal UI. " +
+			"Supports free-text input, multiple-choice option lists, and multi-step " +
+			"questionnaires. Use this instead of embedding questions in your response text " +
+			"to avoid an extra model round-trip and give the user a clear, interactive prompt.",
+		promptSnippet: "Ask the user a question or questionnaire and get structured answers",
+		promptGuidelines: [
+			"Use ask_user whenever you need information, a preference, or confirmation from the user before proceeding.",
+			"Prefer ask_user over posing questions in your response text — it collects answers immediately without an extra LLM call.",
+			"For a single free-form question set type to 'text'. " +
+				"For a multiple-choice question set type to 'choice' and provide options. " +
+				"Pass several questions together for a multi-step flow.",
+			"For choice questions, set allowOther to false only when an open-ended answer is not acceptable.",
+		],
+		parameters: AskUserParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			// ── Guard: interactive mode only ──────────────────────────────────
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{ type: "text", text: "Error: ask_user requires an interactive terminal (UI not available)." },
+					],
+					details: { questions: [], answers: [], cancelled: true } satisfies AskResult,
+				};
+			}
+
+			if (params.questions.length === 0) {
+				return {
+					content: [{ type: "text", text: "Error: No questions provided." }],
+					details: { questions: [], answers: [], cancelled: true } satisfies AskResult,
+				};
+			}
+
+			// Validate: choice questions must have at least one option
+			for (const q of params.questions) {
+				if (q.type === "choice" && (!q.options || q.options.length === 0)) {
+					return {
+						content: [{ type: "text", text: `Error: Question "${q.id}" is type 'choice' but has no options.` }],
+						details: { questions: [], answers: [], cancelled: true } satisfies AskResult,
+					};
+				}
+			}
+
+			// Normalise questions (fill in derived defaults)
+			const questions: AskQuestion[] = params.questions.map((q, i) => ({
+				...q,
+				label: q.label || `Q${i + 1}`,
+				allowOther: true,
+			}));
+
+			// ── Build & show the custom TUI ───────────────────────────────────
+			const result = await ctx.ui.custom<AskResult>((tui, theme, _kb, done) =>
+				createAskUserComponent(tui, theme, done, questions),
+			);
+
+			// ── Build response for LLM ────────────────────────────────────────
+			if (result.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the prompt." }],
+					details: result satisfies AskResult,
+				};
+			}
+
+			const lines = result.answers.map((a) => {
+				const q = questions.find((x) => x.id === a.id);
+				const label = q?.label ?? a.id;
+				if (a.wasCustom) return `${label} (${a.id}): user wrote: ${a.label}`;
+				return `${label} (${a.id}): user selected: ${a.optionIndex}. ${a.label}`;
+			});
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: result satisfies AskResult,
+			};
+		},
+
+		renderCall,
+		renderResult,
+	});
+}

package/src/render.ts

@@ -0,0 +1,48 @@
+import { Text, truncateToWidth } from "@mariozechner/pi-tui";
+import type { AskQuestion, AskResult } from "./types";
+
+// ── TUI rendering ──────────────────────────────────────────────────────────────
+
+export function renderCall(args: any, theme: any): any {
+	const qs = (args.questions as AskQuestion[]) ?? [];
+	const count = qs.length;
+	let text = theme.fg("toolTitle", theme.bold("ask_user "));
+	if (count === 1) {
+		const q = qs[0];
+		const typeTag = theme.fg("muted", `[${q?.type ?? "?"}] `);
+		text += typeTag + theme.fg("muted", q?.prompt ?? "");
+	} else {
+		text += theme.fg("muted", `${count} questions`);
+		const labels = qs.map((q, i) => q.label || `Q${i + 1}`).join(", ");
+		if (labels) text += theme.fg("dim", ` (${truncateToWidth(labels, 48)})`);
+	}
+	return new Text(text, 0, 0);
+}
+
+export function renderResult(result: any, _options: any, theme: any): any {
+	const details = result.details as AskResult | undefined;
+	if (!details) {
+		const first = result.content[0];
+		return new Text(first?.type === "text" ? first.text : "", 0, 0);
+	}
+	if (details.cancelled) {
+		return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+	}
+
+	const lines = details.answers.map((a) => {
+		const q = details.questions.find((x) => x.id === a.id);
+		const label = q?.label ?? a.id;
+		if (a.wasCustom) {
+			return (
+				theme.fg("success", "✓ ") +
+				theme.fg("accent", label) +
+				theme.fg("dim", ": ") +
+				theme.fg("muted", "(wrote) ") +
+				a.label
+			);
+		}
+		const num = a.optionIndex ? `${a.optionIndex}. ` : "";
+		return theme.fg("success", "✓ ") + theme.fg("accent", label) + theme.fg("dim", ": ") + num + a.label;
+	});
+	return new Text(lines.join("\n"), 0, 0);
+}

package/src/schemas.ts

@@ -0,0 +1,66 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "typebox";
+
+// ── Schemas ────────────────────────────────────────────────────────────────────
+
+export const OptionSchema = Type.Object({
+	value: Type.String({
+		description: "Machine-readable value returned when this option is selected",
+	}),
+	label: Type.String({
+		description: "Human-readable display label for the option",
+	}),
+	description: Type.Optional(
+		Type.String({
+			description: "Optional sub-label shown below the option (e.g. a clarifying note)",
+		}),
+	),
+});
+
+export const QuestionSchema = Type.Object({
+	id: Type.String({
+		description: "Unique key for this question — used to identify it in the returned answers map",
+	}),
+	prompt: Type.String({
+		description: "The question text shown to the user",
+	}),
+	type: StringEnum(["text", "choice"] as const, {
+		description:
+			"text: user types a free-form answer via inline editor; " + "choice: user picks from a numbered option list",
+	}),
+	label: Type.Optional(
+		Type.String({
+			description:
+				"Short label shown in the tab bar when multiple questions are asked " +
+				"(e.g. 'Scope', 'Priority'). Defaults to Q1, Q2, …",
+		}),
+	),
+	options: Type.Optional(
+		Type.Array(OptionSchema, {
+			description: "Required when type is 'choice'. The options the user can choose from.",
+		}),
+	),
+	placeholder: Type.Optional(
+		Type.String({
+			description:
+				"Hint text shown inside the editor for text questions " +
+				"(e.g. 'Enter your API key…'). Purely informational.",
+		}),
+	),
+	allowOther: Type.Optional(
+		Type.Boolean({
+			description:
+				"For choice questions: whether to append a 'Type something' option " +
+				"that opens a free-text editor. Defaults to true.",
+		}),
+	),
+});
+
+export const AskUserParams = Type.Object({
+	questions: Type.Array(QuestionSchema, {
+		description:
+			"One or more questions to ask the user. " +
+			"Single-item arrays show a focused UI. " +
+			"Multi-item arrays show a tabbed wizard with a Submit step.",
+	}),
+});

package/src/types.ts

@@ -0,0 +1,34 @@
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export interface QuestionOption {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export type RenderOption = QuestionOption & { isOther?: boolean };
+
+export interface AskQuestion {
+	id: string;
+	prompt: string;
+	type: "text" | "choice";
+	options?: QuestionOption[];
+	placeholder?: string;
+	allowOther?: boolean;
+	label?: string;
+}
+
+export interface Answer {
+	id: string;
+	value: string;
+	label: string;
+	type: "text" | "choice";
+	wasCustom: boolean;
+	optionIndex?: number;
+}
+
+export interface AskResult {
+	questions: AskQuestion[];
+	answers: Answer[];
+	cancelled: boolean;
+}