@garygentry/feature-forge 0.2.13 → 0.3.0

package/adapters/pi/extensions/ask-user-question/state/selectors/derivations.ts

@@ -0,0 +1,42 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/selectors/derivations.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { QuestionAnswer, QuestionData } from "../../tool/types.js";
+import type { WrappingSelectItem } from "../../view/components/wrapping-select.js";
+
+/**
+ * Which row in the active tab should be marked as "previously confirmed"? Drives the
+ * `WrappingSelect` confirmed-row indicator (label + ` ✔`) when the user navigates back
+ * to a question they already answered. Returns `undefined` when no marker should be drawn —
+ * multi-select handles its own `[✔]` boxes via `multiSelectChecked`, and a missing/non-matching
+ * answer (defensive) silently skips the marker.
+ */
+export function selectConfirmedIndicator(
+	questions: readonly QuestionData[],
+	currentTab: number,
+	answers: ReadonlyMap<number, QuestionAnswer>,
+	items: readonly WrappingSelectItem[],
+): { index: number; labelOverride?: string } | undefined {
+	const q = questions[currentTab];
+	if (!q || q.multiSelect === true) return undefined;
+	const prior = answers.get(currentTab);
+	if (!prior) return undefined;
+	if (prior.kind === "custom") {
+		const otherIndex = items.findIndex((it) => it.kind === "other");
+		if (otherIndex < 0) return undefined;
+		return { index: otherIndex, labelOverride: prior.answer ?? "" };
+	}
+	if (prior.kind !== "option" || typeof prior.answer !== "string") return undefined;
+	const index = items.findIndex((it) => it.kind === "option" && it.label === prior.answer);
+	if (index < 0) return undefined;
+	return { index };
+}
+
+/**
+ * Index of the preview pane to display for the current tab. The Submit tab (currentTab ===
+ * questions.length) reuses the last question's pane purely for layout — the strategy
+ * machinery picks the right body component independently. Defensive against `totalQuestions === 0`.
+ */
+export function selectActivePreviewPaneIndex(currentTab: number, totalQuestions: number): number {
+	if (totalQuestions <= 0) return 0;
+	return Math.min(currentTab, totalQuestions - 1);
+}

package/adapters/pi/extensions/ask-user-question/state/selectors/focus.ts

@@ -0,0 +1,19 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/selectors/focus.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { ActiveView } from "../../view/stateful-view.js";
+
+/**
+ * Discriminated focus selector — single source of truth for "which view owns
+ * focus this tick?" Priority order matches the dispatcher cascade
+ * (`key-router.ts`) and the reducer's defensive clears (`state-reducer.ts`).
+ *
+ * Priority: notes > submit > options.
+ */
+export function selectActiveView(
+	state: { notesVisible: boolean; currentTab: number },
+	totalQuestions: number,
+): ActiveView {
+	if (state.notesVisible) return "notes";
+	if (state.currentTab === totalQuestions) return "submit";
+	return "options";
+}

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

@@ -0,0 +1,101 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/selectors/projections.ts
+// Regenerate with: python3 scripts/build-adapters.py
+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 { displayLabel } from "../i18n-bridge.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: displayLabel("next"),
+		};
+	}
+	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 : displayLabel("next");
+	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/adapters/pi/extensions/ask-user-question/state/state-reducer.ts

@@ -0,0 +1,292 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/state-reducer.ts
+// Regenerate with: python3 scripts/build-adapters.py
+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 }
+	/**
+	 * Tell the session to hide or show its underlying overlay. Emitted by the
+	 * `toggle_collapsed` action so the runtime can call `OverlayHandle.setHidden(...)`,
+	 * which lets other overlay-aware consumers (e.g. `pi-station`) see the questionnaire
+	 * as truly hidden and resume normal chat scroll while the user reads the transcript
+	 * behind the modal.
+	 */
+	| { kind: "set_overlay_hidden"; hidden: boolean }
+	| { 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: [{ kind: "set_overlay_hidden", hidden: !s.collapsed }],
+});
+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/adapters/pi/extensions/ask-user-question/state/state.ts

@@ -0,0 +1,55 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/state.ts
+// Regenerate with: python3 scripts/build-adapters.py
+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 a single hint row so the agent transcript
+	 * behind the bottom-anchored overlay becomes readable. Toggled by `Ctrl+]` from any state;
+	 * while true, every keystroke except cancel is swallowed (see `routeKey`). The overlay
+	 * stays focused so the expand key never falls through to an underlying overlay (e.g.
+	 * `/btw`) — that focus-restore property is the entire reason we render a collapsed row
+	 * instead of calling `OverlayHandle.setHidden(true)`.
+	 */
+	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/adapters/pi/extensions/ask-user-question/tool/format-answer.ts

@@ -0,0 +1,31 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/tool/format-answer.ts
+// Regenerate with: python3 scripts/build-adapters.py
+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/adapters/pi/extensions/ask-user-question/tool/response-envelope.ts

@@ -0,0 +1,49 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/tool/response-envelope.ts
+// Regenerate with: python3 scripts/build-adapters.py
+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,
+	};
+}