pi-cc-extensions 0.8.8 → 0.8.9

package/extensions/ask-user-question/state/selectors/projections.ts

@@ -0,0 +1,99 @@
+import { MULTI_SUBMIT_LABEL, type MultiSelectViewProps } from "../../view/components/multi-select-view.js";
+import type { OptionListViewProps } from "../../view/components/option-list-view.js";
+import type { PreviewPaneProps } from "../../view/components/preview/preview-pane.js";
+import type { SubmitPickerProps } from "../../view/components/submit-picker.js";
+import type { TabBarProps } from "../../view/components/tab-bar.js";
+import type { DialogProps } from "../../view/dialog-builder.js";
+import { ROW_INTENT_META } from "../row-intent.js";
+import type { GlobalSelector, PerTabSelector } from "./contract.js";
+import { selectConfirmedIndicator } from "./derivations.js";
+
+export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (state, ctx) => {
+	const question = ctx.questions[ctx.i];
+	if (!question) {
+		return {
+			rows: [],
+			other: {
+				active: false,
+				inputMode: false,
+				inputBuffer: ctx.inputBuffer,
+				inputCursorOffset: ctx.inputCursorOffset,
+			},
+			nextActive: false,
+			nextLabel: ROW_INTENT_META.next.label,
+		};
+	}
+	const focused = ctx.activeView === "options";
+	const rows: { checked: boolean; active: boolean }[] = [];
+	for (let i = 0; i < question.options.length; i++) {
+		rows.push({
+			checked: state.multiSelectChecked.has(i),
+			active: focused && i === state.optionIndex,
+		});
+	}
+	const otherActive = focused && state.optionIndex === question.options.length;
+	const nextActive = focused && state.optionIndex === question.options.length + 1;
+	const isLastQuestion = ctx.i === ctx.questions.length - 1;
+	const nextLabel = isLastQuestion ? MULTI_SUBMIT_LABEL : ROW_INTENT_META.next.label;
+	return {
+		rows,
+		other: {
+			active: otherActive,
+			inputMode: state.inputMode,
+			inputBuffer: ctx.inputBuffer,
+			inputCursorOffset: ctx.inputCursorOffset,
+		},
+		nextActive,
+		nextLabel,
+	};
+};
+
+export const selectOptionListProps: PerTabSelector<OptionListViewProps> = (state, ctx) => {
+	const items = ctx.itemsByTab[ctx.i] ?? [];
+	const focused = ctx.activeView === "options";
+	const confirmed = selectConfirmedIndicator(ctx.questions, state.currentTab, state.answers, items);
+	return {
+		selectedIndex: state.optionIndex,
+		focused,
+		inputBuffer: ctx.inputBuffer,
+		inputCursorOffset: ctx.inputCursorOffset,
+		...(confirmed ? { confirmed } : {}),
+	};
+};
+
+export const selectSubmitPickerProps: GlobalSelector<SubmitPickerProps> = (state, ctx) => {
+	const focused = ctx.activeView === "submit";
+	return {
+		rows: [
+			{ active: focused && state.submitChoiceIndex === 0 },
+			{ active: focused && state.submitChoiceIndex === 1 },
+		],
+	};
+};
+
+export const selectPreviewPaneProps: PerTabSelector<PreviewPaneProps> = (state, ctx) => ({
+	notesVisible: state.notesVisible,
+	selectedIndex: state.optionIndex,
+	focused: ctx.activeView === "options",
+	inputMode: state.inputMode,
+});
+
+export const selectTabBarProps: GlobalSelector<TabBarProps> = (state, ctx) => {
+	const tabs = ctx.questions.map((q, i) => ({
+		label: q.header && q.header.length > 0 ? q.header : `Q${i + 1}`,
+		answered: state.answers.has(i),
+		active: i === state.currentTab,
+	}));
+	return {
+		tabs,
+		submit: {
+			active: state.currentTab === ctx.questions.length,
+			allAnswered: state.answers.size === ctx.questions.length && ctx.questions.length > 0,
+		},
+	};
+};
+
+export const selectDialogProps: GlobalSelector<DialogProps> = (state, ctx) => ({
+	state,
+	activePreviewPane: ctx.activePreviewPane,
+});

