@hank-warren/pi-ask-user-question 0.2.2 → 0.3.0

package/README.md

@@ -4,8 +4,8 @@ A structured questionnaire the model can put to you when it would otherwise
 guess. Instead of a free-form "which do you prefer?" in chat, you get a dialog
 with numbered options, digit hotkeys, a typed-answer escape, and Tab-to-comment.
 
-> **v0.1** ships one question per call, single-select, no preview pane. See
-> [the spec](../../docs/specs/pi-ask-user-question.md) §14 for the road to v0.2.
+> **v0.2** ships 1-4 questions per call as cycleable tabs, single-select, no
+> preview pane. See [the spec](../../docs/specs/pi-ask-user-question.md) §14.
 
 ## Install
 
@@ -23,8 +23,19 @@ register a tool named `ask_user_question`.
 | `1`–`9` | Select that option immediately |
 | `↑` / `↓` | Move the highlight |
 | `Enter` | Confirm the highlighted option |
-| `Tab` | Attach a note to your choice, then `Enter` to send both |
-| `Esc` | Decline the question (or leave note/typed-answer mode) |
+| `n` | Attach a note to your choice, then `Enter` to send both |
+| `Tab` / `→` | Next question |
+| `Shift+Tab` / `←` | Previous question |
+| `Esc` | Decline the questionnaire (or leave note/typed-answer mode) |
+
+With several questions, each is a tab you can cycle through in any order;
+answering one jumps to the next unanswered question, and the call returns once
+every question has an answer. Cycling back and re-answering replaces that
+question's answer rather than recording a second one.
+
+**Why `n` and not `Tab` for notes?** Tab cycles questions here, matching
+`@juicesharp/rpiv-ask-user-question`. `pi-auto-permissions` approval prompts
+keep `Tab` for notes — they are single-question and have no tabs to cycle.
 
 Every question gets an appended **`Type something.`** row for a free-text
 answer. The model is not allowed to author that row itself — reserved labels

package/ask-user-question.ts

@@ -35,16 +35,16 @@ const ERROR_NO_UI = "Error: UI not available (running in non-interactive mode)";
 const ERROR_NO_CUSTOM_UI =
 	"Error: this client cannot render the questionnaire (custom UI is unavailable). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, without using this tool.";
 
-const DESCRIPTION = `Ask the user a structured question during execution. Use when you need to:
+const DESCRIPTION = `Ask the user one or more structured questions during execution. Use when you need to:
 1. Gather user preferences or requirements
 2. Clarify ambiguous instructions
 3. Get decisions on implementation choices as you work
 4. Offer choices to the user about what direction to take
 
 Usage notes:
-- The user can pick an option with the number keys, type a custom answer via the automatically appended "Type something." row, attach a note to their choice with Tab, or press Esc to decline. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
+- The user can pick an option with the number keys, type a custom answer via the automatically appended "Type something." row, attach a note to their choice by pressing n, or press Esc to decline. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
 - If you recommend a specific option, make it the first option and add "(Recommended)" at the end of the label.
