@fyeeme/pi-ask-user 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -2,52 +2,48 @@
 
 ## [Unreleased]
 
-## [2.0.0] - 2026-08-25
+## [2.0.1] - 2026-08-27
 
-**Major release — first npm publication.** Ships as part of the 2.0 extensions family wave (pi-review / pi-dynamic-workflows / pi-subagents). Highlights below.
+Renamed to `@fyeeme/pi-ask-user` (formerly `@fyeeme/pi-omp-ask`, whose 2.0.0 release carried this codebase); the lightweight `ask_user` extension formerly published under this name now lives as `@fyeeme/pi-ask-user-lite`.
 
-### Added
+### Changed
 
-- Review page: multi-question dialogs summarize all answers (custom inputs, notes, unanswered warnings) after the last question; `enter` confirms, `left` revises before submitting. Single-question dialogs keep submitting immediately.
-- Per-question status strip (`●`/`○` chips labeled with `header`) showing which questions are answered.
-- Inline free-text editor for `Other` answers and notes: the option list stays visible while typing, `esc` returns to the rows, an empty submit declines, and revising prefills the previous text. The dialog no longer closes and reopens around a plain input.
-- Numbered options: rows render `1. label` and answers echo the number back to the LLM (`auth: 1. JWT`).
-- `tab` / `shift+tab` as aliases for `right` / `left` question navigation.
+- README synced with the current code: per-answer-note and chat-redirect references removed, the transcript description updated to the compact one-line render, and the timeout expiry wording fixed (recommended option, not "noted or recommended"); added a sister-extension comparison table and a user-facing Features section.
+- Transcript subtraction: `renderResult` now renders one compact `question → answer` line per question (multi-question lines prefixed `[id]`) instead of a framed block that re-listed every option with radio/checkbox markers; unselected options no longer appear in the transcript, and the framed chrome (`FramedComponent`) is gone.
+- The Submit review tab now appears only for 3+ questions or any `multi` question; 1–2 single-select questions advance Enter-to-submit without a review page.
+- Side-by-side preview: on wide terminals (inner width ≥ 80) questions carrying previews split into an options pane and a preview pane that follows the cursor (fzf-style, anchored at the top of the body); narrow terminals keep the inline preview under each option.
 
 ### Fixed
 
-- Single-select questions no longer look multi-selectable: `space` is now a no-op outside `multi` mode, and selecting a different option replaces the previous `(o)` marker instead of stacking another one.
-- Multi-select `enter` with nothing checked is now a no-op instead of recording an empty answer that lit the status chip `●` but echoed `(no selection)` back to the LLM. Users who mean "none of these" can say so via `Other`.
-
-### Changed
-
-- Submitting a custom `Other` answer now also clears stale checkbox marks from the same question.
-- Answering a revisited question now jumps to the next unanswered question (or straight to the review page when everything is answered) instead of always stepping one forward and forcing a re-walk of already-answered questions.
+- IME drift in the custom-input prompt, fixed the way pi's TUI documents it (Focusable / "Container Components with Embedded Inputs"): the dialog now implements `Focusable` (propagating focus to an embedded pi-tui `Input` while the prompt is open), and the `Input` renders the input line itself — emitting `CURSOR_MARKER` at the cursor so the TUI positions the hardware cursor and the IME candidate window at the input point — with the full pi-tui input semantics for free: multi-char CJK IME commits, grapheme-aware cursor/delete (emoji as one unit), bracketed paste buffering, kitty CSI-u printable decoding, undo, and kill ring.
+- Transcript no longer shows the questions twice around an ask: `renderCall` now renders only a `Ask · N questions`
+  summary line while the dialog is pending, and the full framed question/options/answer block renders once from
+  `renderResult` after the user answers. omp updates the framed block in place; pi's `ToolExecutionComponent` appends
+  result renders below call renders, so the call-side block was removed instead of duplicated. The call-side
+  streaming-args normalization (`normalizeRenderOptions`/`normalizeRenderQuestions`) became dead code and was removed.
+### Removed
 
