@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/extensions/ask-user-question/ask-user-question.ts

@@ -0,0 +1,298 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/ask-user-question.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
+import { loadConfig, resolveCollapseKey, validateGuidanceFields } from "./config.js";
+import {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+} from "./events.js";
+// Static import is fine — rpc-fallback pulls only types + the i18n bridge,
+// none of the ~560ms TUI render graph that QuestionnaireSession lazy-loads.
+import { hasDialogUI, runRpcQuestionnaire } from "./rpc-fallback.js";
+import { displayLabel } from "./state/i18n-bridge.js";
+import { sentinelsToAppend } from "./state/row-intent.js";
+import { buildQuestionnaireResponse, buildToolResult } from "./tool/response-envelope.js";
+import {
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	type QuestionData,
+	type QuestionnaireError,
+	type QuestionnaireResult,
+	type QuestionParams,
+	QuestionParamsSchema,
+} from "./tool/types.js";
+import { validateQuestionnaire } from "./tool/validate-questionnaire.js";
+import type { WrappingSelectItem } from "./view/components/wrapping-select.js";
+
+function emitAskUserPromptEvent(pi: ExtensionAPI, params: QuestionParams): void {
+	const payload: AskUserPromptEventPayload = {
+		questions: params.questions.map((q) => ({
+			question: q.question,
+			header: q.header,
+			multiSelect: q.multiSelect ?? false,
+			options: q.options.map((o) => ({
+				label: o.label,
+				description: o.description,
+				hasPreview: typeof o.preview === "string" && o.preview.length > 0,
+			})),
+		})),
+	};
+	pi.events.emit(ASK_USER_PROMPT_EVENT, payload);
+}
+
+function emitAskUserBlockedEvent(pi: ExtensionAPI, active: boolean): void {
+	const payload: AskUserBlockedEventPayload = { active };
+	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
+}
+
+/** Canonical tool name — single source of truth shared with the reconcile module. */
+export const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion"; // FEATURE-FORGE VENDOR PATCH: Claude-parity name
+
+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, e.g. RPC/ACP hosts such as Zed or Paseo). 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 ERROR_SESSION_LOAD_FAILED =
+	"Error: the questionnaire UI failed to load — the host's installed dependencies were likely replaced or removed on disk while Pi was running (e.g. a package-manager install touched the store). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, and tell the user that restoring this tool requires repairing the install if needed and restarting Pi.";
+
+const ERROR_STALE_MODULE_CACHE =
+	"Error: the questionnaire UI cannot load — the host's module cache went stale after an earlier failed load (typically dependencies replaced on disk mid-session). This is unrecoverable within the current Pi process. The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, and tell the user to restart Pi to restore this tool.";
+
+/** Delay before the background session-graph pre-warm; mirrors rpiv-workflow's /wf prewarm. */
+export const PREWARM_DELAY_MS = 2000;
+
+type SessionModule = typeof import("./state/questionnaire-session.js");
+
+type SessionLoad =
+	| { ok: true; module: SessionModule }
+	| { ok: false; error: Extract<QuestionnaireError, "session_load_failed" | "stale_module_cache">; message: string };
+
+/**
+ * Lazy-load the ~560ms QuestionnaireSession view/TUI render graph, guarding
+ * the two failure shapes of issue #107. Pi's jiti loader registers a module in
+ * its graph cache BEFORE evaluating the body and does not evict it when
+ * evaluation throws (jiti 2.7.0), so one failed load — e.g. `pnpm install
+ * --force` replacing the store entry mid-session — leaves every later import
+ * of this specifier resolving to a namespace without the class. That state is
+ * unrecoverable in-process (cache-busting specifiers fail jiti resolution);
+ * both branches therefore return an LLM-facing envelope that names the restart
+ * requirement instead of leaking a bare "not a constructor" TypeError.
+ */
+export async function loadQuestionnaireSession(): Promise<SessionLoad> {
+	let mod: SessionModule;
+	try {
+		mod = await import("./state/questionnaire-session.js");
+	} catch (e) {
+		const cause = e instanceof Error ? e.message : String(e);
+		return { ok: false, error: "session_load_failed", message: `${ERROR_SESSION_LOAD_FAILED} (cause: ${cause})` };
+	}
+	if (typeof mod.QuestionnaireSession !== "function") {
+		const keys = JSON.stringify(Object.keys(mod));
+		return {
+			ok: false,
+			error: "stale_module_cache",
+			message: `${ERROR_STALE_MODULE_CACHE} (resolved namespace keys: ${keys})`,
+		};
+	}
+	return { ok: true, module: mod };
+}
+
+export function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {
+	const items: WrappingSelectItem[] = question.options.map((o) => ({
+		kind: "option",
+		label: o.label,
+		description: o.description,
+	}));
+	for (const kind of sentinelsToAppend(question)) {
+		items.push({ kind, label: displayLabel(kind) });
+	}
+	return items;
+}
+
+export const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;
+export const DEFAULT_PROMPT_GUIDELINES: string[] = [
+	`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
+	`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer via the automatically appended "Type something." row on every question, or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.`,
+	`Set multiSelect: true when multiple answers are valid. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. The "Type something." row is appended to every question; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column. If you recommend a specific option, make that the first option and append "(Recommended)" to its label.`,
+	"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.",
+];
+
+export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
+	const guidance = validateGuidanceFields(loadConfig().guidance);
+	pi.registerTool({
+		name: ASK_USER_QUESTION_TOOL_NAME,
+		label: "Ask User Question",
+		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:
+- Users can type a custom answer via the automatically appended "Type something." row on every question or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
+- Use multiSelect: true when multiple answers are valid. The "Type something." row is available on every question, including when options carry a \`preview\`; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column.
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label.
+
+Preview feature:
+Use the optional \`preview\` field on options when presenting concrete artifacts that users need to visually compare:
+- ASCII mockups of UI layouts or components
+- Code snippets showing different implementations
+- Diagram variations
+- Configuration examples
+
+Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,
+		promptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,
+		promptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,
+		parameters: QuestionParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const typed = params as unknown as QuestionParams;
+			if (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: "no_ui" });
+
+			const validation = validateQuestionnaire(typed);
+			if (!validation.ok) {
+				return buildToolResult(validation.message, {
+					answers: [],
+					cancelled: true,
+					error: validation.error,
+				});
+			}
+
+			// Emit event for external listeners (e.g., notification plugins)
+			emitAskUserPromptEvent(pi, typed);
+
+			// RPC hosts (VSCode pendant, ACP clients like Zed/Paseo — issue #78):
+			// ui.custom() cannot render there, but the select/input dialog
+			// sub-protocol works. Hosts that advertise ctx.mode (pi ≥0.79) route to
+			// the sequential dialog walker up front, skipping the TUI render-graph
+			// import entirely; RPC builds that predate ctx.mode are caught by the
+			// custom()-resolved-undefined backstop below. See ./rpc-fallback.ts.
+			if ((ctx as { mode?: string }).mode === "rpc" && hasDialogUI(ctx.ui)) {
+				emitAskUserBlockedEvent(pi, true);
+				try {
+					return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
+				} finally {
+					emitAskUserBlockedEvent(pi, false);
+				}
+			}
+
+			const itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));
+
+			// Lazy — QuestionnaireSession pulls the ~560ms view/TUI render graph;
+			// load it only when the tool runs, not at extension registration.
+			const sessionLoad = await loadQuestionnaireSession();
+			if (!sessionLoad.ok) {
+				return buildToolResult(sessionLoad.message, { answers: [], cancelled: true, error: sessionLoad.error });
+			}
+			const { QuestionnaireSession } = sessionLoad.module;
+			// Resolve the collapse/expand key spec from config. Default is `ctrl+]`; users
+			// with non-US layouts (e.g. Latin American, where `]` is shifted) can override
+			// via the `collapseKey` config field. `resolveCollapseKey` also accepts the
+			// sentinel value `"off"` to disable the shortcut entirely.
+			const collapseKey = resolveCollapseKey(loadConfig());
+
+			// Capture the overlay handle so the session can call `setHidden()` when the
+			// user toggles collapse, and register a raw terminal input listener for the
+			// same key so the toggle still works while the overlay is hidden (pi-tui does
+			// not route input to a hidden overlay's `component.handleInput`).
+			const sessionRef: {
+				current: import("./state/questionnaire-session.js").QuestionnaireSession | null;
+			} = { current: null };
+			const overlayHandleRef: { current: import("@earendil-works/pi-tui").OverlayHandle | undefined } = {
+				current: undefined,
+			};
+			let hasAnnouncedHide = false;
+			let removeOverlayInputListener: (() => void) | undefined;
+
+			if (collapseKey !== "off" && typeof ctx.ui.onTerminalInput === "function") {
+				removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
+					const handle = overlayHandleRef.current;
+					if (!handle) return undefined;
+					// Only act while the questionnaire is hidden (its handleInput is
+					// unreachable) or actually focused. When some other overlay is on
+					// top (e.g. `/btw`), leave the keystroke to that overlay instead of
+					// toggling the questionnaire from underneath it.
+					if (!handle.isHidden() && !handle.isFocused()) return undefined;
+					if (!matchesKey(data, collapseKey as Parameters<typeof matchesKey>[1])) return undefined;
+					// Kitty-protocol terminals report press, repeat, and release separately.
+					// Toggle only on the initial press so a tap does not immediately reopen
+					// the overlay and a held key does not toggle it repeatedly.
+					if (isKeyRelease(data) || isKeyRepeat(data)) return { consume: true };
+					sessionRef.current?.toggleCollapsedExternal();
+					if (handle.isHidden() && !hasAnnouncedHide) {
+						hasAnnouncedHide = true;
+						ctx.ui.notify?.(`ask_user_question hidden — press ${collapseKey} to reopen`, "info");
+					}
+					return { consume: true };
+				});
+			}
+
+			emitAskUserBlockedEvent(pi, true);
+			try {
+				const result = await ctx.ui.custom<QuestionnaireResult>(
+					(tui, theme, _kb, done) => {
+						const session = new QuestionnaireSession({
+							tui,
+							theme,
+							params: typed,
+							itemsByTab,
+							done,
+							collapseKey,
+						});
+						sessionRef.current = session;
+						return session.component;
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							anchor: "bottom-center",
+							width: "100%",
+							maxHeight: "100%",
+							margin: { left: 0, right: 0, bottom: 0 },
+						},
+						onHandle: (handle) => {
+							overlayHandleRef.current = handle;
+							sessionRef.current?.setOverlayHandle(handle);
+						},
+					},
+				);
+
+				// A TUI questionnaire ALWAYS resolves a QuestionnaireResult (cancel
+				// included — state-reducer emits `{ answers, cancelled }`), so
+				// `undefined` uniquely means "host cannot render", never "user
+				// declined". RPC builds that predate ctx.mode land here: run the
+				// dialog walker when the host has the primitives; otherwise tell the
+				// model the user never saw the questions.
+				if (result === undefined) {
+					if (hasDialogUI(ctx.ui)) {
+						return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
+					}
+					return buildToolResult(ERROR_NO_CUSTOM_UI, { answers: [], cancelled: true, error: "no_custom_ui" });
+				}
+
+				return buildQuestionnaireResponse(result, typed);
+			} finally {
+				removeOverlayInputListener?.();
+				emitAskUserBlockedEvent(pi, false);
+			}
+		},
+	});
+
+	// Pre-warm the lazy session graph once startup settles (#107). A graph
+	// evaluated while the paths Pi resolved at boot still exist stays in memory
+	// for the process lifetime, so later on-disk dependency churn (e.g. `pnpm
+	// install --force` replacing the store mid-session) can no longer poison
+	// jiti's graph cache. Swallowed failure is safe: the first real call
+	// re-imports and surfaces it through loadQuestionnaireSession's structured
+	// envelope. unref keeps the timer from holding a non-TUI embedder's process
+	// open.
+	const timer = setTimeout(() => void loadQuestionnaireSession().catch(() => undefined), PREWARM_DELAY_MS);
+	timer.unref?.();
+}
+
+export { buildQuestionnaireResponse, buildToolResult };

