Interactive Questionnaire

Interactive Questionnaire is a pi Extension Package that registers the agent-facing ask_user tool for structured user feedback. It lets agents ask 1–5 questions, each with 2–5 predefined Choices plus an always-available Custom Answer row labeled Something else….

The package supports cancellation, compact transcript rendering, and /ask-user-demo, a human-facing command that launches a sample questionnaire and writes the formatted JSON result into the editor for inspection or copying.

Install

Install the published npm package:

pi install npm:@hugo-hsi-dev/pi-interactive-questionnaire

Install from a local checkout for development:

pnpm install
pnpm build
pi install ./extensions/interactive-questionnaire

Demo command

Run this in pi:

/ask-user-demo

Answer the sample questionnaire, try the Custom Answer row, or press Escape to cancel. The command writes the result JSON into the editor instead of adding it to the session transcript.

Tool

Registered tool: ask_user

Input always uses a questions array, even for one question:

{
  "questions": [
    {
      "id": "direction",
      "label": "Direction",
      "prompt": "Which implementation direction should we take?",
      "choices": [
        { "value": "minimal", "label": "Minimal skeleton" },
        { "value": "complete", "label": "Full v1 UI", "description": "Include demo and docs." }
      ]
    }
  ]
}

Result examples

Predefined Choice result:

{
  "answers": [
    {
      "id": "direction",
      "value": "minimal",
      "label": "Minimal skeleton",
      "wasCustom": false,
      "index": 1
    }
  ],
  "canceled": false
}

Custom Answer result:

{
  "answers": [
    {
      "id": "direction",
      "value": "Use the smallest useful slice, but keep tests readable.",
      "label": "Use the smallest useful slice, but keep tests readable.",
      "wasCustom": true
    }
  ],
  "canceled": false
}

Canceled result:

{
  "answers": [],
  "canceled": true,
  "reason": "user_canceled"
}

When no interactive UI is available, reason is ui_unavailable. Agents should not assume an answer from any canceled result.

Keyboard controls

• Up/Down move through answer rows and clamp at the first and last row.
• Number keys pick visible rows, including Something else….
• Enter selects a predefined Choice or submits non-empty Custom Answer text.
• Shift+Enter inserts a newline in Custom Answer input.
• Escape cancels at the top level; inside Custom Answer input it returns to the Choice list.