pi-ask-complete

Model-guided ask_user questions for the Pi coding agent.

The extension tells the model to use ask_user for decisions, preferences, confirmations, and clarifying questions instead of dumping multiple-choice prompts into chat. Answers come back as structured JSON. The transcript stays visible the whole time.

• Single-select and multi-select questions
• Free-form answers on every question (Type something.)
• Optional descriptions and side-by-side previews
• Multiple questions with tabs and a final review screen
• Required or skippable questions
• Bottom-panel UI that keeps the transcript visible
• Structured JSON answers returned to the model
• Herdr attention notification when the panel waits in a background pane
• Ovis chat cards through its existing Pi event bridge (optional setup below)

pi install npm:@itc-steve/pi-ask-complete

From a local checkout:

pi install /path/to/pi-ask-complete

Run /reload after installation.

ask_user({
  questions: [
    {
      header: "Which layout?",
      tab: "Layout",
      prompt: "Choose the default page layout.",
      options: [
        { label: "Grid", description: "Dense overview of many items." },
        { label: "List", description: "More detail for each item." }
      ],
      allowSkip: false
    }
  ]
})

Every question also includes a Type something. row. The tool returns structured JSON with the user's selections, custom answers, skipped questions, cancellation state, and optional note.

Ovis chat cards (optional)

This extension speaks Ovis's existing @eko24ive/pi-ask v1 event protocol. It does not require the @eko24ive/pi-ask package; do not enable both packages' ask_user tools in the same Pi session. Terminal questions work unchanged without Ovis. This extension adds no socket, HTTP server, settings, or global installation.

To enable cards, install this package as above, then explicitly install Ovis's separate Pi integration on each machine running Pi, as the same OS user. From an Ovis checkout containing integrations/pi-ask.ts and scripts/install-pi-integration.ts, with Bun available:

cd /path/to/ovis
bun scripts/install-pi-integration.ts

That upstream command writes ~/.pi/agent/extensions/herdr-web-ui.js, or $PI_CODING_AGENT_DIR/extensions/herdr-web-ui.js when set, and refuses to replace a file it does not own. Use the same PI_CODING_AGENT_DIR for installation and Pi. Restart existing Pi sessions after installing the bridge. This package never runs that installer for you. To remove only the Ovis bridge, run bun scripts/install-pi-integration.ts --remove from that checkout and restart Pi.

Ovis's bridge serves a user-private Unix socket at <Pi agent dir>/herdr-web-ui-ask/<pid>.sock. Cards require an interactive Pi in a Herdr pane, a readable matching session file, exactly one active form whose ask_user tool call is open on Pi's live branch, and the matching foreground Pi process. Missing/ambiguous bindings, no bridge, Windows, or an overlong Unix socket path (over 100 bytes) fall back to Terminal. Print/JSON mode is not supported; RPC does not provide this terminal panel. Existing calls are not restored as forms after restart or /reload.

Cards support single/multiple choices, custom text, and multiple question steps. Option values and question IDs are internal identifiers, not labels or tab values, so repeated labels/tabs remain separate. Answers return the same tool JSON as terminal answers. The first terminal/remote completion wins; abort, cancellation, shutdown, and component disposal close the flow. Invalid remote submissions leave it open for correction.

Required-question limitation: the inspected Ovis card implementation hardcodes optional: true and can let you skip even when allowSkip: false. This extension publishes required: true and rejects the final submission with invalid_answer if any required question is empty; it never weakens required validation. Revisit that question in the card and answer it, or use Terminal. Ovis may display the rejection as reply_failed rather than an inline required-field hint. Explicit cancellation is still allowed. The terminal-only final review/note editor is not available in cards; remote submission does not merge unsubmitted terminal drafts or notes. Ovis applies its own form/text size limits (20 questions, 50 options per question, 12,000-character text fields), so larger forms can remain terminal-only.

Compatibility reference: Ovis commit 90d421f823a7d382948871b1a2b5315451103943 (shared/pi-ask-bridge.ts, integrations/pi-ask.ts, server/pi-ask-bridge.ts). No Ovis files need changing.

Checks

Run npm test with a Node version supporting --experimental-strip-types. Protocol tests have no dependency installation requirement. The real-panel test runs when Pi's optional peer packages resolve, otherwise it reports a skip. Set OVIS_CHECKOUT=/path/to/ovis to also test the unmodified upstream Unix-socket bridge using synthetic session data; this test installs nothing.

License

MIT