package/adapters/pi/extensions/ask-user-question/config.ts

@@ -0,0 +1,78 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/config.ts
+// Regenerate with: python3 scripts/build-adapters.py
+// FEATURE-FORGE VENDOR PATCH: upstream imports these from @juicesharp/rpiv-config.
+import type { GuidanceFields } from "./vendor-config-shim.js";
+import { loadJsonConfigWithLegacyFallback, validateGuidanceFields } from "./vendor-config-shim.js";
+
+/** Key spec for the overlay collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
+export type CollapseKeySpec = string;
+
+export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+]";
+export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
+
+export interface AskUserQuestionConfig {
+	guidance?: GuidanceFields;
+	/**
+	 * Key spec for the collapse/expand shortcut, in the same format as pi-coding-agent
+	 * keybinding ids (`modifier+key`, e.g. `ctrl+]`, `alt+o`, `ctrl+shift+h`). Defaults
+	 * to `"ctrl+]"`. Set this to a key that is reachable on your keyboard layout — Latin
+	 * American layouts (where `]` is on the shifted layer) often want `"ctrl+}"` instead.
+	 * Pass `"off"` to disable the collapse shortcut entirely.
+	 */
+	collapseKey?: CollapseKeySpec;
+}
+
+// Named keys accepted by pi-tui's `matchesKey` (keys.js switch on the parsed base key).
+// parseKeyId lowercases the id before matching, so lowercase spellings are canonical.
+const SPECIAL_KEYS = new Set([
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	...Array.from({ length: 12 }, (_, i) => `f${i + 1}`),
+]);
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+function isValidCollapseKeySpec(spec: string): boolean {
+	// Mirror pi-tui's KeyId grammar strictly: zero or more distinct modifiers, then a
+	// base key that is a single printable character or a named special key. A loose
+	// check is not enough — pi-tui's `parseKeyId` takes the LAST `+`-part as the key
+	// and ignores unknown parts, so a typo like `ctr+]` would silently match every
+	// bare `]` keypress (and the raw terminal listener would consume them globally).
+	if (!spec) return false;
+	if (spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+	const parts = spec.split("+");
+	const base = parts[parts.length - 1] ?? "";
+	const modifiers = parts.slice(0, -1);
+	if (modifiers.length !== new Set(modifiers).size) return false;
+	if (!modifiers.every((m) => MODIFIERS.has(m))) return false;
+	return base.length === 1 ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base) : SPECIAL_KEYS.has(base);
+}
+
+export function resolveCollapseKey(config: Pick<AskUserQuestionConfig, "collapseKey">): CollapseKeySpec {
+	const raw = config.collapseKey?.trim().toLowerCase();
+	if (raw === undefined || raw === "") return DEFAULT_COLLAPSE_KEY;
+	if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+	return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
+}
+
+export function loadConfig(): AskUserQuestionConfig {
+	return loadJsonConfigWithLegacyFallback<AskUserQuestionConfig>("rpiv-ask-user-question");
+}
+
+export { validateGuidanceFields };

