@herbertgao/pi-extensions 2026.8.7 → 2026.8.8

package/node_modules/@juicesharp/rpiv-ask-user-question/ask-user-question.ts

@@ -1,5 +1,5 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, isKeyRepeat, matchesKey, type OverlayHandle, type TUI } from "@earendil-works/pi-tui";
 import {
 	COLLAPSE_KEY_OFF,
 	formatKeySpecForDisplay,
@@ -15,7 +15,7 @@ import {
 } 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 { type DialogUI, hasDialogUI, runRpcQuestionnaire } from "./rpc-fallback.js";
 import { displayLabel, t } from "./state/i18n-bridge.js";
 import { sentinelsToAppend } from "./state/row-intent.js";
 import { buildQuestionnaireResponse, buildToolResult } from "./tool/response-envelope.js";
@@ -53,6 +53,22 @@ function emitAskUserBlockedEvent(pi: ExtensionAPI, active: boolean): void {
 	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
 }
 
+/** Non-interactive host backstop (the reconciler normally strips the tool first). */
+function rejectWithoutUi() {
+	return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: "no_ui" });
+}
+
+/** Sequential native-dialog walker for RPC hosts; brackets it with the blocked-event pair + terminal bell. */
+async function runRpcPath(pi: ExtensionAPI, ui: DialogUI, typed: QuestionParams) {
+	emitAskUserBlockedEvent(pi, true);
+	try {
+		emitTerminalAttention();
+		return buildQuestionnaireResponse(await runRpcQuestionnaire(ui, typed), typed);
+	} finally {
+		emitAskUserBlockedEvent(pi, false);
+	}
+}
+
 /** Canonical tool name — single source of truth shared with the reconcile module. */
 export const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
 
@@ -90,6 +106,9 @@ export const PREWARM_DELAY_MS = 2000;
 
 type SessionModule = typeof import("./state/questionnaire-session.js");
 
+type SessionRef = { current: import("./state/questionnaire-session.js").QuestionnaireSession | null };
+type OverlayHandleRef = { current: OverlayHandle | undefined };
+
 type SessionLoad =
 	| { ok: true; module: SessionModule }
 	| { ok: false; error: Extract<QuestionnaireError, "session_load_failed" | "stale_module_cache">; message: string };
@@ -124,6 +143,122 @@ export async function loadQuestionnaireSession(): Promise<SessionLoad> {
 	return { ok: true, module: mod };
 }
 
