pi-native-questions0.2.0

pi-native-questions

RPIV-style questions. Clean outline tabs. Native Pi lifecycle.

A Pi package that gives your agent an ask_user_question tool with Markdown previews, multiselect, custom answers, notes, and a review step—without losing the terminal's “waiting for you” indicator.

The UI adapts RPIV's wrapping choices, checkboxes, inline input, preview boxes, and submit picker. Tabs use thin outlines and square completion markers, without navigation arrows or background fills.

Built for Pi 1.5.0+ and Node.js 24+. Works in any Pi terminal; Rex additionally displays Pi's native blocked/question state.

Install

pi install npm:pi-native-questions

Then run /reload in existing Pi sessions. Try /ask-demo to explore the interface without making a model request.

Replacing another question package

Only one extension should register ask_user_question. If you use RPIV's questionnaire:

pi remove npm:@juicesharp/rpiv-ask-user-question
pi install npm:pi-native-questions

Run /reload. The tool name and input structure stay familiar; existing instructions using ask_user_question continue to work. Other RPIV packages, including rpiv-todo, can stay installed.

What you get

• Single-select and multiselect, with 2–12 options per question.
• Related questions in one batch: prefer 1–4; up to 8.
• Markdown previews: code, diagrams, tables, or mockups. Side-by-side on wide terminals; stacked on narrow terminals. Page through long previews.
• Custom text, with Pi's native multiline editor and IME focus handling.
• Question notes and a global note, plus a review tab before submission.
• Back/next navigation, retained answers, search, and compact mode.
• Explicit partial answers: unanswered questions are identified, never silently accepted.
• Safe cancellation and abort cleanup. No auto-answer timeout or inferred approval.
• Native RPC fallback using Pi's select/input dialogs.
• Model-neutral tool schema and repair of double-encoded nested JSON from some tool-call parsers.
• Codemode compatibility: remains a top-level, model-visible interactive tool even when codemode controls other tools.

Why Rex sees the right state

The rich UI combines adapted RPIV visual components with Pi's own Editor, Markdown, theme, and public dialog API:

ctx.ui.custom(factory, {
  overlay: false,
  blocked: { kind: "question", message: "Waiting for your answer" },
});

Pi owns the terminal status record. This package does not write OSC escape sequences, shell out to Rex, inspect terminal screens, or install another lifecycle reporter. Closing or cancelling the dialog lets Pi restore the underlying agent state.

The dialog is deliberately inline, not an overlay: Pi 1.5.0 ignores the blocked option on custom overlays. Normal transcript scrolling stays with Pi.

Keyboard controls

Key	Action
↑ / ↓	Move between choices (respects Pi's selection bindings)
Enter	Pick a single choice, toggle a multi choice, or activate Next
Space	Toggle the focused multi choice
Tab / Shift+Tab, ← / →	Navigate question and review tabs
N	Edit a question note; on review, edit the global note
/	Search option labels and descriptions; Enter finishes searching
PgUp / PgDn	Scroll the focused option's preview or the review summary
Ctrl+]	Collapse/expand the dialog without answering it (Ctrl+O also works)
Escape	Leave the editor/search, or cancel the questionnaire
Ctrl+C	Cancel the questionnaire

In the editor, Enter saves, Shift+Enter adds a newline, and Escape discards the current edit. Pi's native editor bindings apply. Fullscreen mouse support delegates option selection and editor interactions to Pi's components.

Multiselect choices are retained when navigating tabs. A single-question dialog submits when you confirm a choice or activate Next; it does not add a redundant review step. Multi-question batches have a review tab with explicit Submit answers and Cancel choices. You can submit a partial batch; the model is told which questions remain unanswered.

Tool input

No provider-specific API or extra model call is involved. Models that support Pi tool calling receive a plain object schema:

{
  "questions": [
    {
      "header": "Storage",
      "question": "Which storage approach should we use?",
      "options": [
        {
          "label": "Postgres (Recommended)",
          "description": "Transactions and relational queries.",
          "preview": "### Postgres\n\n```sql\nSELECT * FROM projects;\n```"
        },
        {
          "label": "SQLite",
          "description": "A simpler embedded database."
        }
      ]
    },
    {
      "header": "Features",
      "question": "Which features should ship first?",
      "multiSelect": true,
      "options": [
        { "label": "Search", "description": "Find existing records." },
        { "label": "Audit history", "description": "Explain who changed what." }
      ]
    }
  ]
}

• header: required, 1–16 characters.
• Option label: required, 1–60 characters.
• Option description: required; an empty string is allowed.
• preview and multiSelect: optional. Previews also work on multi choices.
• Put recommendations first and append (Recommended).
• Do not author Other, Type something., or Next choices; those labels are reserved for UI actions.

The model receives the familiar User has answered your questions: ... envelope. Structured tool details retain answers, selection kind, selected labels, notes, previews for single choices, cancellation, and unanswered question indexes. Large text envelopes are capped at Pi's 50 KB / 2,000-line limit; full text is saved in a private local temporary file and its path is returned.

Compatibility boundaries

• Model compatibility follows Pi's provider adapters; not every model/provider has been live-tested. The schema avoids root unions and references, and known nested-JSON parser artifacts are covered by tests.
• In RPC mode, the host's standard select/input dialogs replace the rich UI. Previews are plain text; notes/review/collapse are TUI features.
• Print/JSON modes cannot ask a human and return an explicit tool error rather than guessing an answer.
• This is not a byte-for-byte RPIV fork. RPIV-specific event-bus remote answering, localization, and presentation configuration are not implemented.
• “Native” means native Pi components and dialog lifecycle—not macOS system dialogs. Multiselect and previews require a custom inline component.

Privacy

No telemetry, network requests, model requests, or shell commands are made by the package. Question content is rendered locally. Pi and your selected model provider handle tool calls and answers normally.

Only the fixed message “Waiting for your answer” enters the terminal program-status record; the question and answer text do not. Oversized result text is written locally with owner-only file permissions.

Development and validation

The npm tarball includes source and tests:

npm install --ignore-scripts
npm run typecheck
npm test
npm run smoke:rex  # opt-in: requires installed Pi + a running Rex server
npm pack --dry-run

The Rex integration test creates and removes its own throwaway session. It uses a local deterministic provider fixture—no real API keys or external model requests—and verifies the actual registered tool's:

working → blocked/question → working → done

It also checks submission, previews, multiselect, cancellation, and abort cleanup. Unit tests cover argument repair, schema shape, RPC fallback, Unicode/narrow rendering, notes, navigation, and bounded output.

Credits and license

Inspired by HenryQW's native-dialog approach. Visual components and compatibility behavior are adapted from juicesharp's @juicesharp/rpiv-ask-user-question 2.15.0 (MIT), with clean outlined tabs replacing the original filled tabs. Upstream attribution and local changes are documented in src/rpiv/UPSTREAM.md. See LICENSE. No RPIV package is installed as a runtime dependency.