@fadhelhaidar/pi-ask-user 1.0.3 → 1.1.0

package/docs/hosts.md

@@ -7,7 +7,7 @@ render at all.
 
 | Environment | What the model sees | What you see |
 | --- | --- | --- |
-| Interactive terminal | `ask_user_question` in its tool list | The full tabbed TUI overlay |
+| Interactive terminal | `ask_user_question` in its tool list | The full tabbed TUI dialog, inline in Pi's editor area (or as an overlay — see below) |
 | 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 |
 
@@ -47,15 +47,58 @@ TUI produces. Trade-offs inherent to the native primitives:
   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
-  selection, matching `Next` with nothing toggled.
+  (`1,3`), optionally followed by `; your own answer` to submit checks and custom text
+  together. A reply that is no option number is taken as the typed custom answer; an empty
+  input commits an empty selection, matching `Next` with nothing toggled. A blank custom
+  answer stays blank (this fork keeps that behavior; upstream returns to the picker).
 - 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.
 
+## Where the dialog renders
+
+In a terminal the questionnaire mounts inline in Pi's editor slot by default, capped at
+70% of the terminal height (at least 12 rows), so `PageUp`/`PageDown` and the mouse wheel
+keep scrolling the transcript while a question is open. It falls back to an overlay in two
+cases, both of which mean the inline slot cannot receive keys:
+
+- Another questionnaire already holds the slot.
+- An overlay that captures input (for example `/btw`) is on screen. A question is stacked
+  on top of it as an overlay instead, and collapses to its one-line row rather than
+  hiding, because Pi pops overlays from the top of its stack.
+
+`ctx.ui.custom` options that already allocate the dialog's rows (marked with the host
+symbol `rpiv-ask-user-question:host-allocated-rows`) are exempt from the 70% cap, so a
+host that sizes the slot itself is never shrunk twice.
+
+Because Pi closes an overlay by popping the top of its stack, an answer that arrives from
+outside (`rpiv:ask-user:answer`) removes a stacked questionnaire through its own overlay
+handle rather than the host's close callback. Answering the upper one is unaffected; the
+lower one leaves the stack without disturbing it.
+
+## Answering from outside the terminal
+
+A program driving Pi — a pane supervisor, a phone or web bridge, a test harness — can
+answer an open questionnaire without synthesizing keystrokes:
+
+| Event | Direction | Purpose |
+| --- | --- | --- |
+| `rpiv:ask-user:prompt` | out | Questions, plus the `toolCallId` naming this questionnaire |
+| `rpiv:ask-user:blocked` | out | `{ active: true }` while input is awaited, `{ active: false }` when it ends, both carrying `toolCallId` |
+| `rpiv:ask-user:answer` | **in** | Answer or cancel the questionnaire named by `toolCallId` |
+| `rpiv:ask-user:answer-result` | out | One verdict per attempt: `{ ok }`, or `{ ok: false, code, reason }` with `code` one of `not_found`, `invalid_payload`, `invalid_answer`, `unsupported_host` |
+
+`rpiv:ask-user:answer` takes `answers` — one `{ questionIndex, optionIndexes?, text?, notes? }`
+entry per question, where single-select takes one index or `text` and multi-select takes
+either or both — plus an optional `globalNote`, or `{ cancel: true }` to decline as `Esc`
+does. Validation is strict and all-or-nothing: a missing, duplicated, out-of-range or
+blank answer applies nothing and leaves the dialog open, since a partly applied answer
+would reach the model indistinguishable from one the user gave. The first answer wins,
+whether it came from the keyboard or from this event, and the events are terminal-only:
+RPC hosts answer through their own dialogs and return `unsupported_host`.
+
 ## Conditional surfaces
 
 Some parts of the dialog exist only under the right conditions:
@@ -68,6 +111,7 @@ Some parts of the dialog exist only under the right conditions:
 | 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"` |
+| Overlay instead of inline | Another questionnaire holds the editor slot, or an overlay that captures keys is on screen |
 | Full overlay hide on collapse | The host also exposes raw terminal input (the only path that can reopen a hidden overlay); without it, collapsing shrinks the dialog to a visible one-line row instead |
 | Localized chrome | `@juicesharp/rpiv-i18n` is installed |
 

package/docs/keyboard.md

@@ -13,7 +13,8 @@ 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` | Insert a normal space while typing; never toggle a checkbox. | Text inputs only |
-| `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 |
+| `n` | Open the notes editor for the focused question — or, on the Submit tab, the global note for the whole questionnaire. Configurable via `notesKey`. | Every question tab; the Submit tab in multi-question dialogs |
+| `1`–`9` | Act on the row with that number: answer a single-select question, toggle a multi-select row, or move to `Type something.` so you can type. A digit you bound yourself, or set as `notesKey`, keeps that meaning. | Option list |
 | `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 |
@@ -61,11 +62,17 @@ 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
+multi-select and whether or not its options carry previews. On non-Latin layouts set
+`notesKey` (see [Configuration](configuration.md)) to the character your keyboard types,
+or to a key spec such as `"ctrl+n"`. 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>`.
 
+A saved note stays visible after its editor closes, as one dimmed
+`Note for this answer: …` row that `n` reopens; the preview hint switches to
+`Note saved: press n to edit`, and the Submit-tab review uses the same label.
+
 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
@@ -76,15 +83,19 @@ keystrokes edit the buffer, so `n` types an `n`. Pasted line breaks are preserve
 
 ## 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.