package/adapters/pi/extensions/ask-user-question/events.ts

@@ -0,0 +1,57 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/events.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * Public event contract for @juicesharp/rpiv-ask-user-question.
+ *
+ * STABILITY POLICY — applies to every event in the `rpiv:*` namespace.
+ *
+ *   1. Channel names are immutable. Once shipped, never rename.
+ *   2. Payload changes are append-only. Listeners MUST tolerate unknown
+ *      fields. New fields ship as optional (`?:`).
+ *   3. Breaking changes (rename, retype, remove a field; change emission
+ *      semantics) require a NEW channel, e.g. `rpiv:ask-user:prompt.v2`,
+ *      with dual-emit during a deprecation window.
+ *   4. No `version` field inside payloads. Version via channel name only.
+ *   5. Payloads must be JSON-safe: primitives, arrays, plain objects.
+ *      No Set/Map/Date/class instances — payloads must survive JSON
+ *      serialization when listeners forward them across process or
+ *      network boundaries.
+ *
+ * Naming: `rpiv:<package-or-tool>:<phase>`, lowercase, hyphen-separated.
+ * Aligns with Pi's `"my-extension:status"` example and UniPi's `unipi:*`.
+ */
+
+export const ASK_USER_PROMPT_EVENT = "rpiv:ask-user:prompt" as const;
+
+export interface AskUserPromptEventPayload {
+	questions: ReadonlyArray<AskUserPromptQuestion>;
+}
+
+/**
+ * Emitted while the questionnaire is awaiting user input (TUI `ui.custom` and
+ * RPC dialog walker). Cleared with `{ active: false }` in `finally` so listeners
+ * can distinguish blocked-on-human from working.
+ */
+export const ASK_USER_BLOCKED_EVENT = "rpiv:ask-user:blocked" as const;
+
+export interface AskUserBlockedEventPayload {
+	/** True while input is awaited; false when the wait ends (answer, cancel, or error). */
+	active: boolean;
+}
+
+export interface AskUserPromptQuestion {
+	/** The full question text, exactly as the agent authored it. */
+	question: string;
+	/** The short chip/tag shown next to the question. */
+	header: string;
+	/** True iff the user may pick multiple options. Normalized from optional. */
+	multiSelect: boolean;
+	options: ReadonlyArray<AskUserPromptOption>;
+}
+
+export interface AskUserPromptOption {
+	label: string;
+	description: string;
+	/** True iff the option carries rich preview content (content not shipped). */
+	hasPreview: boolean;
+}