package/extensions/ask-user-question/state/state-reducer.ts

@@ -0,0 +1,282 @@
+import type { QuestionAnswer, QuestionData, QuestionnaireResult } from "../tool/types.js";
+import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
+import type { QuestionnaireAction } from "./key-router.js";
+import { ROW_INTENT_META } from "./row-intent.js";
+import type { QuestionnaireState } from "./state.js";
+
+/** Session-lifetime constants. No live-component reads — peripheral values live on canonical state. */
+export interface ApplyContext {
+	questions: readonly QuestionData[];
+	itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+}
+
+/**
+ * Declarative side-effects emitted by `reduce`. The runtime executes them after
+ * committing the new state, then asks the props-adapter to re-project. Closed set —
+ * adding an effect requires updating both the union AND the runtime's `runEffect` switch
+ * (compiler-enforced exhaustive). No string-keyed escape hatch.
+ */
+export type Effect =
+	| { kind: "set_input_buffer"; value: string }
+	| { kind: "clear_input_buffer" }
+	| { kind: "set_notes_value"; value: string }
+	| { kind: "set_notes_focused"; focused: boolean }
+	| { kind: "forward_notes_keystroke"; data: string }
+	| { kind: "done"; result: QuestionnaireResult };
+
+export interface ApplyResult {
+	state: QuestionnaireState;
+	effects: readonly Effect[];
+}
+
+function orderedAnswers(state: QuestionnaireState, questions: readonly QuestionData[]): QuestionAnswer[] {
+	const out: QuestionAnswer[] = [];
+	for (let i = 0; i < questions.length; i++) {
+		const a = state.answers.get(i);
+		if (a) out.push(a);
+	}
+	return out;
+}
+
+function syncMultiSelectFromAnswers(
+	answers: ReadonlyMap<number, QuestionAnswer>,
+	questions: readonly QuestionData[],
+	tab: number,
+): ReadonlySet<number> {
+	const q = questions[tab];
+	if (!q?.multiSelect) return new Set();
+	const saved = answers.get(tab);
+	const labels = saved?.selected ?? [];
+	const indices = new Set<number>();
+	for (let i = 0; i < q.options.length; i++) {
+		if (labels.includes(q.options[i]!.label)) indices.add(i);
+	}
+	return indices;
+}
+
+function persistMultiSelectAnswer(state: QuestionnaireState, ctx: ApplyContext): ReadonlyMap<number, QuestionAnswer> {
+	const q = ctx.questions[state.currentTab];
+	if (!q?.multiSelect) return state.answers;
+	const selected: string[] = [];
+	for (let i = 0; i < q.options.length; i++) {
+		if (state.multiSelectChecked.has(i)) selected.push(q.options[i]!.label);
+	}
+	const out = new Map(state.answers);
+	if (selected.length === 0) {
+		out.delete(state.currentTab);
+		return out;
+	}
+	const pendingNotes = state.notesByTab.get(state.currentTab);
+	out.set(state.currentTab, {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "multi",
+		answer: null,
+		selected,
+		...(pendingNotes && pendingNotes.length > 0 ? { notes: pendingNotes } : {}),
+	});
+	return out;
+}
+
+/**
+ * Note text to seed the editor/draft with for a tab. The in-flight side-band store
+ * (`notesByTab`) is authoritative — before an option is confirmed the note lives ONLY
+ * there; `answer.notes` is a mirror written on exit/confirm.
+ */
+function notesValueFor(state: QuestionnaireState, tab: number): string {
+	return state.notesByTab.get(tab) ?? state.answers.get(tab)?.notes ?? "";
+}
+
+function switchTabResult(state: QuestionnaireState, nextTab: number, ctx: ApplyContext): ApplyResult {
+	const notesValue = notesValueFor(state, nextTab);
+	const transitioned: QuestionnaireState = {
+		...state,
+		currentTab: nextTab,
+		optionIndex: 0,
+		inputMode: false,
+		notesVisible: false,
+		submitChoiceIndex: 0,
+		multiSelectChecked: syncMultiSelectFromAnswers(state.answers, ctx.questions, nextTab),
+		notesDraft: notesValue,
+	};
+	return {
+		state: transitioned,
+		effects: [
+			{ kind: "set_notes_focused", focused: false },
+			{ kind: "set_notes_value", value: notesValue },
+		],
+	};
+}
+
+function doneFor(state: QuestionnaireState, ctx: ApplyContext, cancelled: boolean): ApplyResult {
+	const result: QuestionnaireResult = { answers: orderedAnswers(state, ctx.questions), cancelled };
+	return { state, effects: [{ kind: "done", result }] };
+}
+
+/**
+ * Per-kind handler signature: action payload narrows to the matching union member
+ * via `Extract`, so handlers consume fully-typed actions without `as` casts.
+ */
+type Handler<K extends QuestionnaireAction["kind"]> = (
+	state: QuestionnaireState,
+	action: Extract<QuestionnaireAction, { kind: K }>,
+	ctx: ApplyContext,
+) => ApplyResult;
+
+const navHandler: Handler<"nav"> = (state, action, ctx) => {
+	const items = ctx.itemsByTab[state.currentTab] ?? [];
+	const item = items[action.nextIndex];
+	const inputMode = item ? ROW_INTENT_META[item.kind].activatesInputMode : false;
+	const next = { ...state, optionIndex: action.nextIndex, inputMode };
+	if (!inputMode) {
+		return { state: next, effects: [{ kind: "clear_input_buffer" }] };
+	}
+	const prior = state.answers.get(state.currentTab);
+	if (prior?.kind === "custom" && typeof prior.answer === "string") {
+		return { state: next, effects: [{ kind: "set_input_buffer", value: prior.answer }] };
+	}
+	return { state: next, effects: [] };
+};
+
+const tabSwitchHandler: Handler<"tab_switch"> = (state, action, ctx) => switchTabResult(state, action.nextTab, ctx);
+
+const confirmHandler: Handler<"confirm"> = (state, action, ctx) => {
+	let answer = action.answer;
+	if (answer.kind === "option" && answer.answer) {
+		const q = ctx.questions[answer.questionIndex];
+		const matched = q?.options.find((o) => o.label === answer.answer);
+		if (matched?.preview && matched.preview.length > 0) {
+			answer = { ...answer, preview: matched.preview };
+		}
+	}
+	const pendingNotes = state.notesByTab.get(answer.questionIndex);
+	if (pendingNotes && pendingNotes.length > 0) {
+		answer = { ...answer, notes: pendingNotes };
+	}
+	const answers = new Map(state.answers);
+	answers.set(answer.questionIndex, answer);
+	// Custom free-text on a multi-select tab is mutually exclusive with checkbox selections:
+	// clear the checked set immediately so [✔] glyphs vanish on Enter. (A custom answer
+	// carries no `selected` array, so syncMultiSelectFromAnswers keeps it empty on tab-back.)
+	const isCustomMulti = answer.kind === "custom" && ctx.questions[answer.questionIndex]?.multiSelect === true;
+	const next: QuestionnaireState = {
+		...state,
+		answers,
+		...(isCustomMulti ? { multiSelectChecked: new Set<number>() } : {}),
+	};
+	if (action.autoAdvanceTab !== undefined) return switchTabResult(next, action.autoAdvanceTab, ctx);
+	return doneFor(next, ctx, false);
+};
+
+const toggleHandler: Handler<"toggle"> = (state, action, ctx) => {
+	const checked = new Set(state.multiSelectChecked);
+	if (checked.has(action.index)) checked.delete(action.index);
+	else checked.add(action.index);
+	const intermediate: QuestionnaireState = { ...state, multiSelectChecked: checked };
+	const answers = persistMultiSelectAnswer(intermediate, ctx);
+	return { state: { ...intermediate, answers }, effects: [] };
+};
+
+const multiConfirmHandler: Handler<"multi_confirm"> = (state, action, ctx) => {
+	const q = ctx.questions[state.currentTab];
+	if (!q) return { state, effects: [] };
+	const pendingNotes = state.notesByTab.get(state.currentTab);
+	const answers = new Map(state.answers);
+	answers.set(state.currentTab, {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "multi",
+		answer: null,
+		selected: action.selected,
+		...(pendingNotes && pendingNotes.length > 0 ? { notes: pendingNotes } : {}),
+	});
+	const synced: QuestionnaireState = {
+		...state,
+		answers,
+		multiSelectChecked: syncMultiSelectFromAnswers(answers, ctx.questions, state.currentTab),
+	};
+	if (action.autoAdvanceTab !== undefined) return switchTabResult(synced, action.autoAdvanceTab, ctx);
+	return doneFor(synced, ctx, false);
+};
+
+const notesEnterHandler: Handler<"notes_enter"> = (state, _action, _ctx) => {
+	const value = notesValueFor(state, state.currentTab);
+	return {
+		state: { ...state, notesVisible: true, notesDraft: value },
+		effects: [
+			{ kind: "set_notes_value", value },
+			{ kind: "set_notes_focused", focused: true },
+		],
+	};
+};
+
+const notesExitHandler: Handler<"notes_exit"> = (state, _action, _ctx) => {
+	const trimmed = state.notesDraft.trim();
+	const notes = new Map(state.notesByTab);
+	const answers = new Map(state.answers);
+	if (trimmed.length === 0) {
+		notes.delete(state.currentTab);
+		const prev = answers.get(state.currentTab);
+		if (prev?.notes) {
+			const stripped = { ...prev };
+			delete (stripped as { notes?: string }).notes;
+			answers.set(state.currentTab, stripped);
+		}
+	} else {
+		notes.set(state.currentTab, trimmed);
+		const prev = answers.get(state.currentTab);
+		if (prev) answers.set(state.currentTab, { ...prev, notes: trimmed });
+	}
+	return {
+		state: { ...state, notesByTab: notes, answers, notesVisible: false },
+		effects: [{ kind: "set_notes_focused", focused: false }],
+	};
+};
+
+const cancelHandler: Handler<"cancel"> = (s, _a, c) => doneFor(s, c, true);
+const submitHandler: Handler<"submit"> = (s, _a, c) => doneFor(s, c, false);
+const submitNavHandler: Handler<"submit_nav"> = (s, a, _c) => ({
+	state: { ...s, submitChoiceIndex: a.nextIndex },
+	effects: [],
+});
+const notesForwardHandler: Handler<"notes_forward"> = (s, a, _c) => ({
+	state: s,
+	effects: [{ kind: "forward_notes_keystroke", data: a.data }],
+});
+const toggleCollapsedHandler: Handler<"toggle_collapsed"> = (s, _a, _c) => ({
+	state: { ...s, collapsed: !s.collapsed },
+	effects: [],
+});
+const ignoreHandler: Handler<"ignore"> = (s, _a, _c) => ({ state: s, effects: [] });
+
+/**
+ * Compile-time-exhaustive dispatch table. `{ [K in Kind]: Handler<K> }` requires
+ * an entry per union member — adding a new `QuestionnaireAction` variant fails to
+ * compile here until a handler is registered, mirroring the `Record<RowKind, …>`
+ * pattern used by `ROW_INTENT_META`.
+ */
+const HANDLERS: { [K in QuestionnaireAction["kind"]]: Handler<K> } = {
+	nav: navHandler,
+	tab_switch: tabSwitchHandler,
+	confirm: confirmHandler,
+	toggle: toggleHandler,
+	multi_confirm: multiConfirmHandler,
+	cancel: cancelHandler,
+	notes_enter: notesEnterHandler,
+	notes_exit: notesExitHandler,
+	notes_forward: notesForwardHandler,
+	submit: submitHandler,
+	submit_nav: submitNavHandler,
+	toggle_collapsed: toggleCollapsedHandler,
+	ignore: ignoreHandler,
+};
+
+/**
+ * Pure reducer: (state, action, ctx) → (state, Effect[]). Mirrors `rpiv-todo`'s `applyTaskMutation`.
+ * Delegates to `HANDLERS` — per-kind handlers above are pure, named, and individually testable.
+ * `ignore` is also handled outside the reducer by `handleIgnoreInline` in the runtime fast path.
+ */
+export function reduce(state: QuestionnaireState, action: QuestionnaireAction, ctx: ApplyContext): ApplyResult {
+	const handler = HANDLERS[action.kind] as Handler<typeof action.kind>;
+	return handler(state, action as never, ctx);
+}