+/**
+ * Register the raw terminal listener that toggles collapse while the overlay is hidden.
+ * Returns the remover, or undefined when the key is off / the host has no raw input hook —
+ * callers derive `canReopenWhileHidden` from that.
+ */
+function registerCollapseKeyListener(
+	ctx: ExtensionContext,
+	collapseKey: string,
+	sessionRef: SessionRef,
+	overlayHandleRef: OverlayHandleRef,
+): (() => void) | undefined {
+	if (collapseKey === COLLAPSE_KEY_OFF || typeof ctx.ui.onTerminalInput !== "function") return undefined;
+	let hasAnnouncedHide = false;
+	return 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 ${formatKeySpecForDisplay(collapseKey)} to reopen`, "info");
+		}
+		return { consume: true };
+	});
+}
+
+/**
+ * Build the `ctx.ui.custom` component factory: constructs the session (capturing it in
+ * `sessionRef`) and exposes its component. `editInput` keeps its two dynamic imports —
+ * they must stay lazy per-invocation.
+ */
+function makeSessionFactory(config: {
+	ctx: ExtensionContext;
+	typed: QuestionParams;
+	itemsByTab: WrappingSelectItem[][];
+	collapseKey: string;
+	canReopenWhileHidden: boolean;
+	sessionRef: SessionRef;
+	Session: SessionModule["QuestionnaireSession"];
+}) {
+	const { ctx, typed, itemsByTab, collapseKey, canReopenWhileHidden, sessionRef, Session } = config;
+	return (
+		tui: TUI,
+		theme: Theme,
+		keybindings: import("./state/questionnaire-session.js").QuestionnaireSessionConfig["keybindings"],
+		done: (result: QuestionnaireResult) => void,
+	): import("./state/questionnaire-session.js").QuestionnaireSessionComponent => {
+		const session = new Session({
+			tui,
+			theme,
+			params: typed,
+			itemsByTab,
+			done,
+			keybindings,
+			editInput: async (value) => {
+				try {
+					const [{ SettingsManager }, { editWithExternalEditor }] = await Promise.all([
+						import("@earendil-works/pi-coding-agent"),
+						import("./state/external-editor.js"),
+					]);
+					const editorCommand = SettingsManager.create(ctx.cwd, undefined, {
+						projectTrusted: ctx.isProjectTrusted(),
+					}).getExternalEditorCommand();
+					if (!editorCommand) throw new Error("No external editor command is configured");
+					return await editWithExternalEditor(tui, editorCommand, value);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					ctx.ui.notify(`${t("editor.failed", "External editor failed")}: ${message}`, "error");
+					return undefined;
+				}
+			},
+			collapseKey,
+			canReopenWhileHidden,
+		});
+		sessionRef.current = session;
+		return session.component;
+	};
+}
+
+/**
+ * A TUI questionnaire ALWAYS resolves a QuestionnaireResult (cancel included), 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.
+ */
+async function resolveUndefinedResult(ctx: ExtensionContext, typed: QuestionParams) {
+	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" });
+}
+
+/**
+ * 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.
+ */
+function prewarmSessionGraph(): void {
+	const timer = setTimeout(() => void loadQuestionnaireSession().catch(() => undefined), PREWARM_DELAY_MS);
+	timer.unref?.();
+}
+
 export function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {
 	const items: WrappingSelectItem[] = question.options.map((o) => ({
 		kind: "option",
@@ -176,7 +311,7 @@ export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
 
 		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" });
+			if (!ctx.hasUI) return rejectWithoutUi();
 
 			const validation = validateQuestionnaire(typed);
 			if (!validation.ok) {
@@ -197,13 +332,7 @@ export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
 			// 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 {
-					emitTerminalAttention();
-					return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
-				} finally {
-					emitAskUserBlockedEvent(pi, false);
-				}
+				return runRpcPath(pi, ctx.ui, typed);
 			}
 
 			const itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));
@@ -225,40 +354,9 @@ export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
 			// 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 !== COLLAPSE_KEY_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 ${formatKeySpecForDisplay(collapseKey)} to reopen`,
-							"info",
-						);
-					}
-					return { consume: true };
-				});
-			}
+			const sessionRef: SessionRef = { current: null };
+			const overlayHandleRef: OverlayHandleRef = { current: undefined };
+			const removeOverlayInputListener = registerCollapseKeyListener(ctx, collapseKey, sessionRef, overlayHandleRef);
 			// Hiding the overlay is only reversible through the raw listener above, so
 			// the session may emit `setHidden` only when it was actually registered;
 			// otherwise collapse falls back to the visible one-line row.
@@ -268,37 +366,15 @@ export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
 			try {
 				emitTerminalAttention();
 				const result = await ctx.ui.custom<QuestionnaireResult>(
-					(tui, theme, keybindings, done) => {
-						const session = new QuestionnaireSession({
-							tui,
-							theme,
-							params: typed,
-							itemsByTab,
-							done,
-							keybindings,
-							editInput: async (value) => {
-								try {
-									const [{ SettingsManager }, { editWithExternalEditor }] = await Promise.all([
-										import("@earendil-works/pi-coding-agent"),
-										import("./state/external-editor.js"),
-									]);
-									const editorCommand = SettingsManager.create(ctx.cwd, undefined, {
-										projectTrusted: ctx.isProjectTrusted(),
-									}).getExternalEditorCommand();
-									if (!editorCommand) throw new Error("No external editor command is configured");
-									return await editWithExternalEditor(tui, editorCommand, value);
-								} catch (error) {
-									const message = error instanceof Error ? error.message : String(error);
-									ctx.ui.notify(`${t("editor.failed", "External editor failed")}: ${message}`, "error");
-									return undefined;
-								}
-							},
-							collapseKey,
-							canReopenWhileHidden,
-						});
-						sessionRef.current = session;
-						return session.component;
-					},
+					makeSessionFactory({
+						ctx,
+						typed,
+						itemsByTab,
+						collapseKey,
+						canReopenWhileHidden,
+						sessionRef,
+						Session: QuestionnaireSession,
+					}),
 					{
 						overlay: true,
 						overlayOptions: {
@@ -314,17 +390,8 @@ export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
 					},
 				);
 
-				// 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 resolveUndefinedResult(ctx, typed);
 				}
 
 				return buildQuestionnaireResponse(result, typed);
@@ -335,16 +402,7 @@ export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
 		},
 	});
 
