@mrclrchtr/supi-ask-user 1.4.0 → 1.5.0

package/README.md

@@ -1,7 +1,6 @@
 # @mrclrchtr/supi-ask-user
 
-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.
+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
 
@@ -21,108 +20,140 @@ After editing the source, run `/reload`.
 
 After install, pi gets one new tool:
 
-- `ask_user` — open a blocking decision form during a run
+- **`ask_user`** — open a blocking decision form during a run
 
-Use cases:
+The tool presents a structured questionnaire in the TUI overlay and blocks the agent turn until the user responds. It is designed for focused decisions, **not** long surveys or open-ended discovery.
 
-- 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
+Typical use cases:
 
-It is **not** meant for long surveys or open-ended discovery.
+- 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
+
+## Package surfaces
+
+- `@mrclrchtr/supi-ask-user/extension` — pi extension entrypoint, registers the `ask_user` tool
+- `@mrclrchtr/supi-ask-user/api` — reusable types and utilities
+
+Example:
+
+```ts
+import { normalizeQuestionnaire, AskUserController } from "@mrclrchtr/supi-ask-user/api";
+
+const questionnaire = normalizeQuestionnaire(params);
+const controller = new AskUserController(questionnaire);
+```
 
 ## Request shape
 
 `ask_user` accepts a small form with optional framing text:
 
-- `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
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string (optional) | Short overall title for the form |
+| `intro` | string (optional) | Why the agent is asking |
+| `questions` | array (1–4) | Choice or text questions |
+| `allowPartialSubmit` | boolean (optional) | Let the user submit partial progress |
+| `allowDiscuss` | boolean (optional) | Let the user switch back into discussion instead of giving a final decision |
 
-## Question types
+## Questions
 
-### `choice`
+Each question has a `type`, `id`, `header`, and `prompt`. Two question types are supported:
 
-Use for fixed options.
+### `choice` — fixed options
 
-Supported fields:
+| Field | Type | Description |
+|-------|------|-------------|
+| `options` | array (2–12) | Allowed answers with `value`, `label`, and optional `description`/`preview` |
+| `required` | boolean (default: `true`) | Whether this question must be answered |
+| `multi` | boolean (default: `false`) | Allow selecting multiple options |
+| `allowOther` | boolean | Allow a freeform answer instead of listed options. Single-select only. |
+| `recommendation` | string \| string[] | Recommended option value(s) |
+| `initial` | string \| string[] | Initially selected option value(s) |
 
-- `options`
-- `required`
-- `multi`
-- `allowOther` — single-select only
-- `recommendation`
-- `initial`
-- option `description`
-- option `preview`
+Model yes/no questions as a `choice` with `{ value: "yes", label: "Yes" }` and `{ value: "no", label: "No" }`.
 
-### `text`
+### `text` — freeform input
 
-Use for freeform input.
+| Field | Type | Description |
+|-------|------|-------------|
+| `required` | boolean (default: `true`) | Whether this question must be answered |
+| `initial` | string | Initial value shown in the editor |
+| `placeholder` | string | Placeholder shown before the user types |
 
-Supported fields:
+## Result
 
-- `required`
-- `initial`
-- `placeholder`
+A completed form returns a result with `details.status` set to one of:
 
-## Result statuses
+| Status | Meaning |
+|--------|---------|
+| `submitted` | Full submit, all required questions answered |
+| `partial` | Partial submit with some required questions unanswered |
+| `discuss` | User wants to continue the conversation instead of deciding |
+| `cancelled` | User explicitly cancelled (aborts the current agent turn) |
+| `aborted` | The interaction was aborted externally (aborts the current agent turn) |
 
-A completed form returns one of these statuses in `details.status`:
+`details.answersById` maps question IDs to their answers. Each answer has a `kind` and type-specific data:
 
-- `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
+- `{ kind: "choice", selections: [{ value, label, note? }] }` — single or multi-select choice, with optional per-option user notes
+- `{ kind: "custom", value: "..." }` — freeform `allowOther` answer
+- `{ kind: "text", value: "..." }` — freeform text answer
 