-## [1.2.0] - 2026-07-20
+- The per-answer note subsystem (`n` key, `✎ note` markers, note lines in the Submit review and transcript, `note` fields in results/details, and the legacy path's note plumbing).
+- Dead chat-redirect surface: `ExtensionAskDialogChatResult`, `AskToolDetails.chatRedirect`/`questions`, and the unreachable `kind: "chat"` branches (the dialog never produced a chat result).
 
-### Added
-
-- `/ask-demo` command: interactive four-phase battery covering all question types, free-form `Other` input, timeout auto-selection, chat redirect, and cancel semantics — each phase reports the exact text the LLM would receive.
 
-## [1.1.0] - 2026-07-20
+## [0.1.0] - 2026-08-23
 
-### Added
+### Fixed
 
-- Single full-screen dialog for all questions: `[n/m]` progress counter, `←`/`→` navigation between questions, answer revision with preserved cursor/selection state.
-- `timeoutSeconds` parameter: overall budget; on expiry unanswered questions auto-select the recommended option and are flagged `timedOut` in the result.
-- `header` question chip, option `preview` lines rendered under the cursored row, and `note` attachment via the `n` key.
-- `Chat about this` reserved row: ends the call with a `chatRedirect` result so the LLM can switch to discussion.
-- Reserved-label collision check in the execution path (fails fast instead of rendering duplicate rows).
-- Agent abort now closes an open dialog and settles the tool as cancelled instead of leaving it pending.
+- Embedded prompt (Other/note) submit ordering: the input is now applied to state before the deferred timeout runs, so a countdown that expires mid-typing keeps the user's answer instead of discarding it and force-picking (omp `#promptForCustomInput` ordering; the old behavior was also asserted by a test, now corrected).
+- Transcript rendering now measures at the live frame width instead of a hardcoded 80 columns, so narrow terminals no longer clip question text.
+- `raceWithSignal` propagates dialog failures instead of swallowing them as a phantom "user cancelled" outcome (matches omp `untilAborted` and the local legacy-path helper).
+- Restored omp's `helpText` construction for the legacy path's select dialogs.
 
 ### Changed
 
-- Multi-select `enter` records the current checkbox set as-is (`space` toggles); re-selecting a single-select option replaces a previous custom input.
-
-## [1.0.0] - 2026-07-20
+- Terminal bell on ask can be disabled with `PI_OMK_ASK_NOTIFY=0`; the `timeoutSeconds` schema description now states exactly when the countdown resets and what expiry picks.
+- Removed unused imports and zero-call-site helper exports; typed the test harness result.
 
 ### Added
 
-- `ask_user` tool: multi-question clarifying prompts with single/multi select, recommended defaults, option descriptions, and free-form "Other" input.
-- Custom TUI picker (radio/checkbox) rendered via `ctx.ui.custom`; answers persisted in tool result details for branch-safe replay.
+- Source migration of oh-my-pi's `ask` tool into a pi extension: `AskTool.execute` (chat redirect, empty-single-select cancellation, multi-question navigation loop), the tabbed `AskDialogComponent` (Submit review tab, radio/checkbox markers, per-answer notes, markdown/code previews, fixed-height panel, cursor-following scroll, inactivity countdown with deferred expiry mid-prompt), the legacy per-question selector path (multi-select toggle loop, `+ Done selecting`, timeout tolerance heuristic), the countdown timer, overlay box chrome, theme symbol defaults, and the `ask.md` tool description.
+- pi host adaptation: rich dialog via `ctx.ui.custom()`, RPC degradation to native `ui.select`/`ui.editor`, headless hiding through `session_start` + `setActiveTools` with an execute backstop, `executionMode: "sequential"` in place of omp's exclusive concurrency, `timeoutSeconds` parameter replacing the settings-driven `ask.timeout`, terminal bell replacing desktop notifications, and keybinding-aware select keys via the injected `KeybindingsManager`.
+- omp error semantics: cancel aborts the agent turn (`ctx.abort()` + tool error); unreachable hosts raise a distinct "question was never shown" error.
+- 45 tests covering the dialog component, the legacy selector logic (driven against the full omp UIContext contract), and the tool's host gating.

package/README.md

@@ -1,75 +1,129 @@
 # pi-ask-user
 
-**2.0.0 — first npm release**, part of the 2.0 extensions family wave. Release highlights:
+- **Faithful omp port** — the tabbed ask dialog (Submit review tab, radio/checkbox markers, markdown/code previews with fence splitting and render caching), the inactivity countdown, and the legacy per-question selector path carried over file-by-file.
+- **Compact transcript** — the pending call renders only an `Ask · N questions` summary; the result renders one compact `question → answer` line per question (multi-question lines prefixed `[id]`) — no framed block, no re-listed options.
+- **Robustness fixes over the omp source** — countdown expiry mid-typing keeps the user's answer, live frame-width measurement replaces the hardcoded 80 columns, and dialog failures propagate instead of degrading to a phantom "user cancelled".
+- **Headless-safe** — print/JSON hosts cannot prompt, so the tool is stripped from the active set; a stray call throws a "question was never shown" error instead of hanging.
 
-- **Review page** — multi-question dialogs summarize every answer (custom inputs, notes, unanswered warnings) before submitting; `enter` confirms, `left` revises.
-- **Inline free-text editor** — `Other` answers and notes type directly inside the dialog (option list stays visible, `esc` returns, empty submit declines).
-- **Numbered options** — rows render `1. label` and answers echo the number back (`auth: 1. JWT`), plus a per-question status strip and `tab`/`shift+tab` navigation.
-- Selection semantics hardened: single-select no longer stacks markers, multi-select `enter` with nothing checked is a no-op, custom `Other` answers clear stale checkboxes.
+oh-my-pi's `ask` tool, migrated to a [pi](https://github.com/earendil-works/pi-coding-agent) extension.
 
-Structured `ask_user` tool for [pi](https://github.com/earendil-works/pi-coding-agent). It lets the LLM surface clarifying questions with selectable options while it works, instead of guessing when choices have materially different tradeoffs.
-
-Ported from the interactive ask flow of [oh-my-pi](https://github.com/can1357/oh-my-pi), adapted to pi's public extension API.
+This is a source migration of the interactive ask feature from
+[oh-my-pi](https://github.com/can1357/oh-my-pi) (a fork of badlogic/pi-mono), not a reimplementation: the tool flow,
+the tabbed ask dialog, the legacy per-question selector path, and the result wording are carried over from
+`packages/coding-agent/src/tools/ask.ts` and `src/modes/components/ask-dialog.ts`, then adapted file-by-file to pi's
+public extension API. Sister extension of [pi-ask-user-lite](../pi-ask-user-lite); the two expose different tools
+(`ask` vs `ask_user`) and should not be enabled together — see
+[pi-ask-user or pi-ask-user-lite?](#pi-ask-user-or-pi-ask-user-lite) below.
 
 ## Features
 
-- **Multiple questions in one dialog** — all questions presented through a single dialog with a `[1/3]` progress counter and a per-question status strip (`● Framework  ○ Style`); `←` revisits earlier questions to revise answers (cursor and selections preserved), `→` moves forward once the current question is answered.
-- **Review before submit** — after the last question, multi-question dialogs show a summary page listing every answer (custom inputs, notes, unanswered warnings); `enter` confirms, `←` goes back to revise. Single-question dialogs still submit immediately.
-- **Smart advance** — answering jumps to the next unanswered question, or straight to the review page once everything is answered; revising an earlier answer never forces a re-walk of already-answered ones.
-- **Single or multi select** — `multi: true` renders checkboxes (`space` toggles, `enter` records the set and is a no-op while nothing is checked); single-select renders radio markers with the recommended option pre-cursored and suffixed `(Recommended)`.
-- **Timeout auto-selection** — optional `timeoutSeconds` budget for the whole dialog; on expiry unanswered questions auto-select the recommended option (or the first) and are flagged `timedOut` so the LLM knows no human chose them.
-- **Option descriptions & previews** — short tradeoff text under each label; an option's `preview` lines render while the cursor rests on it. Options render and echo back numbered (`1. label`), so answers read `auth: 1. JWT`.
-- **Free-form "Other"** — every question gets an automatic `Other (type your own)` row that opens an editor embedded in the dialog: the option list stays visible while typing, `esc` returns to the rows, and an empty submit declines. Re-selecting an option clears a previous custom input.
-- **Answer notes** — press `n` to attach a note through the same inline editor (prefilled when revising); notes are echoed back to the LLM.
-- **"Chat about this" redirect** — a reserved row that ends the call with a `chatRedirect` result, telling the LLM the user prefers discussing over answering.
-- **Abort-safe** — if the agent turn is aborted while a question is open, the dialog closes and the tool settles as cancelled instead of hanging.
-- **Branch-safe state** — answers live in the tool result `details`, so `/tree` branching and session replay see exactly what was asked and answered.
-- **Headless-safe** — throws a proper tool error in `-p`/JSON modes instead of hanging.
+- **Tabbed multi-question dialog** — one question per tab with `header` chips in the tab bar, radio markers for single-select, checkboxes for `multi`; select keys resolve through the injected `KeybindingsManager`, so rebound keys keep working.
+- **Submit review gate** — calls with 3+ questions or any `multi` question get a Submit review tab before the answers go out; 1–2 single-select questions advance Enter-to-submit without a review page.
+- **Markdown/code previews** — an option's `preview` (markdown, fenced code) renders fence-split with render caching. On wide terminals (inner width ≥ 80) the dialog splits into an options pane and a cursor-following preview pane (fzf-style); narrow terminals keep the preview inline under the cursored row.
+- **Inline `Other` input with real editor semantics** — the dialog implements pi's `Focusable` contract and embeds a pi-tui `Input` that renders the input line itself: the hardware cursor and IME candidate window sit at the input point, with multi-char CJK IME commits, grapheme-aware cursor/delete (emoji as one unit), bracketed paste, kitty CSI-u decoding, undo, and kill ring. A countdown expiring mid-typing keeps the typed answer.
+- **Inactivity countdown** — `timeoutSeconds` is an idle budget: dialog keypresses reset it (not while typing); expiry auto-picks the recommended option (or the first) and marks it `auto-selected after timeout`.
+- **Compact transcript** — the pending call renders a single `Ask · N questions` line; the result renders one compact `question → answer` line per question (`[id]`-prefixed on multi-question calls) without re-listing unselected options.
+- **omp semantics kept** — cancelling aborts the agent turn; headless hosts (print/JSON) strip the tool at `session_start` with an execute backstop that errors "question was never shown"; a terminal bell rings on ask (opt out with `PI_OMK_ASK_NOTIFY=0`); answers persist in the tool result `details`.
+
+## What migrated
+
+| oh-my-pi source | Here | Notes |
+|---|---|---|
+| `tools/ask.ts` — `AskTool.execute` | `index.ts` | result-count validation, empty-single-select cancellation (#8265), multi-question loop with navigation state, cancel-aborts-turn semantics |
+| `tools/ask.ts` — `askSingleQuestion` + custom-input title windowing | `src/ask-legacy.ts` | multi-select toggle loop with `+ Done selecting`, recommended suffixes, `Other` via editor, timeout tolerance heuristic (`TIMEOUT_DETECTION_TOLERANCE_MS`), `(i/n)` progress titles |
+| `modes/components/ask-dialog.ts` — `AskDialogComponent` | `src/ask-dialog.ts` | tabbed dialog, Submit review tab, radio/checkbox markers, markdown/code previews with fence splitting and render caching, fixed-height panel sizing, cursor-following scroll, inactivity countdown, malformed-args normalization |
+| `modes/components/countdown-timer.ts` | `src/countdown-timer.ts` | verbatim |
+| `modes/components/overlay-box.ts` (subset) | `src/overlay-box.ts` | `topBorder`/`divider`/`row`/`bottomBorder`/`fit` |
+| `prompts/tools/ask.md` | `index.ts` | tool description, verbatim |
+| theme symbol defaults (`modes/theme/symbols.ts`) | `src/compat.ts` | `❯ ◉ ○ ☑ ☐ ╭╮╰╯` |
+
+## Adaptation notes (omp surface → pi extension API)
+
+Each omp-internal surface maps onto the closest public pi extension boundary:
+
+- **`AgentTool` + `createIf` gate** → `pi.registerTool` + `session_start` strip: print/JSON hosts cannot prompt, so the
+  tool is removed from the active set; if it is still called, `execute` throws with a "question was never shown" error
+  so the model stops retrying instead of misreading a cancel.
+- **ArkType schema + reserved-label narrow** → typebox schema; the narrow runs at the top of `execute`.
+- **`concurrency: "exclusive"`** → `executionMode: "sequential"` (pi tool batches).
+- **`ExtensionUIContext.askDialog`** → `ctx.ui.custom()` mounting `AskDialogComponent`.
+- **`#presentDialog` serial queue** → not needed: `ui.custom()` is a single editor slot and the sequential execution
+  mode already serializes ask calls.
+- **Nested `HookEditorComponent` prompts** (Other) → an embedded prompt mode inside the dialog: pi extensions own
+  one custom component slot, so the dialog renders the input row itself (`#promptActive`) with Enter confirm / Esc back.
+- **Keybindings** — omp's global `matchesSelectUp/…` matchers resolve through the `KeybindingsManager` pi injects into
+  `ui.custom()`, so rebound select keys keep working; footer hints use the configured keys.
+- **`ui.select` dialog options** — pi's select accepts only `{signal, timeout}`. The legacy path keeps the full omp
+  `UIContext` logic (initial index, navigation, markers, timeout callbacks) and degrades on pi: no radio/checkbox
+  markers, no initial cursor, no ←/→ question navigation, and option descriptions are dropped from the visible list.
+- **`ui.editor` prompt style** → pi's `ui.editor` (multi-line) with a signal race; falls back to `ui.input`.
+- **settings `ask.timeout` / `ask.notify`** → `timeoutSeconds` tool parameter + terminal bell, opt-out with
+  `PI_OMK_ASK_NOTIFY=0` (pi extensions cannot read pi settings or send desktop notifications).
+- **`ToolAbortError` + `context.abort()`** → `ctx.abort()` + thrown error (cancel aborts the agent turn, omp semantics).
+- **Transcript renderer** — omp merges call+result in one framed block that updates in place when the user answers;
+  pi's tool rows append the result render below the call render, so the call slot renders only a `Ask · N questions`
+  summary line while pending, and the result slot renders one compact `question → answer` line per question
+  (multi-question lines prefixed `[id]`, with the `auto-selected after timeout — not a user choice` marker).
+
+**Dropped (no pi extension surface):** TTS vocalizer, plan-mode timeout suppression, collab guest racing, ACP
+elicitation forms, `/tree` re-answer, `loadMode: "discoverable"`, the draft-editor input guard, and
+`renderInlineMarkdown` for labels (labels render as plain text; block markdown in questions/previews still uses pi's
+Markdown component + `getMarkdownTheme`). Post-2.0 the per-answer note subsystem and the dead chat-redirect surface
+were also removed (see [Unreleased](./CHANGELOG.md)).
 
 ## Tool schema
 
 ```text
-ask_user(
+ask(
   questions: [
     {
       id: string              // stable identifier, echoed in the answer
       question: string        // shown to the user
-      header?: string         // short chip rendered next to the progress counter
-      options: [{             // 2-6 options
+      header?: string         // short chip in the tab bar
+      options: [{
         label,
         description?,         // tradeoff text under the label
-        preview?              // lines shown while the cursor rests on the option
+        preview?              // markdown / fenced code shown under the cursored option
       }]
       multi?: boolean         // allow multiple selections
-      recommended?: number    // 0-based index of the recommended option
+      recommended?: number    // 0-based index; "(Recommended)" added automatically
     }
   ],
-  timeoutSeconds?: number     // overall budget; expiry auto-selects recommended
+  timeoutSeconds?: number     // omp settings ask.timeout, parameterized; idle budget,
+                             // dialog keypresses reset it (not while typing Other),
+                             // expiry auto-picks the recommended option (or the first)
 )
 ```
 
-## Keys
+## Result semantics (omp wording, verbatim)
 
-| Key | Action |
-|-----|--------|
-| `up` / `down` | Move cursor across rows |
-| `space` | Toggle checkbox (multi-select only) |
-| `enter` | Select / record answer / advance to the next unanswered question (no-op in multi-select with nothing checked); on the review page, submit |
-| `←` / `→` | Previous / next question (`→` requires an answer first) |
-| `tab` / `shift+tab` | Aliases for `→` / `←` |
-| `n` | Attach a note to the current answer |
-| `esc` | Cancel the whole call (inside the inline editor: back to the rows) |
+```text
+User selected: JWT
+User provided custom input: mTLS everywhere
+User answers:
+auth: JWT
+deploy: [staging, prod]
+deploy: staging (auto-selected after timeout)
+```
 
-## Trying it out: `/ask-demo`
+Cancelling (Escape) aborts the agent turn — omp's "cancel the whole call" semantics, via `ctx.abort()` plus a tool
+error. An unreachable host (print/JSON) raises a different error stating the question was never displayed.
 
-The extension registers an interactive battery that exercises every feature end-to-end:
+## pi-ask-user or pi-ask-user-lite?
 
-1. **All question types** — single-select with `(Recommended)` + cursor-rest `preview`, multi-select checkboxes, and an `Other (type your own)` free-form answer (add a note with `n` on the last question), then confirm on the review page.
-2. **Timeout** — a dialog with a 6-second budget; do nothing and watch it auto-select the recommended option.
-3. **Chat redirect** — pick the `Chat about this` row.
-4. **Cancel** — press `Esc` on the first of two questions and confirm the second is never asked.
+Sister packages with intentionally different scopes — pick one, do not enable both:
 
-Each phase reports the collected answers back through a notification so you can verify what the LLM would receive.
+| | pi-ask-user (this one, tool `ask`) | pi-ask-user-lite (tool `ask_user`) |
+|---|---|---|
+| Lineage | File-by-file source port of oh-my-pi's `ask` tool | Pi-native reimplementation of the ask flow |
+| Dialog | Tabbed dialog; Submit review tab for 3+ questions or any `multi`; fzf-style side-by-side preview pane on wide terminals | Single question-page dialog with `[n/m]` counter and per-question status strip; review page after the last question |
+| Option rows | omp radio/checkbox markers | Numbered (`1. label`); answers echo the number back |
+| Previews | Markdown/code, fence-split with render caching | Plain `preview` lines under the cursored option |
+| Timeout | Inactivity countdown reset by keypresses (paused while typing); expiry auto-picks the recommended option | Whole-dialog budget; expiry auto-selects recommended and flags `timedOut` |
+| Notes | Not available (removed post-2.0) | Per-answer notes via `n`, echoed to the LLM |
+| Chat redirect | Removed (dead omp surface) | Reserved `Chat about this` row |
+| Cancel | Aborts the agent turn (omp semantics) | Tool settles cancelled; the LLM is told to proceed conservatively |
+| Extras | Terminal bell (opt out with `PI_OMK_ASK_NOTIFY=0`) | `/ask-demo` interactive battery |
 
 ## Install
 
@@ -87,48 +141,14 @@ Or load ad hoc:
 pi -e ./packages/extensions/pi-ask-user/index.ts
 ```
 
-## Usage
-
-Just ask the agent something ambiguous; with the tool active the LLM can call:
-
-```json
-{
-  "questions": [
-    {
-      "id": "storage",
-      "question": "Which storage backend should this feature use?",
-      "options": [
-        { "label": "SQLite", "description": "Zero-config, file-based" },
-        { "label": "PostgreSQL", "description": "Full server, richer types" }
-      ],
-      "recommended": 0
-    },
-    {
-      "id": "flags",
-      "question": "Which extras should be enabled?",
-      "multi": true,
-      "options": [{ "label": "Telemetry" }, { "label": "Auto-update" }]
-    }
-  ]
-}
-```
-
-The user picks with arrow keys (`space` toggles in multi mode, `enter` submits, `←` revises earlier answers, `esc` cancels). Cancelling marks the call cancelled and tells the LLM to proceed conservatively.
-
-## Boundaries
-
-- Requires an interactive session (TUI or RPC); in print/JSON mode the tool errors out.
-- No per-question timers: `timeoutSeconds` budgets the whole dialog, not each question.
-- No TTS, system-level notifications, or `/tree` re-answer branching — pi's extension API does not expose those surfaces; answers remain inspectable via persisted `details`.
-
 ## Development
 
 ```bash
-npm install --ignore-scripts
+npm install
 npm run typecheck
 npm test
 ```
 
 ## License
 
-MIT
+MIT — the migrated oh-my-pi sources retain their upstream origin (can1357/oh-my-pi, fork of badlogic/pi-mono).