package/extensions/ask-user-question/state/state.ts

@@ -0,0 +1,49 @@
+import type { QuestionAnswer, QuestionData } from "../tool/types.js";
+import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
+
+/**
+ * Canonical state for the questionnaire dialog. Single source of truth — both the
+ * dispatcher (`routeKey`) and the view layer read this same shape.
+ */
+export interface QuestionnaireState {
+	currentTab: number;
+	optionIndex: number;
+	inputMode: boolean;
+	notesVisible: boolean;
+	answers: ReadonlyMap<number, QuestionAnswer>;
+	multiSelectChecked: ReadonlySet<number>;
+	/**
+	 * Pre-answer notes side-band, keyed by tab index. Decoupled from `answers` so adding
+	 * notes does NOT mark a question answered (the Submit-tab missing-check would falsely
+	 * pass otherwise). Merged into the answer at confirm time.
+	 */
+	notesByTab: ReadonlyMap<number, string>;
+	/** Focused row in the Submit-tab picker (0 = Submit, 1 = Cancel). Reset on tab switch. */
+	submitChoiceIndex: number;
+	/** Canonical mirror of the in-flight notes editor; runtime mirrors after `forward_notes_keystroke`. */
+	notesDraft: string;
+	/**
+	 * Collapsed mode: the questionnaire shrinks to one focused hint row in the
+	 * temporary editor slot, returning the remaining space to the transcript.
+	 */
+	collapsed: boolean;
+}
+
+/**
+ * Per-tick context the dispatcher needs alongside canonical state. Held separately
+ * because `keybindings` / `inputBuffer` must never reach view setProps consumers.
+ */
+export interface QuestionnaireRuntime {
+	keybindings: { matches(data: string, name: string): boolean };
+	inputBuffer: string;
+	questions: readonly QuestionData[];
+	isMulti: boolean;
+	currentItem: WrappingSelectItem | undefined;
+	items: readonly WrappingSelectItem[];
+	/**
+	 * Key spec for the collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. Resolved
+	 * from `AskUserQuestionConfig.collapseKey` (or the package default). When `"off"`,
+	 * the collapse shortcut is disabled.
+	 */
+	collapseKey: string;
+}