-- This version accepts exactly one question per call with 2-4 options.`;
+- Ask 1-4 questions per call, each with 2-4 options. Multiple questions render as tabs the user cycles with Tab; every question must be answered before the call returns. Group questions that belong to one decision rather than asking them in separate calls, but do not pad a single decision into several questions.`;
 
 function emitPrompt(pi: ExtensionAPI, params: AskUserParams): void {
 	const payload: AskUserPromptEventPayload = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-ask-user-question",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Structured questionnaire tool for Pi with numbered options, digit hotkeys and Tab-to-comment, composed from the shared permission-selector component.",
   "type": "module",
   "keywords": [
@@ -45,7 +45,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@hank-warren/pi-permission-selector": "^0.2.0"
+    "@hank-warren/pi-permission-selector": "^0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/questionnaire.ts

@@ -2,9 +2,15 @@
  * Questionnaire session state — a plain mutable object, no reducer.
  *
  * @juicesharp/rpiv-ask-user-question spends ~1,500 lines on a Redux-style
- * reducer plus four selector modules for this. The state here is one question
- * index, one answer list, and a custom-answer buffer; a reducer would add
- * indirection without adding a single testable guarantee.
+ * reducer plus four selector modules for this. The state here is a cursor and
+ * a sparse answer array; a reducer would add indirection without adding a
+ * single testable guarantee.
+ *
+ * NAVIGATION MODEL. Questions are tabs, not a queue. The cursor moves freely
+ * (Tab / Shift+Tab, wrapping), answers are stored BY QUESTION INDEX so
+ * revisiting a question replaces its answer rather than appending a second
+ * one, and the questionnaire is complete only when every question has an
+ * answer. This mirrors the tab model of rpiv-ask-user-question.
  *
  * Pure: no pi imports, no rendering. The dialog drives it; tests drive it the
  * same way.
@@ -27,10 +33,12 @@ export interface SelectableRow {
 export class QuestionnaireSession {
 	private readonly params: AskUserParams;
 	private index = 0;
-	private readonly answers: QuestionAnswer[] = [];
+	/** Sparse by design: `answers[i]` is undefined until question i is answered. */
+	private readonly answers: Array<QuestionAnswer | undefined>;
 
 	constructor(params: AskUserParams) {
 		this.params = params;
+		this.answers = new Array(params.questions.length).fill(undefined);
 	}
 
 	get questionIndex(): number {
@@ -45,16 +53,54 @@ export class QuestionnaireSession {
 		return this.params.questions[this.index];
 	}
 
-	/** True once every question has been answered. */
+	/** Move the cursor, wrapping at both ends. */
+	goTo(index: number): void {
+		if (this.total === 0) return;
+		this.index = ((index % this.total) + this.total) % this.total;
+	}
+
+	next(): void {
+		this.goTo(this.index + 1);
+	}
+
+	previous(): void {
+		this.goTo(this.index - 1);
+	}
+
+	/** True once every question has an answer. */
 	isComplete(): boolean {
-		return this.index >= this.total;
+		return this.answers.every((answer) => answer !== undefined);
+	}
+
+	isAnswered(index: number): boolean {
+		return this.answers[index] !== undefined;
+	}
+
+	answeredCount(): number {
+		return this.answers.filter((answer) => answer !== undefined).length;
+	}
+
+	/**
+	 * Move to the next question without an answer, searching forward from the
+	 * cursor and wrapping. Returns false when everything is answered, which the
+	 * dialog treats as "submit".
+	 */
+	advanceToUnanswered(): boolean {
+		for (let step = 1; step <= this.total; step++) {
+			const candidate = (this.index + step) % this.total;
+			if (!this.isAnswered(candidate)) {
+				this.index = candidate;
+				return true;
+			}
+		}
+		return false;
 	}
 
 	/**
 	 * Rows for the current question: the authored options plus the appended
 	 * custom-answer sentinel. The sentinel is never an authored option — it is
-	 * added here and stripped in `recordAnswer`, which is why validation
-	 * rejects models that try to author it themselves.
+	 * added here and stripped when recording, which is why validation rejects
+	 * models that try to author it themselves.
 	 */
 	rows(): SelectableRow[] {
 		const question = this.current;
@@ -74,23 +120,33 @@ export class QuestionnaireSession {
 	}
 
 	/**
-	 * Record an answer for the current question and advance. `custom` marks a
-	 * typed free-text answer; `notes` is the Tab-to-comment note.
+	 * Record (or replace) the answer for the current question. Replacement is
+	 * the point: cycling back to a question and picking again must not leave
+	 * two answers for one question in the envelope.
 	 */
 	recordAnswer(answer: string, opts: { custom?: boolean; notes?: string } = {}): void {
 		const question = this.current;
 		if (!question) return;
-		this.answers.push({
+		this.answers[this.index] = {
 			questionIndex: this.index,
 			question: question.question,
 			answer,
 			custom: opts.custom === true,
 			...(opts.notes ? { notes: opts.notes } : {}),
-		});
-		this.index += 1;
+		};
+	}
+
+	/** The recorded answer for a question, if any. */
+	answerAt(index: number): QuestionAnswer | undefined {
+		return this.answers[index];
+	}
+
+	/** Header for question `index`, used by the tab strip. */
+	headerAt(index: number): string {
+		return this.params.questions[index]?.header ?? "";
 	}
 
-	/** Title line for the dialog: `Header` or `2 of 3 · Header` when multiple. */
+	/** Title line: `Header` alone, or `2 of 3 · Header` when there are tabs. */
 	title(): string {
 		const question = this.current;
 		if (!question) return "";
@@ -99,13 +155,17 @@ export class QuestionnaireSession {
 			: question.header;
 	}
 
+	private collected(): QuestionAnswer[] {
+		return this.answers.filter((answer): answer is QuestionAnswer => answer !== undefined);
+	}
+
 	/** Successful outcome. */
 	result(): QuestionnaireResult {
-		return { answers: [...this.answers], cancelled: false };
+		return { answers: this.collected(), cancelled: false };
 	}
 
 	/** Declined outcome, preserving any answers given before the cancel. */
 	cancelledResult(): QuestionnaireResult {
-		return { answers: [...this.answers], cancelled: true };
+		return { answers: this.collected(), cancelled: true };
 	}
 }

package/tool/schema.ts

@@ -1,11 +1,9 @@
 /**
  * Tool parameter schema and shared types for `ask_user_question`.
  *
- * v0.1 scope (docs/specs/pi-ask-user-question.md §14): a SINGLE question,
- * single-select, no preview. The schema still accepts the `questions` array
- * shape so that v0.2 can lift the count limit without changing the wire
- * contract the model has already learned, and so session history recorded
- * against the array shape keeps replaying.
+ * v0.2 scope (docs/specs/pi-ask-user-question.md §14): up to four questions,
+ * single-select, no preview. Questions render as tabs the user cycles with
+ * Tab / Shift+Tab.
  */
 
 import { Type } from "typebox";
@@ -16,8 +14,7 @@ export const TOOL_NAME = "ask_user_question";
 export const MIN_OPTIONS = 2;
 export const MAX_OPTIONS = 4;
 export const MIN_QUESTIONS = 1;
-/** v0.1 ships single-question only; v0.2 raises this to 4. */
-export const MAX_QUESTIONS = 1;
+export const MAX_QUESTIONS = 4;
 
 export const MAX_HEADER_LENGTH = 16;
 export const MAX_LABEL_LENGTH = 60;
@@ -63,7 +60,8 @@ export const QuestionSchema = Type.Object({
 
 export const QuestionParamsSchema = Type.Object({
 	questions: Type.Array(QuestionSchema, {
-		description: "Questions to ask the user. Exactly one question is supported in this version.",
+		description:
+			"Questions to ask the user. 1-4 questions; the user cycles between them with Tab and answers each one.",
 		minItems: MIN_QUESTIONS,
 		maxItems: MAX_QUESTIONS,
 	}),

package/tool/validate.ts

@@ -49,10 +49,7 @@ export function validateParams(params: AskUserParams): ValidationError | undefin
 	if (!Array.isArray(questions) || questions.length < MIN_QUESTIONS || questions.length > MAX_QUESTIONS) {
 		return {
 			code: "bad_question_count",
-			message:
-				MAX_QUESTIONS === 1
-					? `This version supports exactly ${MAX_QUESTIONS} question per call; received ${questions?.length ?? 0}. Ask the most important question first, then follow up.`
-					: `questions must contain ${MIN_QUESTIONS}-${MAX_QUESTIONS} entries; received ${questions?.length ?? 0}.`,
+			message: `questions must contain ${MIN_QUESTIONS}-${MAX_QUESTIONS} entries; received ${questions?.length ?? 0}. Group questions that belong to one decision; ask further questions in a follow-up call.`,
 		};
 	}
 

package/view/dialog.ts

@@ -2,13 +2,27 @@
  * The questionnaire dialog: a pi-tui component driven by QuestionnaireSession
  * and rendered through `ctx.ui.custom()`.
  *
- * NO MONKEY PATCHING. The numbered options, digit hotkeys and Tab-to-comment
+ * NO MONKEY PATCHING. The numbered options, digit hotkeys and the note editor
  * come from `OptionSelector`, imported from the PUBLISHED sibling package
  * `@hank-warren/pi-permission-selector` (plain `dependencies`, never
  * `bundledDependencies` — AGENTS.md §Structure). See
  * docs/specs/pi-ask-user-question.md §9.
  *
- * TWO RULES, both learned from v0.2.0 shipping broken:
+ * KEY MAP (matches @juicesharp/rpiv-ask-user-question):
+ *
+ *   1-9         select an option
+ *   ↑ / ↓       move the highlight
+ *   enter       confirm the highlight
+ *   n           open the note editor for the highlighted option
+ *   tab / →     next question      shift+tab / ←   previous question
+ *   esc         decline the questionnaire
+ *
+ * Note that `n`, not Tab, opens notes here. Tab is reserved for cycling
+ * questions. pi-auto-permissions approval prompts keep Tab-to-comment, because
+ * they are single-question and have no tabs to cycle — `OptionSelector`
+ * defaults to Tab and this dialog overrides it.
+ *
+ * THREE RULES, all learned from shipping bugs:
  *
  * 1. NEVER compare key data with `===`. Every key check goes through the
  *    shared predicates in `.../keys.ts`. Under the Kitty keyboard protocol
@@ -16,8 +30,7 @@
  *    trapped the user in the custom-answer field with no way out.
  * 2. ALWAYS pad rendered lines to the full overlay width. pi composites an
  *    overlay onto the chat line by line and only overwrites the columns the
- *    overlay actually emits; short lines let chat text show through and the
- *    dialog renders as garbage interleaved with the transcript.
+ *    overlay actually emits; short lines let chat text show through.
  * 3. ALWAYS clamp lines to the inner width. A single over-long line breaks the
  *    right border and spills into the transcript, so `render` truncates as a
  *    last-resort invariant no matter what any content source produces.
@@ -25,9 +38,14 @@
 
 import {
 	isBackspaceKey,
+	isCharKey,
 	isEnterKey,
 	isEscapeKey,
+	isLeftKey,
 	isPrintable,
+	isRightKey,
+	isShiftTabKey,
+	isTabKey,
 } from "@hank-warren/pi-permission-selector/keys.ts";
 import { OptionSelector, type SelectorOption } from "@hank-warren/pi-permission-selector/selector.ts";
 import {
@@ -63,65 +81,87 @@ export interface DialogOptions {
 const CHROME_COLUMNS = 4;
 /** Indent for the custom-answer field, in columns. */
 const FIELD_INDENT = "  ";
+/** Opens the note editor. Tab is taken by question cycling. */
+const NOTE_KEY = "n";
+const isNoteKey = isCharKey(NOTE_KEY);
+
+/** Per-question UI state, preserved while cycling between tabs. */
+interface TabState {
+	selector: OptionSelector;
+	customText?: string;
+	pendingNotes?: string;
+}
 
 export class QuestionnaireDialog {
 	/** Focusable — set by the TUI when focus changes. Drives CURSOR_MARKER. */
 	focused = false;
 
 	private readonly opts: DialogOptions;
-	private selector: OptionSelector;
-	private customText: string | undefined;
-	private pendingNotes: string | undefined;
+	private readonly tabs: TabState[] = [];
 	private finished = false;
 
 	constructor(opts: DialogOptions) {
 		this.opts = opts;
-		this.selector = this.buildSelector();
+		for (let i = 0; i < this.session.total; i++) this.tabs.push({ selector: this.buildSelector(i) });
 	}
 
 	private get session() {
 		return this.opts.session;
 	}
 
+	private get tab(): TabState {
+		return this.tabs[this.session.questionIndex];
+	}
+
 	private repaint(): void {
 		this.opts.requestRender?.();
 	}
 
-	private buildSelector(): OptionSelector {
+	private buildSelector(index: number): OptionSelector {
 		const session = this.session;
+		const previous = session.goTo.bind(session);
+		// rows() reads the cursor, so snapshot this tab's rows at build time.
+		const restore = session.questionIndex;
+		previous(index);
 		const options: SelectorOption[] = session.rows().map((row) => ({
 			value: row.value,
 			label: row.label,
 			description: row.description,
 		}));
+		previous(restore);
 
 		return new OptionSelector({
 			options,
 			theme: this.opts.theme,
+			// `n` instead of Tab; Tab must stay free for question cycling. Tab is
+			// left unconsumed by the selector so this dialog can intercept it.
+			commentTrigger: isNoteKey,
+			commentKeyHint: NOTE_KEY,
 			onSelect: (option, comment) => {
+				session.goTo(index);
 				if (session.isCustomRow(option.value)) {
 					// Enter free-text mode. A note typed on the sentinel row is
 					// carried across so it is not silently lost.
-					this.pendingNotes = comment;
-					this.customText = "";
+					this.tabs[index].pendingNotes = comment;
+					this.tabs[index].customText = "";
 					this.repaint();
 					return;
 				}
 				session.recordAnswer(option.value, { notes: comment });
-				this.advance();
+				this.afterAnswer();
 			},
 			onCancel: () => this.finish(session.cancelledResult()),
 			requestRender: () => this.repaint(),
 		});
 	}
 
-	private advance(): void {
+	/** Submit when everything is answered, else jump to the next gap. */
+	private afterAnswer(): void {
 		if (this.session.isComplete()) {
 			this.finish(this.session.result());
 			return;
 		}
-		// v0.2: multi-question calls rebind the selector to the next question.
-		this.selector = this.buildSelector();
+		this.session.advanceToUnanswered();
 		this.repaint();
 	}
 
@@ -133,11 +173,16 @@ export class QuestionnaireDialog {
 
 	/** True while the free-text custom-answer editor is open. */
 	isTypingCustom(): boolean {
-		return this.customText !== undefined;
+		return this.tab?.customText !== undefined;
+	}
+
+	/** True while any text-entry mode owns the keyboard. */
+	private isTyping(): boolean {
+		return this.isTypingCustom() || this.tab.selector.isCommenting();
 	}
 
 	invalidate(): void {
-		this.selector.invalidate();
+		for (const tab of this.tabs) tab.selector.invalidate();
 	}
 
 	private style(role: string, text: string): string {
@@ -145,19 +190,34 @@ export class QuestionnaireDialog {
 		return role === "dim" ? `\x1b[2m${text}\x1b[0m` : text;
 	}
 
+	/** `✓ Database   ▸ Cache   ○ Queue` — one line, only when tabs exist. */
+	private tabStrip(): string {
+		const parts: string[] = [];
+		for (let i = 0; i < this.session.total; i++) {
+			const current = i === this.session.questionIndex;
+			const mark = this.session.isAnswered(i) ? "✓" : current ? "▸" : "○";
+			const label = `${mark} ${this.session.headerAt(i)}`;
+			parts.push(current ? this.style("accent", label) : this.style("dim", label));
+		}
+		return parts.join("   ");
+	}
+
 	/** Inner content lines, before the box is drawn around them. */
 	private contentLines(inner: number): string[] {
 		const session = this.session;
-		const lines: string[] = [this.style("accent", session.title()), ""];
+		const lines: string[] = [this.style("accent", session.title())];
+		if (session.total > 1) lines.push(this.tabStrip());
+		lines.push("");
 		lines.push(...wrapTextWithAnsi(session.current?.question ?? "", inner));
 		lines.push("");
 
-		if (this.customText !== undefined) {
+		const tab = this.tab;
+		if (tab.customText !== undefined) {
 			// Wrap the typed answer. Without this a long answer ran past the right
 			// border and off the screen forever, because an input field renders as
 			// one line unless something breaks it up.
 			const avail = Math.max(1, inner - FIELD_INDENT.length - 1); // -1 reserves the caret cell
-			const wrapped = wrapTextWithAnsi(this.customText, avail);
+			const wrapped = wrapTextWithAnsi(tab.customText, avail);
 			// CURSOR_MARKER is a zero-width APC sequence: the TUI strips it and
 			// parks the hardware cursor there, so the caret lands in the field
 			// instead of at the bottom of the screen.
@@ -171,7 +231,10 @@ export class QuestionnaireDialog {
 			return lines;
 		}
 
-		lines.push(...this.selector.render(inner));
+		lines.push(...tab.selector.render(inner));
+		if (session.total > 1 && !tab.selector.isCommenting()) {
+			lines.push(this.style("dim", "  tab next · shift+tab prev question"));
+		}
 		return lines;
 	}
 
@@ -196,43 +259,62 @@ export class QuestionnaireDialog {
 	}
 
 	handleInput(keyData: string): void {
-		if (this.customText === undefined) {
-			this.selector.handleInput(keyData);
+		const tab = this.tab;
+
+		// Question cycling. Deliberately NOT active while typing: Tab inside the
+		// note editor means "back to options", and inside the custom-answer field
+		// a stray Tab must never teleport the user to another question and strand
+		// their half-typed text.
+		if (this.session.total > 1 && !this.isTyping()) {
+			if (isTabKey(keyData) || isRightKey(keyData)) {
+				this.session.next();
+				this.repaint();
+				return;
+			}
+			if (isShiftTabKey(keyData) || isLeftKey(keyData)) {
+				this.session.previous();
+				this.repaint();
+				return;
+			}
+		}
+
+		if (tab.customText === undefined) {
+			tab.selector.handleInput(keyData);
 			return;
 		}
 
 		// Free-text mode. Every check below MUST use a shared predicate — see
-		// the header comment. Esc unwinds to the option list rather than
-		// cancelling the dialog: one Esc never discards more than one layer.
+		// rule 1. Esc unwinds to the option list rather than cancelling the
+		// dialog: one Esc never discards more than one layer.
 		if (isEscapeKey(keyData)) {
-			this.customText = undefined;
-			this.pendingNotes = undefined;
+			tab.customText = undefined;
+			tab.pendingNotes = undefined;
 			this.repaint();
 			return;
 		}
 		if (isEnterKey(keyData)) {
-			const text = this.customText.trim();
+			const text = tab.customText.trim();
 			if (text.length === 0) return; // Empty custom answers are not submittable.
-			this.session.recordAnswer(text, { custom: true, notes: this.pendingNotes });
-			this.customText = undefined;
-			this.pendingNotes = undefined;
-			this.advance();
+			this.session.recordAnswer(text, { custom: true, notes: tab.pendingNotes });
+			tab.customText = undefined;
+			tab.pendingNotes = undefined;
+			this.afterAnswer();
 			return;
 		}
 		if (isBackspaceKey(keyData)) {
-			this.customText = this.customText.slice(0, -1);
+			tab.customText = tab.customText.slice(0, -1);
 			this.repaint();
 			return;
 		}
 		if (isPrintable(keyData)) {
-			this.customText += keyData;
+			tab.customText += keyData;
 			this.repaint();
 			return;
 		}
 		// Kitty/modifyOtherKeys terminals encode plain printables as CSI-u.
 		const decoded = decodeKittyPrintable(keyData);
 		if (decoded !== undefined && isPrintable(decoded)) {
-			this.customText += decoded;
+			tab.customText += decoded;
 			this.repaint();
 		}
 		// Anything else (arrows, unhandled chords) is inert — never inserted