package/adapters/pi/extensions/ask-user-question/index.ts

@@ -0,0 +1,61 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/index.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * rpiv-ask-user-question — Pi extension. Registers the `ask_user_question`
+ * tool: a structured option selector with an automatically appended
+ * `Type something.` custom-answer row.
+ *
+ * Sentinel labels and TUI chrome strings localize at render time via the i18n
+ * bridge. Strings are registered with rpiv-i18n here, once, at module init —
+ * but only when the SDK is actually installed. If `@juicesharp/rpiv-i18n` is
+ * missing (standalone install of just this package), the dynamic-load shim
+ * no-ops and the bridge's `t(key, fallback)` returns the inline English literal
+ * at every call site. The extension stays online either way.
+ *
+ * Adding a locale: drop `locales/<code>.json` next to en.json (mirroring the
+ * key set). No edit needed here — `registerLocalesFromDir` iterates
+ * `SUPPORTED_LOCALES` from the SDK. See `@juicesharp/rpiv-i18n` README →
+ * "Contributing translations" for the full convention.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { dirname } from "node:path"; // FEATURE-FORGE VENDOR PATCH
+import { fileURLToPath } from "node:url"; // FEATURE-FORGE VENDOR PATCH
+import { registerAskUserQuestionTool } from "./ask-user-question.js";
+import { registerAskUserQuestionReconciler } from "./reconcile.js";
+import { I18N_NAMESPACE } from "./state/i18n-bridge.js";
+
+type I18nLoader = {
+	registerLocalesFromDir: (namespace: string, packageUrl: string, options?: { label?: string }) => void;
+};
+
+// Dynamic import keeps `@juicesharp/rpiv-i18n` a soft optional peer: when the
+// SDK is installed alongside this package the strings register and
+// `/languages` flips them live; when it isn't, the import rejects here, we
+// no-op, and the bridge's English-fallback shim keeps the extension online.
+//
+// The `/loader` subpath is used instead of the SDK entry so the i18n-ui +
+// pi-tui modules are not pulled into our load graph just to register strings.
+try {
+	const sdk = (await import("@juicesharp/rpiv-i18n/loader")) as I18nLoader;
+	sdk.registerLocalesFromDir(I18N_NAMESPACE, import.meta.url, { label: "rpiv-ask-user-question" });
+} catch {
+	// SDK absent — extension still loads with English-only UI.
+}
+
+export {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+	type AskUserPromptOption,
+	type AskUserPromptQuestion,
+} from "./events.js";
+
+export default function (pi: ExtensionAPI) {
+	// FEATURE-FORGE VENDOR PATCH: seed the bundle root so generated forge shell
+	// snippets prefer this active Pi adapter over unrelated local installs.
+	process.env.FEATURE_FORGE_ROOT ||= dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+	registerAskUserQuestionTool(pi);
+	registerAskUserQuestionReconciler(pi);
+}