package/extensions/ask-user-question/tool/format-answer.ts

@@ -0,0 +1,29 @@
+import type { QuestionAnswer } from "./types.js";
+
+/**
+ * Placeholder for empty / null answer text. Used uniformly across both variants — the
+ * earlier `(no answer)` fallback in the dialog summary was accidental drift; tests pin
+ * `(no input)` only.
+ */
+export const NO_INPUT_PLACEHOLDER = "(no input)";
+
+export type FormatAnswerVariant = "summary" | "envelope";
+
+/**
+ * Format a `QuestionAnswer` to its scalar string form. `variant` is currently unused
+ * across all branches (the chat branch that once distinguished `envelope` from
+ * `summary` has been removed); it is retained on the signature for stability.
+ * The `kind: "custom"` empty-string handling and the option fallback both unify on
+ * `NO_INPUT_PLACEHOLDER`. Switch is exhaustive — non-`void` return enforces every
+ * variant is handled.
+ */
+export function formatAnswerScalar(a: QuestionAnswer, _variant: FormatAnswerVariant): string {
+	switch (a.kind) {
+		case "multi":
+			return a.selected && a.selected.length > 0 ? a.selected.join(", ") : NO_INPUT_PLACEHOLDER;
+		case "custom":
+			return a.answer && a.answer.length > 0 ? a.answer : NO_INPUT_PLACEHOLDER;
+		case "option":
+			return a.answer ?? NO_INPUT_PLACEHOLDER;
+	}
+}

