@mrclrchtr/supi-ask-user 1.3.1 → 1.4.0

package/README.md

@@ -1,6 +1,7 @@
 # @mrclrchtr/supi-ask-user
 
-Structured `ask_user` tool and rich questionnaire overlay for the [pi coding agent](https://github.com/earendil-works/pi). Lets the agent pause and ask you focused, typed decisions — picking from lists, multi-selecting, or entering freeform text.
+Adds a redesigned `ask_user` tool to the [pi coding agent](https://github.com/earendil-works/pi).
+It lets the model pause and request a small decision form when explicit human input is required.
 
 ## Install
 
@@ -14,34 +15,121 @@ For local development:
 pi install ./packages/supi-ask-user
 ```
 
-After editing the source, run `/reload` to pick up changes.
+After editing the source, run `/reload`.
 
-## What it adds
+## What you get
 
-Registers the `ask_user` tool — callable by the model during an agent run. When the agent needs explicit user input to proceed, it invokes `ask_user` with a questionnaire, and the extension opens an interactive overlay.
+After install, pi gets one new tool:
 
-**Question types:**
+- `ask_user` — open a blocking decision form during a run
 
-| Type | Use |
-|------|-----|
-| `choice` | Pick one option (default) or multiple options (`multi: true`) from a list |
-| `text` | Freeform text input |
+Use cases:
 
-For yes/no questions, use `choice` with options `{value: "yes", label: "Yes"}` and `{value: "no", label: "No"}` — there is no separate `yesno` type.
+- clarify a narrow implementation choice
+- confirm a risky or destructive action
+- ask for a preference the repo cannot answer
+- gather one short cluster of related decisions before proceeding
 
-**Key behaviors:**
+It is **not** meant for long surveys or open-ended discovery.
 
-- Returns an error in non-interactive or print-mode sessions (no fallback dialog).
-- Only one questionnaire runs at a time — concurrent `ask_user` calls return an error.
-- Cancelling or closing the overlay aborts the current agent turn.
-- Completed answers appear as a readable summary entry in the `/tree` view.
+## Request shape
 
-## Usage
+`ask_user` accepts a small form with optional framing text:
 
-The agent decides when to call `ask_user`. You control how it's used through the system prompt guidelines the extension injects. A minimal example the agent might construct:
+- `title` — short overall title
+- `intro` — why the agent is asking
+- `questions` — 1-4 related questions
+- `allowPartialSubmit` — let the user submit partial progress
+- `allowDiscuss` — let the user switch back into discussion instead of giving a final decision
+
+## Question types
+
+### `choice`
+
+Use for fixed options.
+
+Supported fields:
+
+- `options`
+- `required`
+- `multi`
+- `allowOther` — single-select only
+- `recommendation`
+- `initial`
+- option `description`
+- option `preview`
+
+### `text`
+
+Use for freeform input.
+
+Supported fields:
+
+- `required`
+- `initial`
+- `placeholder`
+
+## Result statuses
+
+A completed form returns one of these statuses in `details.status`:
+
+- `submitted` — full submit
+- `partial` — partial submit with missing required answers
+- `discuss` — user wants to continue the conversation instead of deciding
+- `cancelled` — user explicitly cancelled
+- `aborted` — the interaction was aborted externally
+
+`details.answersById` contains structured answers keyed by question id.
+
+## Behavior
+
+- interactive UI with custom overlay support required
+- `ask_user` does not provide a degraded dialog fallback
+- only one `ask_user` interaction may be active at a time
+- cancellation or abort stops the current agent turn
+- completed forms are summarized in the session tree
+
+## Rich overlay controls
+
+`ask_user` requires the rich overlay renderer. The current interaction model is:
+
+### Choice questions
+
+- `↑↓` move between rows
+- `Space` selects the focused option in single-select mode
+- `Space` toggles the focused option in multi-select mode
+- `Enter` submits the current choice answer
+- `←` goes back to the previous question
+- `Esc` cancels the whole form
+
+On wide terminals, choice previews render side-by-side with the option list. On narrow terminals, previews stack below.
+
+Visible rows are kept for exceptional paths only:
+
+- `Other…`
+- `Discuss instead…`
+- `Submit partial answers`
+- `Skip question` for optional questions
+
+There is no visible Back row or Cancel row in the overlay.
+
+### Text questions
+
+- the text editor is visible immediately
+- there is no separate `Enter response…` row
+- `Enter` submits the current text answer
+- `↓` moves from the editor into any visible exceptional action rows
+- `↑` from the first action row returns focus to the editor
+- `Esc` cancels the whole form
+
+Text questions may still show exceptional action rows such as `Discuss instead…` or `Submit partial answers` below the editor when those paths are enabled.
+
+## Example
 
 ```json
 {
+  "title": "Formatter decision",
+  "intro": "I need one explicit choice before I update the repo config.",
   "questions": [
     {
       "type": "choice",
@@ -53,63 +141,33 @@ The agent decides when to call `ask_user`. You control how it's used through the
         { "value": "prettier", "label": "Prettier" }
       ],
       "recommendation": "biome",
-      "default": "biome"
+      "initial": "biome"
     },
     {
       "type": "text",
       "id": "reason",
       "header": "Reason",
-      "prompt": "Why this formatter?",
-      "default": "Faster linting"
+      "prompt": "Anything I should optimize for?",
+      "required": false,
+      "placeholder": "optional"
     }
-  ]
-}
-```
-
-**Multi-select example:**
-
-```json
-{
-  "type": "choice",
-  "multi": true,
-  "id": "features",
-  "header": "Features",
-  "prompt": "Which features to include?",
-  "options": [
-    { "value": "auth", "label": "Authentication" },
-    { "value": "caching", "label": "Caching" },
-    { "value": "logging", "label": "Logging" }
   ],
-  "recommendation": ["auth", "caching"]
+  "allowDiscuss": true
 }
 ```
 
-**Per-question features:**
-
-- `multi` — set to `true` to enable multi-select (replaces the former `multichoice` type). Default `false`.
-- `recommendation` — highlights the preferred option with a visual badge. String for single-select, array for multi-select.
-- `default` — pre-selects a starting value the user can accept with a single keystroke. String for single-select, array for multi-select.
-- `allowOther` — lets the user type a custom answer instead of picking from options.
-- `allowDiscuss` — lets the user opt into a discussion instead of deciding immediately.
-- `preview` — rich content (markdown, code, or ASCII mockups) shown alongside the option.
-
-**Questionnaire-level controls:**
-
-- `allowSkip` — exposes a Skip action so the user can submit partial results without answering all required questions.
-
-## Limits
-
-- **1–4 questions** per questionnaire. Use one decision per call; chain multiple calls when you need more questions.
-- **2–12 options** per `choice` question (single or multi-select).
-- **60 characters** max per question header.
-- **4000 characters** max per question prompt.
-
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `typebox`
-
-## Source
-
-Entrypoint: `src/ask-user.ts` — registers the `ask_user` tool, drives the questionnaire overlay, and manages the concurrency lock.
+## Source layout
+
+- `src/ask-user.ts` — tool registration and execution boundary
+- `src/schema.ts` — tool-call schema
+- `src/normalize.ts` — validation and lowering into internal types
+- `src/session/controller.ts` — headless decision-form state
+- `src/ui/choose-renderer.ts` — custom-overlay capability gate
+- `src/ui/overlay.ts` — rich custom interaction orchestration
+- `src/ui/overlay-view.ts` — choice/action row modeling and split-layout helpers
+- `src/ui/overlay-render.ts` — rich overlay rendering built on `Markdown`, `Editor`, and `SelectList`
+- `src/ui/overlay-actions.ts` — exceptional-action list wiring for text questions
+- `src/ui/types.ts` — shared UI runner types
+- `src/render/result.ts` — tool result shaping
+- `src/render/transcript.ts` — transcript rendering
+- `src/render/tree-summary.ts` — session-tree summary labels

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- shared config loading, scoped reads, writes, and key removal
-- config-backed settings registration helpers for `/supi-settings`
-- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
-- XML `<extension-context>` wrapping plus context-message utilities
-- context-provider and debug-event registries reused across SuPi packages
-- project root and path helpers reused by packages such as `supi-lsp`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
 
 - global: `~/.pi/agent/supi/config.json`
 - project: `.pi/supi/config.json`
 
-Main helpers:
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
 ## Example
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{config-settings.ts → config/config-settings.ts}

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-import type { SettingsScope } from "./settings-registry.ts";
-import { registerSettings } from "./settings-registry.ts";
 
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */

package/node_modules/@mrclrchtr/supi-core/src/{context-provider-registry.ts → context/context-provider-registry.ts}

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

package/node_modules/@mrclrchtr/supi-core/src/extension.ts

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{settings-registry.ts → settings/settings-registry.ts}

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-ask-user",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "SuPi ask-user extension — rich questionnaire UI for structured agent-user decisions",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
   ],
   "main": "src/api.ts",
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.3.1"
+    "@mrclrchtr/supi-core": "1.4.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/api.ts

@@ -1 +1,20 @@
 export { default } from "./ask-user.ts";
+export { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
+export { AskUserParamsSchema } from "./schema.ts";
+export { AskUserController } from "./session/controller.ts";
+export { ActiveQuestionnaireLock } from "./session/lock.ts";
+export type {
+  Answer,
+  AskUserDetails,
+  AskUserErrorDetails,
+  AskUserOutcome,
+  AskUserStatus,
+  AskUserToolDetails,
+  ChoiceAnswer,
+  CustomAnswer,
+  NormalizedChoiceQuestion,
+  NormalizedQuestion,
+  NormalizedQuestionnaire,
+  NormalizedTextQuestion,
+  TextAnswer,
+} from "./types.ts";