package/adapters/pi/extensions/ask-user-question/locales/de.json

@@ -0,0 +1,27 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Schreibe etwas.",
+  "sentinel.next": "Weiter",
+
+  "submit.label": "Antworten senden",
+  "submit.cancel": "Abbrechen",
+
+  "hint.enter": "Enter zum Auswählen",
+  "hint.navigate": "↑/↓ zur Navigation",
+  "hint.toggle": "Leertaste zum Umschalten",
+  "hint.notes": "n für Notizen",
+  "hint.tab": "Tab wechselt die Frage",
+  "hint.cancel": "Esc zum Abbrechen",
+
+  "review.heading": "Antworten überprüfen",
+  "review.ready": "Bereit, deine Antworten zu senden?",
+  "review.incomplete": "⚠ Beantworte die verbleibenden Fragen vor dem Senden:",
+
+  "preview.no_preview": "Keine Vorschau verfügbar",
+  "preview.notes_affordance": "Notizen: drücke n, um Notizen hinzuzufügen",
+  "notes.header": "Notizen:",
+
+  "rpc.multi_instructions": "Gib die Nummern aller zutreffenden Optionen durch Komma getrennt ein (z. B. \"1,3\") oder tippe eine eigene Antwort als Text.",
+  "rpc.custom_answer_title": "Gib deine Antwort ein:"
+}

