@bingjiang0611/rotom 0.1.0-alpha.0

package/extensions/third-party/node_modules/@juicesharp/rpiv-ask-user-question/config.ts

@@ -0,0 +1,75 @@
+import type { GuidanceFields } from "@juicesharp/rpiv-config";
+import { loadJsonConfigWithLegacyFallback, validateGuidanceFields } from "@juicesharp/rpiv-config";
+
+/** 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/extensions/third-party/node_modules/@juicesharp/rpiv-ask-user-question/docs/configuration.md

@@ -0,0 +1,120 @@
+# Configuration
+
+Every setting the package reads, where the file lives, and what happens when a value is
+wrong.
+
+## The config file
+
+```
+~/.config/rpiv-ask-user-question/config.json
+```
+
+The file is optional — with no config at all, every setting takes its default. This
+package only ever *reads* the file; it never creates, writes or chmods it, so its
+permissions are whatever you give it.
+
+A complete example:
+
+```json
+{
+  "collapseKey": "alt+o",
+  "guidance": {
+    "description": "Ask the user structured questions whenever requirements are ambiguous.",
+    "promptSnippet": "Ask me before guessing on anything ambiguous",
+    "promptGuidelines": [
+      "Batch every clarifying question into one ask_user_question call.",
+      "Put your recommended option first and suffix it with (Recommended)."
+    ]
+  }
+}
+```
+
+### Where the file is looked up
+
+1. `$XDG_CONFIG_HOME/rpiv-ask-user-question/config.json`, if `XDG_CONFIG_HOME` is set,
+   non-empty and absolute. A leading `~` is expanded first; a relative value is ignored.
+   Unset or ignored, the directory falls back to `~/.config`.
+2. If that file does not exist, the legacy path `~/.config/rpiv-ask-user-question/config.json`
+   is read. This path deliberately ignores `XDG_CONFIG_HOME`, so an existing config keeps
+   working after you set the variable.
+3. Neither present: all defaults.
+
+If the XDG-path file exists, its result wins even when it is malformed — there is no
+second chance at the legacy path.
+
+### When the file is invalid
+
+Malformed JSON is not fatal. The loader warns on stderr and continues with defaults:
+
+```
+rpiv-config: invalid JSON at <path>, using default ({}) — <parser message>
+```
+
+Valid JSON that is not an object (a string, number, `null`, or an array) is rejected too,
+falling back to defaults — but silently, with no warning. Individual keys with the wrong
+type are likewise dropped back to their default without a warning.
+
+## Settings
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `collapseKey` | Key that collapses and expands the dialog overlay. | `"ctrl+]"` |
+| `guidance.description` | Full text of the tool description the model sees. Replaces the built-in default entirely — no merging. | built-in description |
+| `guidance.promptSnippet` | One-line snippet describing the tool in the system prompt. | built-in snippet |
+| `guidance.promptGuidelines` | List of usage guidelines given to the model. | 4 built-in guidelines |
+
+### `collapseKey`
+
+The value uses Pi's keybinding id format: zero or more distinct modifiers from `ctrl`,
+`shift`, `alt`, `super`, joined by `+`, followed by a base key. Values are trimmed and
+lowercased before matching.
+
+The base key is either a single printable character from
+`a-z 0-9 _ - ! @ # $ % ^ & * ( ) | ~ \` ' " : ; , . / < > ? [ ] { } = \`, or one of the
+named keys `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`,
+`insert`, `clear`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`,
+`f1`–`f12`.
+
+Examples that work: `"ctrl+]"`, `"alt+o"`, `"ctrl+shift+h"`, `"f9"`, `"ctrl+}"`.
+
+Set `"off"` (any casing) to disable the collapse shortcut entirely — no raw terminal
+listener is registered in that case.
+
+A spec that does not match the grammar is rejected and the default is used. This is
+strict on purpose: Pi's parser takes the last `+`-separated part as the key and ignores
+unknown parts, so a typo like `"ctr+]"` would otherwise silently capture every bare `]`
+keypress at the terminal level.
+
+One known rough edge: the footer hint line inside the dialog always reads `Ctrl+] to
+collapse` and does not interpolate a custom `collapseKey`. The one-shot notification you
+get when the dialog first collapses *does* name your configured key.
+
+### `guidance.description`, `guidance.promptSnippet` and `guidance.promptGuidelines`
+
+`guidance.description` replaces the entire built-in description Pi registers for the
+`ask_user_question` tool — the text the model reads when deciding how to use it. There is
+no merging: a valid value wins wholesale. It is used only when it is a non-empty string;
+anything else falls back to the built-in default. Like the other guidance fields it is read
+once, when the extension registers the tool, so changes take effect on the next Pi restart.
+
+These replace the text Pi puts in the system prompt about when to reach for
+`ask_user_question`. Use them to make the model ask more or less often, or to enforce a
+house style for options.
+
+`promptSnippet` is used only when it is a non-empty string. `promptGuidelines` is used
+only when it is a non-empty array whose entries are all non-empty strings. Anything else
+falls back to the built-in defaults. Both are read once, when the extension registers the
+tool, so changes take effect on the next Pi restart.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `XDG_CONFIG_HOME` | Relocates the config directory, as described above. Must be absolute. |
+
+`LANG` and `LC_ALL` influence the dialog language, but they are read by
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) rather than
+by this package — see [localization.md](./localization.md).
+
+No other environment variables are read. The package makes no model calls, so it needs no
+API keys or model settings of its own.

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

@@ -0,0 +1,93 @@
+# Hosts and runtime behavior
+
+Where the questionnaire renders, what it degrades to, and what happens when it cannot
+render at all.
+
+## Three environments
+
+| Environment | What the model sees | What you see |
+| --- | --- | --- |
+| Interactive terminal | `ask_user_question` in its tool list | The full tabbed TUI overlay |
+| RPC / ACP host (VS Code pendant, Zed, Paseo) | `ask_user_question` in its tool list | A sequence of the host's own native select and input dialogs |
+| Non-interactive run (no UI) | Nothing — the tool is removed | Nothing |
+
+### Terminal attention
+
+After UI availability and questionnaire validation succeed, the package emits exactly one standard terminal BEL (`\x07`) immediately before the interactive wait begins. The signal is sent to `stdout` only when `process.stdout.isTTY` is true, so redirected output and non-TTY RPC streams stay untouched. A TTY-backed RPC dialog walker receives the same signal as the TUI path.
+
+The BEL is best effort: if the synchronous terminal write fails, the questionnaire continues and its existing prompt/blocked lifecycle and result envelope are unchanged. The terminal configuration decides whether the BEL is audible, visual, or ignored. No BEL is emitted for missing UI, invalid questionnaires, or a failed TUI session load.
+
+### Non-interactive runs
+
+A `before_agent_start` hook reconciles the active tool set against `ctx.hasUI` before every
+turn. When there is no UI, `ask_user_question` is stripped from the list so the model never
+sees a tool it cannot use — better than offering it and auto-declining every call. When UI
+comes back, the tool is restored. The reconciler is idempotent and leaves sibling tools
+untouched.
+
+A second guard lives inside the tool handler as a one-turn backstop: if a call somehow
+arrives without UI, it returns `error: "no_ui"` and the text
+`Error: UI not available (running in non-interactive mode)`.
+
+### RPC and ACP hosts
+
+RPC hosts report `hasUI: true` because Pi's dialog sub-protocol works there, but custom
+terminal UI does not render. The package detects this two ways: hosts that advertise
+`ctx.mode === "rpc"` route straight to the dialog walker, skipping the TUI import
+entirely, and older RPC builds are caught by a backstop when custom UI resolves without
+rendering anything. Either path requires the host to expose both `select` and `input`.
+
+The walker asks one question per dialog and returns exactly the same result envelope the
+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.
+- 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
+  selection, matching `Next` with nothing toggled.
+- Dismissing any dialog cancels the whole questionnaire, mirroring `Esc` in the TUI.
+
+If the host can render neither custom UI nor dialogs, the call returns
+`error: "no_custom_ui"` with text telling the model the user never saw the questions and
+that it should ask them as plain chat text instead — explicitly not a decline.
+
+## Conditional surfaces
+
+Some parts of the dialog exist only under the right conditions:
+
+| Surface | Appears when |
+| --- | --- |
+| Tab bar and Submit tab | The call carries more than one question |
+| `Next` row | The question is multi-select |
+| `Type something.` row | Always |
+| Side-by-side preview | An option carries a `preview`, and terminal and pane are both ≥ 100 columns |
+| Preview pane at all | Single-select questions only |
+| Collapse shortcut | `collapseKey` is not `"off"` and the host exposes raw terminal input |
+| Localized chrome | `@juicesharp/rpiv-i18n` is installed |
+
+## Loading and startup cost
+
+The dialog's render graph costs roughly 560 ms to import, so it is loaded lazily — on the
+first tool call, not when the extension registers. To keep that first call fast and safe,
+the graph is also pre-warmed in the background two seconds after startup. The pre-warm
+timer is unref'd, so it never holds a process open, and a failed pre-warm is swallowed:
+the first real call re-imports and reports properly.
+
+The pre-warm exists for a specific failure. Pi's module loader registers a module in its
+graph cache *before* evaluating it and does not evict it if evaluation throws. If your
+package manager replaces the dependency store while Pi is running, one failed import can
+poison the cache for the rest of the process. Evaluating the graph early, while the paths
+Pi resolved at boot still exist, keeps it in memory for the process lifetime and makes
+that unreachable.
+
+When it does happen, you get a structured envelope rather than a raw `TypeError`:
+
+| `error` | Meaning | Fix |
+| --- | --- | --- |
+| `session_load_failed` | The dialog module could not be imported. | Repair the install if needed, then restart Pi. |
+| `stale_module_cache` | The module cache went stale after an earlier failed import. | Restart Pi — this is unrecoverable in the running process. |
+
+Both messages tell the model the questions were never shown and to ask them as plain chat
+text instead of treating the failure as a decline.

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

@@ -0,0 +1,103 @@
+# Keyboard and dialog layout
+
+Every key the questionnaire dialog reacts to, the rows it appends for you, and how it
+adapts to the size of your terminal.
+
+## Keys
+
+| Key | What it does | Where it applies |
+| --- | --- | --- |
+| `↑` / `↓` | Move between rows. Wraps at both ends. | Option list, Submit picker |
+| `Enter` | Confirm the focused option, commit typed text, close notes, or activate the focused Submit-picker row. | Everywhere |
+| `Shift+Enter` | Insert a newline. | `Type something.` input, notes editor |
+| `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 |
+| `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 |
+
+The table names the default keys; the dialog actually follows your Pi keybindings.
+Confirm listens to both `tui.select.confirm` and `tui.input.submit`, and a key bound to
+`tui.input.newLine` always inserts a newline even if it also matches confirm. So a
+Slack-style configuration — `enter` folded into `tui.input.newLine`, submit moved to
+`ctrl+enter` — keeps working: `enter` breaks lines, and your submit key confirms
+everywhere `Enter` does.
+
+In a multi-select question, `Enter` on a regular row toggles its checkbox exactly like
+`Space` — it does not submit. Committing the question means focusing the `Next` row and
+pressing `Enter`. That is deliberate: it makes `Enter` a zero-cost way to flip boxes
+without leaving the home row.
+
+`Space` is suppressed on two rows: `Next` (it is a command, not a choice) and
+`Type something.` (it is an inline text input, so the space character belongs to your
+answer).
+
+## The rows the dialog adds
+
+| Row | Label | Appended to |
+| --- | --- | --- |
+| Custom answer | `Type something.` | Every question — single-select and multi-select, with or without previews |
+| Commit | `Next` | Multi-select questions only |
+
+Focusing `Type something.` switches the row into an inline multiline editor. In preview
+mode it expands to the full pane width while you type, so a long custom answer is not
+squeezed into the narrow options column. `Shift+Enter` inserts a line break; vertical
+arrows move between lines and return to row navigation at the draft's top and bottom.
+The draft replaces the static row label while you browse other options and is isolated
+per question. `Ctrl+G` round-trips it through Pi's configured external editor; `Ctrl+U`
+clears it, while `Esc` remains the explicit way to cancel the questionnaire. Confirming
+it produces an answer of `kind: "custom"`.
+
+Both labels are reserved — the model cannot author an option that collides with them.
+Both localize with the rest of the UI chrome; the reserved-label check always compares
+against the canonical English strings.
+
+## Notes
+
+`n` opens a notes editor on any question tab, whether the question is single- or
+multi-select and whether or not its options carry previews. Notes are stored in a
+side-band keyed by tab index, not inside the answer, so writing a note does not mark a
+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>`.
+
+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.
+
+## Collapse mode
+
+`Ctrl+]` gets the dialog out of the way: the overlay is marked hidden in Pi's overlay
+stack and shrinks to a single dim hint row, so the transcript it was covering becomes
+readable and chat scrolling resumes. Press the same key to bring the questionnaire back
+with your answers intact. The first time you collapse, Pi notifies you with the key to
+press — that message names your configured key.
+
+Because Pi routes no input to a hidden overlay, the collapse key is additionally captured
+at the raw terminal level. It only acts when the questionnaire is hidden or focused, so a
+different overlay on top of it (for example `/btw`) keeps its keystrokes.
+
+While collapsed, every keystroke other than cancel is ignored, so you cannot mutate
+answers you cannot see.
+
+The default `ctrl+]` is free in Terminal.app, iTerm2, Warp, tmux, zellij and screen. On
+keyboard layouts where `]` sits on the shifted layer — Latin American `es-AR` / `es-MX`,
+among others — set a different `collapseKey`, or `"off"` to disable the shortcut.
+
+## Layout
+
+Options render in a vertical list. When any option in a single-select question carries a
+`preview`, the dialog splits into a side-by-side layout with the option list on the left
+and a bordered monospace preview box on the right — but only when both the terminal and
+the dialog pane are at least 100 columns wide. Below that, the preview stacks underneath
+the options instead.
+
+When the dialog is taller than the terminal, the body scrolls between a sticky heading and
+a sticky footer, and an overflow indicator shows which direction is clipped: `↑` for
+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.
+`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/extensions/third-party/node_modules/@juicesharp/rpiv-ask-user-question/docs/localization.md

@@ -0,0 +1,83 @@
+# Localization
+
+How the dialog picks its language, which languages ship, and how to add one.
+
+## Enabling it
+
+The extension works standalone: install only this package and you get the full dialog in
+English. Localization needs one more install:
+
+```sh
+pi install npm:@juicesharp/rpiv-i18n
+```
+
+Restart your Pi session. If you installed through
+[`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) and ran
+`/rpiv-setup`, you already have it.
+
+The dependency is a genuinely optional peer. This package loads the SDK inside a
+`try`/`catch` at startup; when it is absent, every string falls back to its inline English
+literal at the call site. There is no warning and no crash — the dialog simply renders in
+English.
+
+## Picking a language
+
+With the SDK installed, the locale resolves in this order, first hit wins:
+
+1. `pi --locale <code>` on the command line
+2. `~/.config/rpiv-i18n/locale.json`
+3. `LANG` / `LC_ALL` from the environment
+4. English
+
+`/languages` opens an interactive picker and flips the strings live — the dialog reads its
+strings at render time, so an open questionnaire follows the change. Both `/languages` and
+`--locale` are registered by `@juicesharp/rpiv-i18n`, not by this package.
+
+## Shipped languages
+
+Nine locale files ship in `locales/`:
+
+| Code | Language |
+| --- | --- |
+| `de` | Deutsch |
+| `en` | English |
+| `es` | Español |
+| `fr` | Français |
+| `pt` | Português |
+| `pt-BR` | Português (Brasil) |
+| `ru` | Русский |
+| `uk` | Українська |
+| `zh` | 中文 |
+
+## 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`.
+
+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,
+not UI, and translating them would change model behavior rather than your reading
+experience. It also means reserved-label validation compares against fixed English
+strings, so `Type something.` is rejected as an authored option label in every locale.
+
+## Adding a language
+
+No code change is required.
+
+1. Copy `locales/en.json` to `locales/<code>.json`, where `<code>` is a locale the SDK
+   supports.
+2. Translate the values. Keep every key, and keep the placeholders and leading symbols
+   (`↑/↓`, `⚠`) intact.
+3. Restart Pi and select the language with `/languages`.
+
+The loader iterates the SDK's supported-locale list over this directory at startup, so a
+new file is picked up automatically. See the
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) README,
+section "Contributing translations", for the full convention.
+
+Keys are looked up individually with an English fallback, so a partially translated file
+is safe — untranslated keys render in English rather than blank.

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

@@ -0,0 +1,121 @@
+# Tool schema
+
+The complete programmatic surface of `ask_user_question`: what the model sends, what
+validation rejects, what comes back, and the event other extensions can listen to.
+
+## Parameters
+
+```ts
+ask_user_question({
+  questions: [
+    {
+      question: string,            // full question text, ends with "?"
+      header: string,              // chip label, max 16 chars
+      options: [
+        {
+          label: string,           // 1-5 words, max 60 chars
+          description: string,     // what the choice means / its trade-off
+          preview?: string,        // markdown rendered next to the options
+        },
+        // … 2-4 options total
+      ],
+      multiSelect?: boolean,       // default false
+    },
+    // … 1-4 questions total
+  ]
+})
+```
+
+### Limits
+
+| Field | Constraint | Enforced by |
+| --- | --- | --- |
+| `questions` | 1-4 entries | TypeBox schema + `validateQuestionnaire` |
+| `questions[].header` | max 16 characters | TypeBox schema only |
+| `questions[].options` | 2-4 entries | TypeBox schema (both bounds) + `validateQuestionnaire` (minimum only) |
+| `options[].label` | max 60 characters | TypeBox schema only |
+| `options[].preview` | single-select questions only | tool description (multi-select tabs render checkbox rows) |
+
+The two `maxLength` limits are checked by the parameter schema before `execute` runs;
+the runtime validator does not re-check them.
+
+### Reserved option labels
+
+Authoring any of `"Other"`, `"Type something."`, or `"Next"` as an option label is
+rejected with `reserved_label`. The last two are the runtime sentinel rows the dialog
+appends itself; `"Other"` is reserved because models are conditioned to reach for it.
+Reservation is unconditional — a single-select question rejects `"Next"` even though
+that row is never appended there.
+
+## Validation errors
+
+Every rejection returns `cancelled: true`, an empty `answers` array, and an `error`
+code. The `content[0].text` string is written for the model, not for a log.
+
+| `error` | Cause |
+| --- | --- |
+| `no_questions` | `questions` was empty |
+| `too_many_questions` | more than 4 questions in one call |
+| `duplicate_question` | two questions with identical text |
+| `empty_options` | a question carried fewer than 2 options |
+| `reserved_label` | an option used a reserved label |
+| `duplicate_option_label` | two options in one question share a label |
+| `no_ui` | the run has no UI (`ctx.hasUI === false`) |
+| `no_custom_ui` | the host cannot render custom UI and exposes no `select`/`input` dialogs |
+| `session_load_failed` | the dialog module failed to import (dependencies changed on disk mid-session) |
+| `stale_module_cache` | the loader cached a broken module after an earlier failed import; needs a Pi restart |
+
+`reserved_label` short-circuits before `duplicate_option_label`.
+
+## Result
+
+```ts
+{
+  content: [{ type: "text", text: string }], // envelope prose, or the decline message
+  details: {
+    answers: Array<{
+      questionIndex: number,
+      question: string,
+      kind: "option" | "custom" | "multi",
+      answer: string | null,       // option label, typed text, or null for multi
+      selected?: string[],         // chosen labels, multi-select only
+      notes?: string,              // free-text note, when you wrote one
+      preview?: string,            // echoed back when the chosen option carried a preview
+    }>,
+    cancelled: boolean,
+    error?: QuestionnaireError,    // one of the codes above
+  }
+}
+```
+
+### Envelope text
+
+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.
+
+## Event contract
+
+The package publishes one event on Pi's event bus, emitted after validation passes and
+before the dialog is shown. Import it from the `/events` subpath:
+
+```ts
+import { ASK_USER_PROMPT_EVENT, type AskUserPromptEventPayload } from "@juicesharp/rpiv-ask-user-question/events";
+
+pi.events.on(ASK_USER_PROMPT_EVENT, (payload: AskUserPromptEventPayload) => {
+  // payload.questions[].{ question, header, multiSelect, options[] }
+  // payload.questions[].options[].{ label, description, hasPreview }
+});
+```
+
+The channel name is `rpiv:ask-user:prompt`. Preview *content* is deliberately not shipped
+in the payload — only `hasPreview: boolean` — so listeners forwarding the event across a
+process or network boundary stay cheap.
+
+Stability policy for the `rpiv:*` namespace: channel names are immutable, payload changes
+are append-only and always optional, payloads stay JSON-safe, and any breaking change ships
+as a new channel (e.g. `rpiv:ask-user:prompt.v2`) rather than a version field.

package/extensions/third-party/node_modules/@juicesharp/rpiv-ask-user-question/events.ts

@@ -0,0 +1,55 @@
+/**
+ * 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;
+}