@signalridge/pi-ask-user-question

A stable Pi extension that registers a structured ask_user_question tool. It lets an LLM pause for focused user decisions and receives a bounded, structured JSON answer.

Install

pi install npm:@signalridge/pi-ask-user-question

The package is opt-in. Its Pi manifest loads src/index.ts, which registers the tool when the package is enabled.

Tool contract

The tool accepts one to four questions. Every question has a prompt and two to four options. id, header, value, description, multiSelect, and allowOther are optional; multiSelect defaults to false and allowOther defaults to true.

{
  "questions": [
    {
      "id": "storage",
      "header": "Storage",
      "question": "Which storage should the feature use?",
      "options": [
        { "label": "SQLite", "value": "sqlite", "description": "Local and transactional." },
        { "label": "JSON", "value": "json", "description": "Simple and portable." }
      ],
      "allowOther": true
    }
  ]
}

Results have the same JSON payload in content[0].text and typed details. Successful answers contain ordered answers with the question identity plus selected option label/value/index or free text. Cancellations contain cancelled, a reason, and any answers collected before cancellation.

Interaction

In TUI mode the tool opens a centered overlay with a visible top and bottom Pi border and a consistent side frame. Its outer border uses the theme's borderAccent color (purple in the Signalridge themes). It presents one question at a time, shows [n/total] progress for batches, displays option descriptions, supports single select, checkbox-like multi-select with an explicit Done row, Other free text, Back to revise an earlier answer, and Escape cancellation. Free-text editor input remains inside the same border and forwards focus to Pi's Editor for correct cursor and IME placement. PageUp/PageDown scroll the question and option descriptions without changing the selected answer. While reading, Enter or Space first returns to the selected control rather than submitting or toggling an offscreen answer; arrow keys resume option navigation.

RPC mode uses Pi's abortable sequential select and input requests instead of custom, including multi-select and Back where the RPC UI supports repeated selections. Other answers use single-line input in RPC; TUI keeps its multiline editor. Print mode and contexts without UI return a structured cancellation without opening a dialog.

Other answers are stored without display sanitization: multiline text, leading/trailing spaces, and emoji joiners are retained. Responses over 4,000 UTF-16 code units are explicitly rejected for correction, never silently clipped. TUI stores the public editor's expanded draft; Pi's editor itself normalizes tabs to spaces and CR/CRLF to LF before exposing that draft. RPC stores the returned input string unchanged. Labels and question text are sanitized only as display copies. UI failures return ui_error with completed partial answers; cancellation and abort remain distinct.

The tool is registered with executionMode: "sequential", so two question dialogs cannot overlap.

Development

bun run check