+`Ctrl+]` gets the dialog out of the way: it shrinks to a single dim hint row, so the
+transcript 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.
+How it collapses depends on where the dialog opened. Inline (Pi's editor area) it simply
+keeps the editor slot and the one-line row. An overlay is marked hidden in Pi's overlay
+stack instead, and 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. A question that opened on top of `/btw` keeps its one-line row rather than
+hiding, since Pi closes overlays from the top of the stack and would otherwise pop `/btw`
+instead of the hidden question.
 
 While collapsed, every keystroke other than cancel is ignored, so you cannot mutate
 answers you cannot see.
@@ -95,15 +106,24 @@ among others — set a different `collapseKey`, or `"off"` to disable the shortc
 
 ## Layout
 
+The dialog opens inline in Pi's editor area below the transcript, where Pi's own prompts
+appear, and takes at most 70% of the terminal height (never fewer than 12 rows); it
+scrolls within that space, so the transcript above it stays scrollable while a question is
+open. A second questionnaire opened while an inline one is showing, or a question arriving
+while another overlay such as `/btw` is open, opens as an overlay on top instead, so the
+question on screen is the one receiving keys.
+
 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.
+When the dialog is taller than the space it has, the header and question stay pinned while
+the body scrolls between them and a sticky footer, and an overflow indicator shows which
+direction is clipped: `↑` for content above, `↓` for content below, `↕` for both. The
+markers never replace the focused row, padding is trimmed before content, and only the
+padding — never the body — is dropped to make the dialog fit.
 
 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

package/docs/localization.md

@@ -57,8 +57,13 @@ the footer hint segments (including the collapsed-state line and the Submit tab'
 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`.
+external-editor failure notification, the saved-note row label and the preview's "press
+<key> to edit" line, and the two RPC dialog prompts. Thirty-one keys in total, all under
+the namespace `@juicesharp/rpiv-ask-user-question`.
+
+The transcript receipts the model's answer is rendered into — the `✓`, `✗`, `not
+answered` and `no answer` strings — are translated too (`transcript.*`), because they are
+chrome in the transcript rather than prompt input.
 
 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/docs/tool-schema.md

@@ -100,27 +100,59 @@ 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.
+signal. Partial submission is allowed: unanswered questions contribute no segment, and
+their question text is listed in an `unanswered: "<question>", …` segment after the
+answers, with the same indexes in `details.unanswered`. A global note counts as an answer
+on its own, so a note with every question blank still yields the answered envelope.
 A cancelled result always reads as the decline in text; its note, if any, survives only
 in `details.globalNote`.
 
 ## 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:
+The package publishes three events on Pi's event bus — one before the dialog is shown, two
+bracketing the wait — and accepts a fourth that answers the questionnaire from outside the
+terminal. Import them from the `/events` subpath:
 
 ```ts
-import { ASK_USER_PROMPT_EVENT, type AskUserPromptEventPayload } from "@juicesharp/rpiv-ask-user-question/events";
+import { ASK_USER_PROMPT_EVENT, type AskUserPromptEventPayload } from "@fadhelhaidar/pi-ask-user/events";
 
 pi.events.on(ASK_USER_PROMPT_EVENT, (payload: AskUserPromptEventPayload) => {
-  // payload.questions[].{ question, header, multiSelect, options[] }
+  // payload.toolCallId, 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.
+process or network boundary stay cheap. The prompt event fires after validation passes and
+before the dialog is shown; `rpiv:ask-user:blocked` then brackets the wait with
+`{ active: true, toolCallId }` and `{ active: false, toolCallId }`, including when the
+dialog never mounts because an answer arrived first.
+
+## Answering from outside the terminal
+
+A supervisor, bridge or test harness emits `rpiv:ask-user:answer` on the same bus:
+
+```ts
+pi.events.emit(ASK_USER_ANSWER_EVENT, {
+  toolCallId,
+  answers: [{ questionIndex: 0, optionIndexes: [1], notes: "keep the bus factor up" }],
+  globalNote: "ship on Tuesday",
+});
+```
+
+`answers` carries one entry per question — `optionIndexes` for chosen options (authored
+order is preserved, not the order given here), `text` for a typed custom answer, `notes`
+for that question's note; multi-select accepts both `optionIndexes` and `text` together,
+single-select takes one index or `text`. Send `{ cancel: true }` instead to decline as `Esc`
+does. Every attempt gets exactly one `rpiv:ask-user:answer-result` verdict:
+`{ ok: true }`, or `{ ok: false, code, reason }` with `code` one of `not_found`,
+`invalid_payload`, `invalid_answer` or `unsupported_host`. Validation is strict and
+all-or-nothing — a blank, duplicated or out-of-range answer applies nothing and leaves the
+dialog open — and the first answer wins, whether it came from the keyboard or this event.
+Questionnaires are addressed by the `toolCallId` on the prompt event, so parallel calls
+are independent. Events answer terminal dialogs only; RPC hosts answer through their own
+dialogs and reject with `unsupported_host`.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhelhaidar/pi-ask-user",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Standalone Pi questionnaire with combined multi-select and custom answers, Enter-only toggling, and preserved drafts.",
   "type": "module",
   "license": "MIT",
@@ -57,8 +57,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.2",
-    "@earendil-works/pi-tui": "1.0.2",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@juicesharp/rpiv-i18n": "2.12.0",
     "typescript": "5.9.3",
     "vitest": "4.1.10"

package/dist/chunks/index-bx2tbz93.js

@@ -1,5 +0,0 @@
-// events.ts
-var ASK_USER_PROMPT_EVENT2 = "rpiv:ask-user:prompt";
-var ASK_USER_BLOCKED_EVENT2 = "rpiv:ask-user:blocked";
-
-export { ASK_USER_PROMPT_EVENT2, ASK_USER_BLOCKED_EVENT2 };