package/extensions/ask-user-question/tool/response-envelope.ts

@@ -0,0 +1,47 @@
+import { formatAnswerScalar } from "./format-answer.js";
+import type { QuestionAnswer, QuestionnaireResult, QuestionParams } from "./types.js";
+
+export const DECLINE_MESSAGE = "User declined to answer questions";
+export const ENVELOPE_PREFIX = "User has answered your questions:";
+export const ENVELOPE_SUFFIX = "You can now continue with the user's answers in mind.";
+
+/**
+ * Map a `QuestionnaireResult` (or null/cancelled) to the LLM-facing tool envelope.
+ * Pure of `(result, params)`; cancelled and "no segments" both fall to `DECLINE_MESSAGE`
+ * so the model sees a single canonical "didn't answer" signal regardless of why.
+ */
+export function buildQuestionnaireResponse(result: QuestionnaireResult | null | undefined, params: QuestionParams) {
+	if (!result || result.cancelled) {
+		return buildToolResult(DECLINE_MESSAGE, {
+			answers: result?.answers ?? [],
+			cancelled: true,
+		});
+	}
+	const segments: string[] = [];
+	for (let i = 0; i < params.questions.length; i++) {
+		const a = result.answers.find((x) => x.questionIndex === i);
+		if (a) segments.push(buildAnswerSegment(a));
+	}
+	if (segments.length === 0) {
+		return buildToolResult(DECLINE_MESSAGE, { answers: result.answers, cancelled: true });
+	}
+	return buildToolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, result);
+}
+
+/**
+ * Format a single answer segment for the envelope. Pure of `a`. The `"Q"="A"` shape and
+ * the optional `selected preview:` / `user notes:` suffixes are pinned by envelope tests.
+ */
+export function buildAnswerSegment(a: QuestionAnswer): string {
+	const parts: string[] = [`"${a.question}"="${formatAnswerScalar(a, "envelope")}"`];
+	if (a.preview && a.preview.length > 0) parts.push(`selected preview: ${a.preview}`);
+	if (a.notes && a.notes.length > 0) parts.push(`user notes: ${a.notes}`);
+	return `${parts.join(". ")}.`;
+}
+
+export function buildToolResult(text: string, details: QuestionnaireResult) {
+	return {
+		content: [{ type: "text" as const, text }],
+		details,
+	};
+}