-`details.answersById` contains structured answers keyed by question id.
+`details.missingQuestionIds` lists any required questions that were left unanswered on a partial submit.
 
 ## 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
+- Requires pi in interactive (TUI) mode with custom overlay support — no degraded fallback
+- Only one `ask_user` form may be active at a time; calling `ask_user` while another form is in flight returns an error
+- Cancellation or abort stops the current agent turn
+- Completed forms are summarized in the session tree
+- Do not use `ask_user` for open-ended interviews or repo facts the agent can discover on its own
+
+## Tool guidance
 
-## Rich overlay controls
+The tool registers the following prompt guidance that the model sees:
 
-`ask_user` requires the rich overlay renderer. The current interaction model is:
+- Use ask_user only when explicit user input is required to proceed safely; do not use ask_user for open-ended interviews or repo facts.
+- Use ask_user with 1-4 related questions; prefer one when possible.
+- Use ask_user `choice` for fixed options and ask_user `text` for freeform input; model yes/no as `choice` with `{ value: "yes", label: "Yes" }` and `{ value: "no", label: "No" }`.
+- Use ask_user `allowOther` only on single-select `choice` questions.
+- Use ask_user `allowDiscuss` or `allowPartialSubmit` only when that outcome is actionable.
+- Do not call ask_user while another ask_user form is already in flight.
+
+## UI controls
 
 ### 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
+- `↑↓` — move between options
+- `Space` — select the focused option (single-select) or toggle (multi-select)
+- `Enter` — submit the current answer
+- `n` — edit a note for the focused choice option
+- `←` — go back to the previous question
+- `Esc` — cancel the whole form (or close the note editor if one is open)
+
+On wide terminals, option previews render side-by-side with the option list. On narrow terminals, previews stack below.
 
-On wide terminals, choice previews render side-by-side with the option list. On narrow terminals, previews stack below.
+Notes are available only for real `choice` options. They do not apply to `text` questions, `Other…` freeform answers, or other exceptional action rows. Saving a non-empty note selects the option if needed; clearing a note leaves the current selection alone; deselecting a multi-select option removes its note with the selection.
 
-Visible rows are kept for exceptional paths only:
+Only exceptional action rows are visible:
 
-- `Other…`
-- `Discuss instead…`
-- `Submit partial answers`
-- `Skip question` for optional questions
+- `Other…` — when `allowOther` is enabled
+- `Discuss instead…` — when `allowDiscuss` is enabled
+- `Submit partial answers` — when `allowPartialSubmit` is enabled
+- `Skip question` — for optional questions
 
-There is no visible Back row or Cancel row in the overlay.
+Back and cancel are keyboard-only (`←`, `Esc`) — no visible rows.
 
 ### 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
+- The editor is visible immediately (no separate entry row)
+- `Enter` — submit the current text
+- `↓` — move from the editor into visible exceptional action rows
+- `↑` — from the first action row, return focus to the editor
+- `Esc` — cancel 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.
+Exceptional action rows (`Discuss instead…`, `Submit partial answers`) may appear below the editor when those paths are enabled.
 
 ## Example
 