package/adapters/pi/extensions/ask-user-question/locales/en.json

@@ -0,0 +1,27 @@
+{
+  "sentinel.other": "Type something.",
+  "sentinel.next": "Next",
+
+  "submit.label": "Submit answers",
+  "submit.cancel": "Cancel",
+
+  "hint.enter": "Enter to select",
+  "hint.navigate": "↑/↓ to navigate",
+  "hint.toggle": "Space to toggle",
+  "hint.notes": "n to add notes",
+  "hint.tab": "Tab to switch questions",
+  "hint.collapse": "Ctrl+] to collapse",
+  "hint.expand_line": "Ctrl+] to expand · Esc to cancel",
+  "hint.cancel": "Esc to cancel",
+
+  "review.heading": "Review your answers",
+  "review.ready": "Ready to submit your answers?",
+  "review.incomplete": "⚠ Answer remaining questions before submitting:",
+
+  "preview.no_preview": "No preview available",
+  "preview.notes_affordance": "Notes: press n to add notes",
+  "notes.header": "Notes:",
+
+  "rpc.multi_instructions": "Enter the numbers of all that apply, comma-separated (e.g. \"1,3\"), or type a custom answer as plain text.",
+  "rpc.custom_answer_title": "Type your answer:"
+}

package/adapters/pi/extensions/ask-user-question/locales/es.json

@@ -0,0 +1,27 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Escribe algo.",
+  "sentinel.next": "Siguiente",
+
+  "submit.label": "Enviar respuestas",
+  "submit.cancel": "Cancelar",
+
+  "hint.enter": "Enter para seleccionar",
+  "hint.navigate": "↑/↓ para navegar",
+  "hint.toggle": "Espacio para alternar",
+  "hint.notes": "n para añadir notas",
+  "hint.tab": "Tab para cambiar de pregunta",
+  "hint.cancel": "Esc para cancelar",
+
+  "review.heading": "Revisa tus respuestas",
+  "review.ready": "¿Listo para enviar tus respuestas?",
+  "review.incomplete": "⚠ Responde las preguntas restantes antes de enviar:",
+
+  "preview.no_preview": "Vista previa no disponible",
+  "preview.notes_affordance": "Notas: pulsa n para añadir notas",
+  "notes.header": "Notas:",
+
+  "rpc.multi_instructions": "Introduce los números de todas las opciones que apliquen, separados por comas (p. ej. \"1,3\"), o escribe una respuesta propia como texto.",
+  "rpc.custom_answer_title": "Escribe tu respuesta:"
+}

