@mrclrchtr/supi-ask-user 0.1.0

package/ask-user.ts

@@ -0,0 +1,131 @@
+// `ask_user` extension entry point. Registers a single model-callable tool
+// for focused interactive decisions during an agent run. Holds the per-session
+// single-active-questionnaire lock and chooses between the rich overlay and
+// the dialog fallback at execute time.
+//
+// Implementation modules:
+//   schema.ts           — external (LLM-facing) parameter schema
+//   normalize.ts        — validation + normalization into the shared internal model
+//   flow.ts             — shared questionnaire flow + concurrency lock
+//   ui-rich.ts          — overlay UI via ctx.ui.custom()
+//   ui-rich-render.ts   — overlay rendering helpers
+//   ui-fallback.ts      — dialog/input fallback adapter
+//   result.ts           — hybrid (content + details) result formatting
+//   render.ts           — custom renderCall / renderResult for the transcript
+
+import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import { ActiveQuestionnaireLock } from "./flow.ts";
+import { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
+import { renderAskUserCall, renderAskUserResult } from "./render.ts";
+import { buildErrorResult, buildResult, type HybridResult } from "./result.ts";
+import { type AskUserParams, AskUserParamsSchema } from "./schema.ts";
+import type { NormalizedQuestion } from "./types.ts";
+import { type FallbackUi, runFallbackQuestionnaire } from "./ui-fallback.ts";
+import { type RichUiHost, runRichQuestionnaire } from "./ui-rich.ts";
+
+const TOOL_NAME = "ask_user";
+const TOOL_LABEL = "Ask User";
+
+const TOOL_DESCRIPTION =
+  "Ask the user a focused decision question (or up to 4 grouped questions) when explicit user input is required to proceed safely. Use for clarifying intent, picking between options, prioritizing a short set of features, or confirming a destructive action — not for surveys or open-ended discovery. Each question is `choice`, `multichoice`, `text`, or `yesno`; structured questions can add `recommendation`, `allowOther`, `allowDiscuss`, and option `preview` content.";
+
+const PROMPT_SNIPPET =
+  "ask_user — pause and request a focused decision (1-4 typed questions) when explicit user input is required to proceed, including rich choice, multichoice, and discuss flows";
+
+const PROMPT_GUIDELINES = [
+  "Use ask_user only for decisions that require explicit user input — never as a substitute for reading code or thinking through a problem.",
+  "Keep questionnaires bounded: 1-4 focused questions with short headers; prefer one decision per call when possible.",
+  "Choose the narrowest type that fits: yesno for binary decisions, choice for one known option, multichoice for short pick-many lists, and text only when freeform input is genuinely needed.",
+  "Set `recommendation` when one option or a small set of options is clearly preferable, so the UI can surface that guidance.",
+  "Enable `allowOther` only when a custom answer is genuinely useful, and `allowDiscuss` only when the user may need to talk through the choice instead of deciding immediately.",
+  "Use option `preview` content when the user would understand choices better from code, config, markdown, or ASCII mockups than from one-line descriptions alone.",
+  "Do not call ask_user while another ask_user interaction is in flight — wait for the previous result before issuing another.",
+];
+
+interface ExtensionUi {
+  ui: {
+    select: FallbackUi["select"];
+    input: FallbackUi["input"];
+    custom?: RichUiHost["custom"];
+  };
+  hasUI: boolean;
+}
+
+export default function askUserExtension(pi: ExtensionAPI): void {
+  const lock = new ActiveQuestionnaireLock();
+
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: TOOL_LABEL,
+    description: TOOL_DESCRIPTION,
+    promptSnippet: PROMPT_SNIPPET,
+    promptGuidelines: PROMPT_GUIDELINES,
+    parameters: AskUserParamsSchema,
+    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return executeAskUser(params as AskUserParams, signal, ctx as ExtensionUi, lock);
+    },
+    renderCall: (args, theme) => renderAskUserCall(args, theme as Theme),
+    renderResult: (result, _options, theme) =>
+      renderAskUserResult(
+        result as { details?: unknown; content: { type: string; text?: string }[] },
+        theme as Theme,
+      ) as unknown as Component,
+  });
+}
+
+async function executeAskUser(
+  params: AskUserParams,
+  signal: AbortSignal | undefined,
+  ctx: ExtensionUi,
+  lock: ActiveQuestionnaireLock,
+): Promise<HybridResult> {
+  let normalized: NormalizedQuestion[];
+  try {
+    normalized = normalizeQuestionnaire(params).questions;
+  } catch (err) {
+    if (err instanceof AskUserValidationError) return buildErrorResult(`Error: ${err.message}`);
+    throw err;
+  }
+  if (!ctx.hasUI) {
+    return buildErrorResult(
+      "Error: ask_user requires interactive UI but the current session has none.",
+    );
+  }
+  if (!lock.acquire()) {
+    return buildErrorResult(
+      "Error: another ask_user interaction is already in flight. Wait for it to complete before calling ask_user again.",
+    );
+  }
+  try {
+    return await driveQuestionnaire(normalized, signal, ctx);
+  } finally {
+    lock.release();
+  }
+}
+
+async function driveQuestionnaire(
+  questions: NormalizedQuestion[],
+  signal: AbortSignal | undefined,
+  ctx: ExtensionUi,
+): Promise<HybridResult> {
+  if (typeof ctx.ui.custom === "function") {
+    const richHost: RichUiHost = { custom: ctx.ui.custom.bind(ctx.ui) };
+    const outcome = await runRichQuestionnaire(questions, { ui: richHost, signal });
+    if (outcome !== "unsupported") return buildResult(questions, outcome);
+  }
+  const fallbackUi: FallbackUi = {
+    select: ctx.ui.select.bind(ctx.ui),
+    input: ctx.ui.input.bind(ctx.ui),
+  };
+  const outcome = await runFallbackQuestionnaire(questions, { ui: fallbackUi, signal });
+  return buildResult(questions, outcome);
+}
+
+export { ActiveQuestionnaireLock, QuestionnaireFlow } from "./flow.ts";
+// Re-exports used by tests.
+export { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
+export { buildResult } from "./result.ts";
+export { runFallbackQuestionnaire } from "./ui-fallback.ts";
+export { PROMPT_GUIDELINES as askUserPromptGuidelines, PROMPT_SNIPPET as askUserPromptSnippet };

package/flow.ts

@@ -0,0 +1,212 @@
+// Shared questionnaire flow state used by both UI paths and the
+// single-active-questionnaire concurrency guard. The flow owns terminal-state
+// transitions (`submitted`, `cancelled`, `aborted`) so overlay and fallback
+// cannot drift apart on cancellation/abort semantics.
+
+import type { Answer, NormalizedQuestion, QuestionnaireOutcome, TerminalState } from "./types.ts";
+import { needsReview } from "./types.ts";
+
+export type FlowMode = "answering" | "reviewing" | "terminal";
+
+export class QuestionnaireFlow {
+  private readonly answers = new Map<string, Answer>();
+  private index = 0;
+  private mode: FlowMode = "answering";
+  private terminalState: TerminalState | null = null;
+
+  constructor(public readonly questions: NormalizedQuestion[]) {
+    if (questions.length === 0) {
+      throw new Error("QuestionnaireFlow requires at least one question.");
+    }
+  }
+
+  get currentIndex(): number {
+    return this.index;
+  }
+
+  get currentMode(): FlowMode {
+    return this.mode;
+  }
+
+  get isMultiQuestion(): boolean {
+    return this.questions.length > 1;
+  }
+
+  get currentQuestion(): NormalizedQuestion | undefined {
+    return this.questions[this.index];
+  }
+
+  hasAnswer(questionId: string): boolean {
+    return this.answers.has(questionId);
+  }
+
+  getAnswer(questionId: string): Answer | undefined {
+    return this.answers.get(questionId);
+  }
+
+  allAnswered(): boolean {
+    return this.questions.every((q) => this.answers.has(q.id));
+  }
+
+  setAnswer(answer: Answer): void {
+    this.answers.set(answer.questionId, normalizeAnswer(answer));
+  }
+
+  advance(): boolean {
+    if (this.mode !== "answering") return false;
+    const current = this.currentQuestion;
+    if (current && !this.answers.has(current.id)) return false;
+    if (this.index < this.questions.length - 1) {
+      this.index += 1;
+      return true;
+    }
+    if (needsReview(this.questions)) {
+      this.mode = "reviewing";
+      return true;
+    }
+    this.markSubmitted();
+    return true;
+  }
+
+  goBack(): boolean {
+    if (this.mode === "terminal") return false;
+    if (this.mode === "reviewing") {
+      this.mode = "answering";
+      this.index = this.questions.length - 1;
+      return true;
+    }
+    if (this.index > 0) {
+      this.index -= 1;
+      return true;
+    }
+    return false;
+  }
+
+  enterReview(): boolean {
+    if (this.mode === "terminal") return false;
+    if (!needsReview(this.questions)) return false;
+    if (!this.allAnswered()) return false;
+    this.mode = "reviewing";
+    return true;
+  }
+
+  submit(): boolean {
+    if (this.mode === "terminal") return false;
+    if (!this.allAnswered()) return false;
+    this.markSubmitted();
+    return true;
+  }
+
+  cancel(): void {
+    if (this.mode === "terminal") return;
+    this.mode = "terminal";
+    this.terminalState = "cancelled";
+  }
+
+  abort(): void {
+    if (this.mode === "terminal") return;
+    this.mode = "terminal";
+    this.terminalState = "aborted";
+  }
+
+  isTerminal(): boolean {
+    return this.mode === "terminal";
+  }
+
+  outcome(): QuestionnaireOutcome {
+    const state = this.terminalState ?? "cancelled";
+    return {
+      terminalState: state,
+      answers: state === "submitted" ? this.collectAnswers() : [...this.answers.values()],
+    };
+  }
+
+  private markSubmitted(): void {
+    this.mode = "terminal";
+    this.terminalState = "submitted";
+  }
+
+  private collectAnswers(): Answer[] {
+    return this.questions.flatMap((q) => {
+      const answer = this.answers.get(q.id);
+      return answer ? [answer] : [];
+    });
+  }
+}
+
+function normalizeAnswer(answer: Answer): Answer {
+  switch (answer.source) {
+    case "option":
+      return {
+        questionId: answer.questionId,
+        source: "option",
+        value: answer.value.trim(),
+        optionIndex: answer.optionIndex,
+        note: trimOptional(answer.note),
+      };
+    case "options":
+      return {
+        questionId: answer.questionId,
+        source: "options",
+        values: answer.values.map((value) => value.trim()),
+        optionIndexes: [...answer.optionIndexes],
+        selections: answer.selections.map((selection) => ({
+          value: selection.value.trim(),
+          optionIndex: selection.optionIndex,
+          note: trimOptional(selection.note),
+        })),
+      };
+    case "other":
+      return {
+        questionId: answer.questionId,
+        source: "other",
+        value: answer.value.trim(),
+      };
+    case "discuss": {
+      const value = trimOptional(answer.value);
+      return value
+        ? { questionId: answer.questionId, source: "discuss", value }
+        : { questionId: answer.questionId, source: "discuss" };
+    }
+    case "text":
+      return {
+        questionId: answer.questionId,
+        source: "text",
+        value: answer.value.trim(),
+      };
+    case "yesno":
+      return {
+        questionId: answer.questionId,
+        source: "yesno",
+        value: answer.value,
+        optionIndex: answer.optionIndex,
+        note: trimOptional(answer.note),
+      };
+  }
+}
+
+function trimOptional(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+
+// Session-scoped lock: only one in-flight `ask_user` interaction at a time.
+// Stored at module scope per extension instance (the extension factory runs
+// once per session in pi).
+export class ActiveQuestionnaireLock {
+  private active = false;
+
+  acquire(): boolean {
+    if (this.active) return false;
+    this.active = true;
+    return true;
+  }
+
+  release(): void {
+    this.active = false;
+  }
+
+  isActive(): boolean {
+    return this.active;
+  }
+}

package/format.ts

@@ -0,0 +1,95 @@
+// Shared formatting helpers used by both UI paths and result rendering.
+// Keeps summary/review formatting in one place so the rich overlay, dialog
+// fallback, transcript renderer, and tool-content summary cannot accidentally
+// diverge.
+
+import type { Answer, MultiSelection, NormalizedQuestion } from "./types.ts";
+
+export const OTHER_LABEL = "Other answer";
+export const DISCUSS_LABEL = "Discuss instead";
+export const SUBMIT_SELECTIONS_LABEL = "Submit selections";
+export const NOTE_MARKER = "✎";
+
+export function decorateOption(label: string, recommended: boolean): string {
+  return recommended ? `${label} (recommended)` : label;
+}
+
+export function formatSummaryBody(question: NormalizedQuestion, answer: Answer): string {
+  switch (answer.source) {
+    case "option": {
+      const label = question.options[answer.optionIndex]?.label ?? answer.value;
+      return withNote(label, answer.note);
+    }
+    case "options": {
+      const selections = resolveSelections(question, answer);
+      return selections.map((selection) => withNote(selection.label, selection.note)).join("; ");
+    }
+    case "other":
+      return `Other — ${answer.value}`;
+    case "discuss":
+      return answer.value ? `Discuss — ${answer.value}` : "Discuss";
+    case "text":
+      return answer.value;
+    case "yesno":
+      return withNote(answer.value === "yes" ? "Yes" : "No", answer.note);
+  }
+}
+
+export function formatReviewBody(question: NormalizedQuestion, answer: Answer): string {
+  return formatReviewLines(question, answer).join("; ");
+}
+
+export function formatReviewLines(question: NormalizedQuestion, answer: Answer): string[] {
+  switch (answer.source) {
+    case "option": {
+      const label = question.options[answer.optionIndex]?.label ?? answer.value;
+      return [withNote(label, answer.note)];
+    }
+    case "options": {
+      const selections = resolveSelections(question, answer);
+      return selections.length > 0
+        ? selections.map((selection) => withNote(selection.label, selection.note))
+        : ["(no selections)"];
+    }
+    case "other":
+      return [`Other: ${answer.value}`];
+    case "discuss":
+      return [answer.value ? `Discuss: ${answer.value}` : "Discuss"];
+    case "text":
+      return [answer.value];
+    case "yesno":
+      return [withNote(answer.value === "yes" ? "Yes" : "No", answer.note)];
+  }
+}
+
+export function formatReviewLine(question: NormalizedQuestion, answer: Answer | undefined): string {
+  if (!answer) return "(no answer)";
+  return formatReviewBody(question, answer);
+}
+
+interface ResolvedSelection {
+  label: string;
+  note?: string;
+}
+
+function resolveSelections(
+  question: NormalizedQuestion,
+  answer: Extract<Answer, { source: "options" }>,
+): ResolvedSelection[] {
+  const selections = answer.selections.length > 0 ? answer.selections : legacySelections(answer);
+  return selections.map((selection) => ({
+    label: question.options[selection.optionIndex]?.label ?? selection.value,
+    note: selection.note,
+  }));
+}
+
+function legacySelections(answer: Extract<Answer, { source: "options" }>): MultiSelection[] {
+  return answer.optionIndexes.map((optionIndex, index) => ({
+    value: answer.values[index] ?? "",
+    optionIndex,
+  }));
+}
+
+function withNote(body: string, note: string | undefined): string {
+  return note ? `${body} — ${note}` : body;
+}

package/normalize.ts

@@ -0,0 +1,218 @@
+// Validates raw `ask_user` parameters and lowers them into the shared internal
+// questionnaire model. Both UI paths and result formatting consume only this
+// normalized model, so the overlay and dialog flows cannot drift apart.
+
+import type {
+  AskUserParams,
+  ExternalChoiceQuestion,
+  ExternalMultiChoiceQuestion,
+  ExternalQuestion,
+  ExternalYesNoQuestion,
+} from "./schema.ts";
+import {
+  type NormalizedOption,
+  type NormalizedQuestion,
+  type NormalizedQuestionnaire,
+  QUESTION_LIMITS,
+} from "./types.ts";
+
+const YES_NO_OPTIONS: readonly NormalizedOption[] = [
+  { value: "yes", label: "Yes" },
+  { value: "no", label: "No" },
+] as const;
+
+export class AskUserValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AskUserValidationError";
+  }
+}
+
+export function normalizeQuestionnaire(params: AskUserParams): NormalizedQuestionnaire {
+  validateQuestionnaireShape(params);
+  return { questions: params.questions.map((q) => normalizeQuestion(q)) };
+}
+
+function validateQuestionnaireShape(params: AskUserParams): void {
+  const count = params.questions.length;
+  if (count < QUESTION_LIMITS.minQuestions || count > QUESTION_LIMITS.maxQuestions) {
+    throw new AskUserValidationError(
+      `ask_user supports ${QUESTION_LIMITS.minQuestions}-${QUESTION_LIMITS.maxQuestions} questions only (got ${count}).`,
+    );
+  }
+  const seen = new Set<string>();
+  for (const q of params.questions) {
+    if (seen.has(q.id)) {
+      throw new AskUserValidationError(
+        `Duplicate question id "${q.id}" — question ids must be unique within a questionnaire.`,
+      );
+    }
+    seen.add(q.id);
+  }
+}
+
+function normalizeQuestion(q: ExternalQuestion): NormalizedQuestion {
+  validateCommonFields(q);
+  switch (q.type) {
+    case "choice":
+      return normalizeChoice(q);
+    case "multichoice":
+      return normalizeMultiChoice(q);
+    case "yesno":
+      return normalizeYesNo(q);
+    case "text":
+      return normalizeText(q);
+  }
+}
+
+function validateCommonFields(q: ExternalQuestion): void {
+  if (q.id.trim().length === 0) {
+    throw new AskUserValidationError("Question id must be a non-empty string.");
+  }
+  if (q.header.trim().length === 0) {
+    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty header.`);
+  }
+  if (q.header.length > QUESTION_LIMITS.maxHeaderLength) {
+    throw new AskUserValidationError(
+      `Question "${q.id}" header exceeds ${QUESTION_LIMITS.maxHeaderLength} characters.`,
+    );
+  }
+  if (q.prompt.trim().length === 0) {
+    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty prompt.`);
+  }
+  if (q.prompt.length > QUESTION_LIMITS.maxPromptLength) {
+    throw new AskUserValidationError(
+      `Question "${q.id}" prompt exceeds ${QUESTION_LIMITS.maxPromptLength} characters.`,
+    );
+  }
+}
+
+function normalizeChoice(q: ExternalChoiceQuestion): NormalizedQuestion {
+  const options = normalizeStructuredOptions(q.id, q.options);
+  return {
+    id: q.id,
+    header: q.header,
+    type: "choice",
+    prompt: q.prompt,
+    options,
+    allowOther: q.allowOther ?? false,
+    allowDiscuss: q.allowDiscuss ?? false,
+    recommendedIndexes: resolveSingleRecommendation(q.id, options, q.recommendation),
+  };
+}
+
+function normalizeMultiChoice(q: ExternalMultiChoiceQuestion): NormalizedQuestion {
+  if (q.allowOther) {
+    throw new AskUserValidationError(
+      `multichoice question "${q.id}" does not support allowOther in this version.`,
+    );
+  }
+  const options = normalizeStructuredOptions(q.id, q.options);
+  return {
+    id: q.id,
+    header: q.header,
+    type: "multichoice",
+    prompt: q.prompt,
+    options,
+    allowOther: false,
+    allowDiscuss: q.allowDiscuss ?? false,
+    recommendedIndexes: resolveMultiRecommendation(q.id, options, q.recommendation),
+  };
+}
+
+function normalizeYesNo(q: ExternalYesNoQuestion): NormalizedQuestion {
+  return {
+    id: q.id,
+    header: q.header,
+    type: "yesno",
+    prompt: q.prompt,
+    options: YES_NO_OPTIONS.map((option) => ({ ...option })),
+    allowOther: q.allowOther ?? false,
+    allowDiscuss: q.allowDiscuss ?? false,
+    recommendedIndexes: q.recommendation === undefined ? [] : [q.recommendation === "yes" ? 0 : 1],
+  };
+}
+
+function normalizeText(q: { id: string; header: string; prompt: string }): NormalizedQuestion {
+  return {
+    id: q.id,
+    header: q.header,
+    type: "text",
+    prompt: q.prompt,
+    options: [],
+  };
+}
+
+function normalizeStructuredOptions(
+  questionId: string,
+  options: ExternalChoiceQuestion["options"] | ExternalMultiChoiceQuestion["options"],
+): NormalizedOption[] {
+  const optionCount = options.length;
+  if (
+    optionCount < QUESTION_LIMITS.minChoiceOptions ||
+    optionCount > QUESTION_LIMITS.maxChoiceOptions
+  ) {
+    throw new AskUserValidationError(
+      `structured question "${questionId}" must have ${QUESTION_LIMITS.minChoiceOptions}-${QUESTION_LIMITS.maxChoiceOptions} options (got ${optionCount}).`,
+    );
+  }
+  const seenValues = new Set<string>();
+  return options.map((opt) => {
+    if (opt.value.trim().length === 0 || opt.label.trim().length === 0) {
+      throw new AskUserValidationError(
+        `structured question "${questionId}" has an option with empty value or label.`,
+      );
+    }
+    if (seenValues.has(opt.value)) {
+      throw new AskUserValidationError(
+        `structured question "${questionId}" has duplicate option value "${opt.value}".`,
+      );
+    }
+    seenValues.add(opt.value);
+    return {
+      value: opt.value,
+      label: opt.label,
+      description: opt.description,
+      preview: opt.preview,
+    };
+  });
+}
+
+function resolveSingleRecommendation(
+  questionId: string,
+  options: NormalizedOption[],
+  recommendation: string | undefined,
+): number[] {
+  if (recommendation === undefined) return [];
+  const idx = options.findIndex((opt) => opt.value === recommendation);
+  if (idx < 0) {
+    throw new AskUserValidationError(
+      `choice question "${questionId}" recommends "${recommendation}", which is not one of its option values.`,
+    );
+  }
+  return [idx];
+}
+
+function resolveMultiRecommendation(
+  questionId: string,
+  options: NormalizedOption[],
+  recommendation: string[] | undefined,
+): number[] {
+  if (!recommendation || recommendation.length === 0) return [];
+  const seen = new Set<string>();
+  return recommendation.map((value) => {
+    if (seen.has(value)) {
+      throw new AskUserValidationError(
+        `multichoice question "${questionId}" has duplicate recommended value "${value}".`,
+      );
+    }
+    seen.add(value);
+    const idx = options.findIndex((opt) => opt.value === value);
+    if (idx < 0) {
+      throw new AskUserValidationError(
+        `multichoice question "${questionId}" recommends "${value}", which is not one of its option values.`,
+      );
+    }
+    return idx;
+  });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mrclrchtr/supi-ask-user",
+  "version": "0.1.0",
+  "description": "SuPi ask-user extension — rich questionnaire UI for structured agent-user decisions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "*.ts",
+    "!__tests__"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "~0.66.0",
+    "@mariozechner/pi-tui": "~0.66.0",
+    "@sinclair/typebox": ">=0.34.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.4"
+  },
+  "pi": {
+    "extensions": [
+      "./ask-user.ts"
+    ]
+  }
+}