@@ -158,12 +189,19 @@ Text questions may still show exceptional action rows such as `Discuss instead
 
 ## Source layout
 
+- `src/extension.ts` — pi extension entrypoint
+- `src/api.ts` — reusable public surface
+- `src/index.ts` — package barrel
 - `src/ask-user.ts` — tool registration and execution boundary
-- `src/schema.ts` — tool-call schema
+- `src/schema.ts` — tool-call parameter schema (TypeBox)
+- `src/types.ts` — internal normalized types and answer shapes
 - `src/normalize.ts` — validation and lowering into internal types
-- `src/session/controller.ts` — headless decision-form state
+- `src/tool/guidance.ts` — prompt guidance and tool description
+- `src/session/controller.ts` — headless decision-form state machine
+- `src/session/lock.ts` — session-scoped concurrency lock
 - `src/ui/choose-renderer.ts` — custom-overlay capability gate
-- `src/ui/overlay.ts` — rich custom interaction orchestration
+- `src/ui/overlay.ts` — overlay runner that creates the custom interaction session
+- `src/ui/overlay-component.ts` — rich custom interaction state and input 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

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.4.0",
+  "version": "1.5.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

@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,6 +64,7 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
 export { registerSettingsCommand } from "./settings/settings-command.ts";
 export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";

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

@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,6 +64,7 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
 export { registerSettingsCommand } from "./settings/settings-command.ts";
 export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -0,0 +1,40 @@
+import * as path from "node:path";
+
+/** Strip pi's optional leading `@` file-path prefix from a tool input. */
+export function stripToolPathPrefix(target: string): string {
+  return target.startsWith("@") ? target.slice(1) : target;
+}
+
+/**
+ * Resolve a tool-style file path from a session cwd.
+ *
+ * Built-in pi file tools accept a leading `@` prefix in path arguments, so
+ * shared SuPi path helpers normalize that prefix before resolving relative
+ * paths.
+ */
+export function resolveToolPath(cwd: string, target: string): string {
+  return path.resolve(cwd, stripToolPathPrefix(target));
+}
+
+/** Convert a file path to a file:// URI. */
+export function fileToUri(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  if (process.platform === "win32") {
+    return `file:///${resolved.replace(/\\/g, "/")}`;
+  }
+  return `file://${resolved}`;
+}
+
+/** Convert a file:// URI to a file path. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}

package/node_modules/@mrclrchtr/supi-core/src/registry-utils.ts

@@ -5,8 +5,20 @@
 // Without this, each symlink path gets its own module copy and its own Map,
 // so registrations from one instance are invisible to consumers in another.
 
+import * as path from "node:path";
+
 const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
 
+function getGlobalRegistryMap<T>(name: string): Map<string, T> {
+  const key = Symbol.for(SYMBOL_PREFIX + name);
+  let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
+  if (!map) {
+    map = new Map<string, T>();
+    (globalThis as Record<symbol, unknown>)[key] = map;
+  }
+  return map;
+}
+
 /**
  * Create a named registry backed by `globalThis` + `Symbol.for`.
  *
@@ -18,16 +30,7 @@ const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
  * @returns An object with `register`, `getAll`, and `clear` functions.
  */
 export function createRegistry<T>(name: string) {
-  const key = Symbol.for(SYMBOL_PREFIX + name);
-
-  const getMap = (): Map<string, T> => {
-    let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
-    if (!map) {
-      map = new Map<string, T>();
-      (globalThis as Record<symbol, unknown>)[key] = map;
-    }
-    return map;
-  };
+  const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
 
   return {
     /**
@@ -52,3 +55,32 @@ export function createRegistry<T>(name: string) {
     },
   };
 }
+
+/**
+ * Create a named session-state registry keyed by normalized cwd.
+ *
+ * This helper is intended for session-scoped runtime services that should be
+ * shared across duplicate jiti module instances while keeping package-specific
+ * state unions and convenience wrappers local to the calling package.
+ */
+export function createSessionStateRegistry<TState>(name: string) {
+  const getMap = (): Map<string, TState> => getGlobalRegistryMap<TState>(name);
+  const normalizeCwd = (cwd: string): string => path.resolve(cwd);
+
+  return {
+    /** Get the current state for one session cwd. */
+    get: (cwd: string): TState | undefined => {
+      return getMap().get(normalizeCwd(cwd));
+    },
+
+    /** Store the current state for one session cwd. */
+    set: (cwd: string, state: TState): void => {
+      getMap().set(normalizeCwd(cwd), state);
+    },
+
+    /** Clear the current state for one session cwd. */
+    clear: (cwd: string): void => {
+      getMap().delete(normalizeCwd(cwd));
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-ask-user",
-  "version": "1.4.0",
+  "version": "1.5.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.4.0"
+    "@mrclrchtr/supi-core": "1.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/ask-user.ts

@@ -19,6 +19,8 @@ export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "
     notify?(message: string, type?: "info" | "warning" | "error"): void;
     setWorkingVisible?(visible: boolean): void;
     setTitle?(title: string): void;
+    getToolsExpanded?(): boolean;
+    setToolsExpanded?(expanded: boolean): void;
   };
 };
 
@@ -81,6 +83,10 @@ export async function executeAskUser(
         notify: ctx.ui.notify,
       },
       signal,
+      onToggleToolsExpanded:
+        ctx.ui.getToolsExpanded && ctx.ui.setToolsExpanded
+          ? () => ctx.ui.setToolsExpanded?.(!ctx.ui.getToolsExpanded?.())
+          : undefined,
     });
 
     if (outcome === "unsupported") {

package/src/render/result.ts

@@ -42,7 +42,7 @@ export function buildErrorResult(message: string): AskUserToolResult {
 export function formatAnswerSummary(_question: NormalizedQuestion, answer: Answer): string {
   switch (answer.kind) {
     case "choice":
-      return answer.selections.map((selection) => selection.label).join("; ");
+      return answer.selections.map(formatChoiceSelectionSummary).join("; ");
     case "custom":
       return `Other — ${answer.value}`;
     case "text":
@@ -50,6 +50,10 @@ export function formatAnswerSummary(_question: NormalizedQuestion, answer: Answe
   }
 }
 
+function formatChoiceSelectionSummary(selection: { label: string; note?: string }): string {
+  return selection.note ? `${selection.label} (note: ${selection.note})` : selection.label;
+}
+
 function summarizeOutcome(questions: NormalizedQuestion[], outcome: AskUserOutcome): string {
   if (outcome.status === "cancelled") return "User cancelled the form.";
   if (outcome.status === "aborted") return "The form was aborted before completion.";

package/src/session/controller.ts

@@ -1,5 +1,6 @@
 import type {
   Answer,
+  AnswerSelection,
   AskUserOutcome,
   AskUserStatus,
   NormalizedChoiceQuestion,
@@ -59,6 +60,77 @@ export class AskUserController {
       .filter((index) => index >= 0);
   }
 
+  getChoiceOptionNote(questionId: string, optionValue: string): string | undefined {
+    const answer = this.answers.get(questionId);
+    if (answer?.kind !== "choice") return undefined;
+    return answer.selections.find((selection) => selection.value === optionValue)?.note;
+  }
+
+  selectChoiceOption(question: NormalizedChoiceQuestion, optionIndex: number): void {
+    if (this.isTerminal) return;
+    const option = question.options[optionIndex];
+    if (!option) return;
+    const existingNote = this.getChoiceOptionNote(question.id, option.value);
+    this.commitChoiceSelections(question, [
+      buildSelection(option.value, option.label, existingNote),
+    ]);
+  }
+
+  toggleChoiceOption(question: NormalizedChoiceQuestion, optionIndex: number): void {
+    if (this.isTerminal) return;
+    const option = question.options[optionIndex];
+    if (!option) return;
+    if (!question.multi) {
+      this.selectChoiceOption(question, optionIndex);
+      return;
+    }
+
+    const selections = this.getStoredChoiceSelections(question.id);
+    const filtered = selections.filter((selection) => selection.value !== option.value);
+    if (filtered.length !== selections.length) {
+      this.commitChoiceSelections(question, filtered);
+      return;
+    }
+
+    this.commitChoiceSelections(question, [
+      ...selections,
+      buildSelection(option.value, option.label),
+    ]);
+  }
+
+  setChoiceOptionNote(
+    question: NormalizedChoiceQuestion,
+    optionIndex: number,
+    note: string | undefined,
+  ): void {
+    if (this.isTerminal) return;
+    const option = question.options[optionIndex];
+    if (!option) return;
+
+    const trimmedNote = trimOptional(note);
+    const selections = this.getStoredChoiceSelections(question.id);
+    const existing = selections.find((selection) => selection.value === option.value);
+
+    if (existing) {
+      this.commitChoiceSelections(
+        question,
+        selections.map((selection) => {
+          if (selection.value !== option.value) return selection;
+          return buildSelection(selection.value, selection.label, trimmedNote);
+        }),
+      );
+      return;
+    }
+
+    if (!trimmedNote) return;
+
+    const nextSelection = buildSelection(option.value, option.label, trimmedNote);
+    this.commitChoiceSelections(
+      question,
+      question.multi ? [...selections, nextSelection] : [nextSelection],
+    );
+  }
+
   setAnswer(questionId: string, answer: Answer): void {
     if (this.isTerminal) return;
     this.answers.set(questionId, normalizeAnswer(answer));
@@ -138,6 +210,29 @@ export class AskUserController {
       .filter((question) => question.required && !this.answers.has(question.id))
       .map((question) => question.id);
   }
+
+  private getStoredChoiceSelections(questionId: string): AnswerSelection[] {
+    const answer = this.answers.get(questionId);
+    if (answer?.kind !== "choice") return [];
+    return answer.selections.map((selection) => ({ ...selection }));
+  }
+
+  private commitChoiceSelections(
+    question: NormalizedChoiceQuestion,
+    selections: AnswerSelection[],
+  ): void {
+    const ordered = orderSelections(question, normalizeChoiceSelections(selections));
+    const nextSelections = question.multi ? ordered : ordered.slice(0, 1);
+    if (nextSelections.length === 0) {
+      this.answers.delete(question.id);
+      return;
+    }
+
+    this.answers.set(question.id, {
+      kind: "choice",
+      selections: nextSelections,
+    });
+  }
 }
 
 function normalizeAnswer(answer: Answer): Answer {
@@ -145,10 +240,7 @@ function normalizeAnswer(answer: Answer): Answer {
     case "choice":
       return {
         kind: "choice",
-        selections: answer.selections.map((selection) => ({
-          value: selection.value.trim(),
-          label: selection.label.trim(),
-        })),
+        selections: normalizeChoiceSelections(answer.selections),
       };
     case "custom":
       return { kind: "custom", value: answer.value.trim() };
@@ -157,6 +249,32 @@ function normalizeAnswer(answer: Answer): Answer {
   }
 }
 
+function normalizeChoiceSelections(selections: AnswerSelection[]): AnswerSelection[] {
+  return selections.map((selection) =>
+    buildSelection(selection.value, selection.label, selection.note),
+  );
+}
+
+function orderSelections(
+  question: NormalizedChoiceQuestion,
+  selections: AnswerSelection[],
+): AnswerSelection[] {
+  const byValue = new Map(selections.map((selection) => [selection.value, selection]));
+  return question.options.flatMap((option) => {
+    const selection = byValue.get(option.value);
+    return selection ? [selection] : [];
+  });
+}
+
+function buildSelection(value: string, label: string, note?: string): AnswerSelection {
+  const trimmedNote = trimOptional(note);
+  return {
+    value: value.trim(),
+    label: label.trim(),
+    ...(trimmedNote ? { note: trimmedNote } : {}),
+  };
+}
+
 function trimOptional(value: string | undefined): string | undefined {
   const trimmed = value?.trim();
   return trimmed ? trimmed : undefined;

package/src/types.ts

@@ -43,9 +43,16 @@ export interface NormalizedQuestionnaire {
   allowDiscuss: boolean;
 }
 
+/**
+ * One selected choice option returned from `ask_user`.
+ *
+ * `note` is optional user-entered context attached to this specific option.
+ * It is only used on `choice` answers and is absent for `text` / `custom` answers.
+ */
 export interface AnswerSelection {
   value: string;
   label: string;
+  note?: string;
 }
 
 export interface ChoiceAnswer {