-	// 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?.();
+	prewarmSessionGraph();
 }
 
 export { buildQuestionnaireResponse, buildToolResult };

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/hosts.md

@@ -43,6 +43,9 @@ TUI produces. Trade-offs inherent to the native primitives:
 - No side-by-side preview pane. Previews are folded into the dialog title instead,
   truncated at 600 characters each.
 - No tab bar and no Submit review tab — one dialog per question, in order.
+- No notes. Both note kinds — per-question `n` on a question tab and global `n` on the
+  Submit tab — are terminal-only; the host's native `select` and `input` primitives carry
+  no note field.
 - Multi-select is a free-text input: type the option numbers, comma-separated
   (`1,3`). Any token that is not a valid option index is treated as a typed custom answer,
   which is how the `Type something.` escape survives. An empty input commits an empty

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/keyboard.md

@@ -13,7 +13,7 @@ adapts to the size of your terminal.
 | `Esc` | Cancel the whole questionnaire. | Everywhere except the notes editor, where it closes notes |
 | `Tab` / `Shift+Tab` | Next / previous tab, wrapping. `→` / `←` do the same. | Multi-question dialogs only |
 | `Space` | Toggle the focused checkbox. | Multi-select questions |
-| `n` | Open the notes editor for the current question. | Every question tab |
+| `n` | Open the notes editor for the focused question — or, on the Submit tab, the global note for the whole questionnaire. | Every question tab; the Submit tab in multi-question dialogs |
 | `Ctrl+G` | Open Pi's configured external editor with the current custom-answer draft. | `Type something.` input |
 | `Ctrl+U` | Clear the current custom-answer draft. | `Type something.` input |
 | `Ctrl+]` | Collapse or expand the dialog. Configurable via `collapseKey`. | Everywhere, including while collapsed |
@@ -62,6 +62,11 @@ side-band keyed by tab index, not inside the answer, so writing a note does not
 question as answered — the Submit tab still lists it as outstanding. The note merges into
 the answer when you confirm it, and reaches the model as `user notes: <text>`.
 
+On the Submit tab, `n` opens the global note editor instead — one note covering the whole
+questionnaire. It lives outside every answer, so it survives tab switches and never marks
+a question as answered; it reaches the model as `global note: <text>`, and submitting with
+nothing but a global note still returns an answered result rather than a decline.
+
 Inside the editor, `Shift+Enter` inserts a newline, while `Esc` and `Enter` close it; other
 keystrokes edit the buffer, so `n` types an `n`. Pasted line breaks are preserved.
 
@@ -98,6 +103,9 @@ content above, `↓` for content below, `↕` for both.
 
 The footer hint line adapts to context — it drops the notes hint and appends the
 `Shift+Enter` newline hint whenever a text editor has the keyboard, with `Ctrl+U` still at
-the far right for custom answers. It adds the tab hint only in multi-question dialogs.
+the far right for custom answers. It adds the tab hint only in multi-question dialogs. The
+Submit tab follows the same idiom: its bottom hint row sits below the picker and carries
+an `n to add a note` part that gives way to the `Shift+Enter` newline hint while the
+global-note editor is open; a committed note shows as a `Note` entry in the review list.
 `Ctrl+G` remains Pi's global external-editor shortcut and is not repeated there. On narrow
 terminals the right edge clips with `…` so the core hints survive.

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/localization.md