package/adapters/pi/extensions/ask-user-question/locales/fr.json

@@ -0,0 +1,27 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Écrivez quelque chose.",
+  "sentinel.next": "Suivant",
+
+  "submit.label": "Envoyer les réponses",
+  "submit.cancel": "Annuler",
+
+  "hint.enter": "Entrée pour sélectionner",
+  "hint.navigate": "↑/↓ pour naviguer",
+  "hint.toggle": "Espace pour basculer",
+  "hint.notes": "n pour ajouter des notes",
+  "hint.tab": "Tab pour changer de question",
+  "hint.cancel": "Échap pour annuler",
+
+  "review.heading": "Vérifiez vos réponses",
+  "review.ready": "Prêt à envoyer vos réponses ?",
+  "review.incomplete": "⚠ Répondez aux questions restantes avant d'envoyer :",
+
+  "preview.no_preview": "Aucun aperçu disponible",
+  "preview.notes_affordance": "Notes : appuyez sur n pour ajouter des notes",
+  "notes.header": "Notes :",
+
+  "rpc.multi_instructions": "Saisissez les numéros de toutes les options applicables, séparés par des virgules (p. ex. « 1,3 »), ou tapez une réponse libre en texte.",
+  "rpc.custom_answer_title": "Tapez votre réponse :"
+}

package/adapters/pi/extensions/ask-user-question/locales/pt-BR.json

@@ -0,0 +1,27 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Digite algo.",
+  "sentinel.next": "Próximo",
+
+  "submit.label": "Enviar respostas",
+  "submit.cancel": "Cancelar",
+
+  "hint.enter": "Enter para selecionar",
+  "hint.navigate": "↑/↓ para navegar",
+  "hint.toggle": "Espaço para alternar",
+  "hint.notes": "n para adicionar notas",
+  "hint.tab": "Tab para trocar de pergunta",
+  "hint.cancel": "Esc para cancelar",
+
+  "review.heading": "Revise suas respostas",
+  "review.ready": "Pronto para enviar suas respostas?",
+  "review.incomplete": "⚠ Responda as perguntas restantes antes de enviar:",
+
+  "preview.no_preview": "Pré-visualização indisponível",
+  "preview.notes_affordance": "Notas: pressione n para adicionar notas",
+  "notes.header": "Notas:",
+
+  "rpc.multi_instructions": "Digite os números de todas as opções aplicáveis, separados por vírgula (ex.: \"1,3\") ou digite uma resposta própria em texto.",
+  "rpc.custom_answer_title": "Digite sua resposta:"
+}

package/adapters/pi/extensions/ask-user-question/locales/pt.json

@@ -0,0 +1,27 @@
+{
+  "_meta.notes": "European Portuguese (Portugal). Auto-translated draft. Native-speaker review welcome via PR. Distinct from pt-BR (Brasil): differs in lexicon (utilizador / você), conjugation, and some terms. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Escreva algo.",
+  "sentinel.next": "Seguinte",
+
+  "submit.label": "Enviar respostas",
+  "submit.cancel": "Cancelar",
+
+  "hint.enter": "Enter para selecionar",
+  "hint.navigate": "↑/↓ para navegar",
+  "hint.toggle": "Espaço para alternar",
+  "hint.notes": "n para adicionar notas",
+  "hint.tab": "Tab para mudar de pergunta",
+  "hint.cancel": "Esc para cancelar",
+
+  "review.heading": "Reveja as suas respostas",
+  "review.ready": "Pronto para enviar as suas respostas?",
+  "review.incomplete": "⚠ Responda às perguntas restantes antes de enviar:",
+
+  "preview.no_preview": "Pré-visualização indisponível",
+  "preview.notes_affordance": "Notas: prima n para adicionar notas",
+  "notes.header": "Notas:",
+
+  "rpc.multi_instructions": "Introduza os números de todas as opções aplicáveis, separados por vírgulas (ex.: \"1,3\") ou escreva uma resposta própria em texto.",
+  "rpc.custom_answer_title": "Escreva a sua resposta:"
+}