package/extensions/ask-user-question/tool/types.ts

@@ -0,0 +1,145 @@
+import { type Static, Type } from "typebox";
+import { LABELS_BY_KIND, ROW_INTENT_META } from "../state/row-intent.js";
+
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER_LENGTH = 16;
+export const MAX_LABEL_LENGTH = 60;
+
+/**
+ * User-facing labels for the three runtime sentinel rows, keyed by their
+ * `WrappingSelectItem.kind` discriminator. Sourced from
+ * `ROW_INTENT_META` via `LABELS_BY_KIND` (`row-intent.ts`) — single source of
+ * truth. Adding a new sentinel requires extending the `WrappingSelectItem`
+ * union AND adding an entry to `ROW_INTENT_META`; this map then auto-extends.
+ */
+export const SENTINEL_LABELS = LABELS_BY_KIND;
+
+export type SentinelKind = keyof typeof SENTINEL_LABELS;
+export type SentinelLabel = (typeof SENTINEL_LABELS)[SentinelKind];
+
+/**
+ * Labels reserved for Pi-internal sentinels — authoring an option with any
+ * of these labels triggers the `reserved_label` runtime guard. Two of the
+ * three come from `ROW_INTENT_META` (the runtime kinds); `"Other"` is
+ * reserved for CC parity only (the model is conditioned to reach for
+ * "Other" in CC; we reject it so the runtime sentinel is the single source
+ * of truth) and has no runtime kind.
+ *
+ * Reserved unconditionally — every question mode rejects these labels, even
+ * when a given runtime sentinel is not appended in that mode.
+ *
+ * Order is pinned by `types.test.ts:292` — keep the explicit
+ * `["Other", other, next]` literal so consumers using
+ * `RESERVED_LABELS[i]` indexing or `Set` membership see no behavior change.
+ */
+export const RESERVED_LABELS = ["Other", ROW_INTENT_META.other.label, ROW_INTENT_META.next.label] as const;
+export type ReservedLabel = (typeof RESERVED_LABELS)[number];
+
+export const OptionSchema = Type.Object({
+	label: Type.String({
+		maxLength: MAX_LABEL_LENGTH,
+		description: `MAX ${MAX_LABEL_LENGTH} CHARACTERS — hard limit, requests over the limit are rejected. The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.`,
+	}),
+	description: Type.String({
+		description:
+			"Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
+	}),
+	preview: Type.Optional(
+		Type.String({
+			description:
+				"Optional preview content rendered when this option is focused. Use for mockups, code snippets, or visual comparisons that help users compare options. See the tool description for the expected content format.",
+		}),
+	),
+});
+
+export const QuestionSchema = Type.Object({
+	question: Type.String({
+		description:
+			'The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: "Which library should we use for date formatting?" If multiSelect is true, phrase it accordingly, e.g. "Which features do you want to enable?"',
+	}),
+	header: Type.String({
+		maxLength: MAX_HEADER_LENGTH,
+		description: `MAX ${MAX_HEADER_LENGTH} CHARACTERS — hard limit, requests over the limit are rejected. Very short chip/tag shown next to the question. Examples: "Auth method", "Library", "Approach".`,
+	}),
+	options: Type.Array(OptionSchema, {
+		minItems: MIN_OPTIONS,
+		maxItems: MAX_OPTIONS,
+		description:
+			"The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). The 'Type something.' row is appended automatically — do NOT author it.",
+	}),
+	multiSelect: Type.Optional(
+		Type.Boolean({
+			default: false,
+			description:
+				"Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
+		}),
+	),
+});
+
+export const QuestionsSchema = Type.Array(QuestionSchema, {
+	minItems: 1,
+	maxItems: MAX_QUESTIONS,
+	description: "Questions to ask the user (1-4 questions)",
+});
+
+export const QuestionParamsSchema = Type.Object({
+	questions: QuestionsSchema,
+});
+
+export type OptionData = Static<typeof OptionSchema>;
+export type QuestionData = Static<typeof QuestionSchema>;
+export type QuestionParams = Static<typeof QuestionParamsSchema>;
+
+/**
+ * Answer-intent discriminated union. `kind` is the single discriminator —
+ * pre-1.0.3 boolean flags have been removed (see `banned-flags.test.ts`).
+ * Mirrors the row-side `WrappingSelectItem.kind` vocabulary where possible;
+ * `multi` is the multi-select variant (no row-side analog).
+ *
+ * Variant semantics:
+ * - `option`: user picked one of the author-defined options. `answer` is the option's label.
+ * - `custom`: user typed free-text via the "Type something." row. `answer` is the typed text or null.
+ * - `multi`: user committed multi-select choices. `selected` carries chosen labels; `answer` is null.
+ */
+export interface QuestionAnswer {
+	questionIndex: number;
+	question: string;
+	kind: "option" | "custom" | "multi";
+	answer: string | null;
+	selected?: string[];
+	notes?: string;
+	/**
+	 * Markdown text from the matched option's `preview` field, populated only
+	 * when the user lands on a single-select option carrying a `preview`.
+	 * Used by `buildQuestionnaireResponse` to echo `selected preview: <preview>`
+	 * into the LLM-facing envelope. Undefined for multi-select and custom-text
+	 * (`kind: "custom"`) answers.
+	 */
+	preview?: string;
+}
+
+export type QuestionnaireError =
+	| "no_ui"
+	| "no_custom_ui"
+	| "no_questions"
+	| "empty_options"
+	| "too_many_questions"
+	| "duplicate_question"
+	| "duplicate_option_label"
+	| "reserved_label"
+	| "session_load_failed"
+	| "stale_module_cache";
+
+export interface QuestionnaireResult {
+	answers: QuestionAnswer[];
+	cancelled: boolean;
+	error?: QuestionnaireError;
+}
+
+export function isQuestionnaireResult(value: unknown): value is QuestionnaireResult {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return Array.isArray(v.answers) && typeof v.cancelled === "boolean";
+}