@@ -52,11 +52,13 @@ Nine locale files ship in `locales/`:
 ## What is translated, and what is not
 
 Translation covers the chrome you read: the `Type something.` and `Next` sentinel rows,
-the footer hint segments (including the collapsed-state line), the Submit picker labels,
-the review-tab heading with its submit-readiness prompt and incomplete-answers warning, the
-preview pane's empty and notes-affordance lines, the notes header, the external-editor
-failure notification, and the two RPC dialog prompts. Twenty-three keys in total, all under the namespace
-`@juicesharp/rpiv-ask-user-question`.
+the footer hint segments (including the collapsed-state line and the Submit tab's
+`n to add a note` hint), the Submit picker labels, the review-tab heading with its
+submit-readiness prompt, incomplete-answers warning, and committed-note `Note` label, the
+preview pane's empty and notes-affordance lines, the notes header and the global-note
+header on the Submit tab, the
+external-editor failure notification, and the two RPC dialog prompts. Twenty-six keys in total,
+all under the namespace `@juicesharp/rpiv-ask-user-question`.
 
 Everything the *model* reads stays English by design: the tool description, the parameter
 schema descriptions, error messages, and the reserved-label list. Those are prompt inputs,

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/tool-schema.md

@@ -83,6 +83,7 @@ code. The `content[0].text` string is written for the model, not for a log.
       preview?: string,            // echoed back when the chosen option carried a preview
     }>,
     cancelled: boolean,
+    globalNote?: string,          // Submit-tab note; present even when cancelled is true
     error?: QuestionnaireError,    // one of the codes above
   }
 }
@@ -92,11 +93,16 @@ code. The `content[0].text` string is written for the model, not for a log.
 
 On success the text reads `User has answered your questions: "<question>"="<answer>". …
 You can now continue with the user's answers in mind.` A chosen option's `preview` is
-appended as `selected preview: <markdown>`, and a note as `user notes: <text>`.
-
-Cancelling, and any result that produces no answer segments, both collapse to the single
-string `User declined to answer questions` so the model sees one canonical signal.
-Partial submission is allowed: unanswered questions simply contribute no segment.
+appended as `selected preview: <markdown>`, a per-question note as `user notes: <text>`,
+and the Submit tab's global note as a trailing `global note: <text>` segment. A global
+note alone still yields the answered envelope — it counts as an answer even when every
+question is blank.
+
+Cancelling, and any result with neither answer segments nor a global note, both collapse
+to the single string `User declined to answer questions` so the model sees one canonical
+signal. Partial submission is allowed: unanswered questions simply contribute no segment.
+A cancelled result always reads as the decline in text; its note, if any, survives only
+in `details.globalNote`.
 
 ## Event contract
 

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/en.json

@@ -19,10 +19,13 @@
   "review.heading": "Review your answers",
   "review.ready": "Ready to submit your answers?",
   "review.incomplete": "⚠ Answer remaining questions before submitting:",
+  "review.global_hint": "n to add a note",
+  "review.note_label": "Note",
 
   "preview.no_preview": "No preview available",
   "preview.notes_affordance": "Notes: press n to add notes",
   "notes.header": "Notes:",
+  "notes.global_header": "Global note:",
 
   "editor.failed": "External editor failed",
 

package/node_modules/@juicesharp/rpiv-ask-user-question/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-ask-user-question",
-	"version": "2.6.4",
+	"version": "2.7.0",
 	"description": "Pi extension. A structured questionnaire the model can put to you when it would otherwise guess, with typed options instead of free-form replies.",
 	"keywords": [
 		"pi-package",
@@ -94,7 +94,7 @@
 		}
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^2.6.4",
+		"@juicesharp/rpiv-config": "^2.7.0",
 		"typebox": "^1.1.24"
 	}
 }