@mrclrchtr/supi-ask-user 1.3.1 → 1.5.0

package/src/schema.ts

@@ -1,100 +1,103 @@
-// External (model-facing) parameter schema for the `ask_user` tool.
-// Two question types: choice (structured pick-one-or-many with options)
-// and text (freeform input). Yes/no and multichoice have been unified
-// into choice — yes/no is just choice with two options, multi-select
-// is choice with `multi: true`.
+// External, model-facing parameter schema for the redesigned ask_user tool.
 
 import { type Static, Type } from "typebox";
 
-const StructuredOptionSchema = Type.Object({
-  value: Type.String({ description: "Stable identifier returned in the answer" }),
+const OptionSchema = Type.Object({
+  value: Type.String({ description: "Stable identifier returned when this option is selected" }),
   label: Type.String({ description: "Display label shown to the user" }),
   description: Type.Optional(
     Type.String({
-      description:
-        "Optional clarification shown under the label (wraps naturally, a short paragraph is fine)",
+      description: "Optional clarification shown under the label in richer UIs",
     }),
   ),
   preview: Type.Optional(
     Type.String({
-      description:
-        "Optional rich preview content shown in the TUI (markdown, code, or ASCII mockups)",
+      description: "Optional preview content shown for the currently focused option",
     }),
   ),
 });
 
 const ChoiceQuestionSchema = Type.Object({
   type: Type.Literal("choice"),
-  id: Type.String({ description: "Unique question id within this questionnaire" }),
-  header: Type.String({ description: "Short label (chip) describing the decision" }),
+  id: Type.String({ description: "Unique question id within this form" }),
+  header: Type.String({ description: "Short label describing the decision" }),
   prompt: Type.String({ description: "Full question text shown to the user" }),
-  options: Type.Array(StructuredOptionSchema, {
-    description: "Allowed answers (2-12). Use distinct, mutually exclusive options.",
+  options: Type.Array(OptionSchema, {
+    description: "Allowed answers (2-12 distinct options)",
   }),
   required: Type.Optional(
     Type.Boolean({
       default: true,
-      description: "Whether this question must be answered before submission (default true)",
-    }),
-  ),
-  allowOther: Type.Optional(
-    Type.Boolean({
-      description: "Allow an explicit custom answer path instead of forcing one of the options",
+      description: "Whether this question must be answered for a full submit",
     }),
   ),
-  allowDiscuss: Type.Optional(
+  multi: Type.Optional(
     Type.Boolean({
-      description:
-        "Allow the user to choose discussion instead of committing to a decision right now",
+      default: false,
+      description: "Allow selecting multiple options instead of one",
     }),
   ),
-  multi: Type.Optional(
+  allowOther: Type.Optional(
     Type.Boolean({
-      default: false,
       description:
-        "Allow selecting multiple options (multi-select). Default false (single-select).",
+        "Allow a custom freeform answer instead of the listed options. Only valid for single-select choice questions.",
     }),
   ),
   recommendation: Type.Optional(
     Type.Union([Type.String(), Type.Array(Type.String())], {
       description:
-        "Recommended option value(s). String for single-select, array for multi-select. Each must match an option value.",
+        "Recommended option value or values. Use a string for single-select and an array for multi-select.",
     }),
   ),
-  default: Type.Optional(
+  initial: Type.Optional(
     Type.Union([Type.String(), Type.Array(Type.String())], {
       description:
-        "Pre-selected option value(s). String for single-select, array for multi-select. Each must match an option value.",
+        "Initial selected option value or values. Use a string for single-select and an array for multi-select.",
     }),
   ),
 });
 
 const TextQuestionSchema = Type.Object({
   type: Type.Literal("text"),
-  id: Type.String({ description: "Unique question id within this questionnaire" }),
-  header: Type.String({ description: "Short label (chip) describing the prompt" }),
+  id: Type.String({ description: "Unique question id within this form" }),
+  header: Type.String({ description: "Short label describing the prompt" }),
   prompt: Type.String({ description: "Full question text shown to the user" }),
   required: Type.Optional(
     Type.Boolean({
       default: true,
-      description: "Whether this question must be answered before submission (default true)",
+      description: "Whether this question must be answered for a full submit",
     }),
   ),
-  default: Type.Optional(
-    Type.String({ description: "Pre-filled default value shown in the text input" }),
+  initial: Type.Optional(Type.String({ description: "Initial value shown in the editor" })),
+  placeholder: Type.Optional(
+    Type.String({ description: "Placeholder shown before the user types" }),
   ),
 });
 
 const QuestionSchema = Type.Union([ChoiceQuestionSchema, TextQuestionSchema]);
 
 export const AskUserParamsSchema = Type.Object({
+  title: Type.Optional(
+    Type.String({ description: "Optional short title explaining the overall decision" }),
+  ),
+  intro: Type.Optional(
+    Type.String({
+      description: "Optional introductory context explaining why the agent is asking",
+    }),
+  ),
   questions: Type.Array(QuestionSchema, {
-    description: "Between 1 and 4 focused decision questions",
+    description: "Between 1 and 4 focused questions that belong to the same decision",
   }),
-  allowSkip: Type.Optional(
+  allowPartialSubmit: Type.Optional(
+    Type.Boolean({
+      description:
+        "Allow the user to submit a partial form when some required questions remain unanswered",
+    }),
+  ),
+  allowDiscuss: Type.Optional(
     Type.Boolean({
       description:
-        "Expose a Skip action so the user can submit a partial result without answering all questions",
+        "Allow the user to switch back into discussion instead of committing to a final answer",
     }),
   ),
 });

package/src/session/controller.ts

@@ -0,0 +1,281 @@
+import type {
+  Answer,
+  AnswerSelection,
+  AskUserOutcome,
+  AskUserStatus,
+  NormalizedChoiceQuestion,
+  NormalizedQuestion,
+  NormalizedQuestionnaire,
+} from "../types.ts";
+
+export class AskUserController {
+  private readonly answers = new Map<string, Answer>();
+  private index = 0;
+  private status: AskUserStatus | null = null;
+  private discussMessage: string | undefined;
+
+  constructor(public readonly questionnaire: NormalizedQuestionnaire) {
+    if (questionnaire.questions.length === 0) {
+      throw new Error("AskUserController requires at least one question.");
+    }
+  }
+
+  get questions(): NormalizedQuestion[] {
+    return this.questionnaire.questions;
+  }
+
+  get currentIndex(): number {
+    return this.index;
+  }
+
+  get currentQuestion(): NormalizedQuestion {
+    const question = this.questionnaire.questions[this.index];
+    if (!question) {
+      throw new Error(`No question at index ${this.index}.`);
+    }
+    return question;
+  }
+
+  get isTerminal(): boolean {
+    return this.status !== null;
+  }
+
+  get answerCount(): number {
+    return this.answers.size;
+  }
+
+  hasAnswer(questionId: string): boolean {
+    return this.answers.has(questionId);
+  }
+
+  getAnswer(questionId: string): Answer | undefined {
+    return this.answers.get(questionId);
+  }
+
+  getSelectedIndexes(question: NormalizedChoiceQuestion): number[] {
+    const answer = this.answers.get(question.id);
+    if (answer?.kind !== "choice") return [...question.initialIndexes];
+    return answer.selections
+      .map((selection) => question.options.findIndex((option) => option.value === selection.value))
+      .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));
+  }
+
+  clearAnswer(questionId: string): void {
+    if (this.isTerminal) return;
+    this.answers.delete(questionId);
+  }
+
+  goNext(): boolean {
+    if (this.isTerminal) return false;
+    if (this.index >= this.questionnaire.questions.length - 1) return false;
+    this.index += 1;
+    return true;
+  }
+
+  goBack(): boolean {
+    if (this.isTerminal) return false;
+    if (this.index === 0) return false;
+    this.index -= 1;
+    return true;
+  }
+
+  canSubmit(): boolean {
+    return this.missingQuestionIds().length === 0;
+  }
+
+  canPartialSubmit(): boolean {
+    return (
+      this.questionnaire.allowPartialSubmit &&
+      this.answerCount > 0 &&
+      this.missingQuestionIds().length > 0
+    );
+  }
+
+  finishSubmitted(): boolean {
+    if (!this.canSubmit() || this.isTerminal) return false;
+    this.status = "submitted";
+    return true;
+  }
+
+  finishPartial(): boolean {
+    if (!this.canPartialSubmit() || this.isTerminal) return false;
+    this.status = "partial";
+    return true;
+  }
+
+  finishDiscuss(message?: string): boolean {
+    if (!this.questionnaire.allowDiscuss || this.isTerminal) return false;
+    this.status = "discuss";
+    this.discussMessage = trimOptional(message);
+    return true;
+  }
+
+  cancel(): void {
+    if (this.isTerminal) return;
+    this.status = "cancelled";
+  }
+
+  abort(): void {
+    if (this.isTerminal) return;
+    this.status = "aborted";
+  }
+
+  outcome(): AskUserOutcome {
+    return {
+      status: this.status ?? "cancelled",
+      answersById: Object.fromEntries(this.answers),
+      missingQuestionIds: this.missingQuestionIds(),
+      ...(this.discussMessage ? { discussMessage: this.discussMessage } : {}),
+    };
+  }
+
+  missingQuestionIds(): string[] {
+    return this.questionnaire.questions
+      .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 {
+  switch (answer.kind) {
+    case "choice":
+      return {
+        kind: "choice",
+        selections: normalizeChoiceSelections(answer.selections),
+      };
+    case "custom":
+      return { kind: "custom", value: answer.value.trim() };
+    case "text":
+      return { kind: "text", value: answer.value.trim() };
+  }
+}
+
+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/session/lock.ts

@@ -0,0 +1,19 @@
+// Session-scoped single-active interaction guard for ask_user.
+
+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/src/tool/guidance.ts

@@ -0,0 +1,15 @@
+// Prompt guidance and tool description for the redesigned ask_user tool.
+
+export const toolDescription =
+  "Ask the user for a focused blocking decision when explicit input is required to proceed safely. Requires an interactive UI with custom overlay support, and only one ask_user form can be active at a time. Use 1-4 related `choice` or `text` questions. Do not use ask_user for open-ended interviews or repo facts you can get yourself. Forms may allow partial submit or discussion handoff.";
+
+export const promptSnippet = "ask_user — request a focused blocking user decision";
+
+export const promptGuidelines = [
+  "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.",
+];

package/src/types.ts

@@ -1,10 +1,8 @@
-// Internal data model used by both UI paths and result formatting.
-// The external (model-facing) schema lives in `schema.ts`; everything beyond
-// parsing passes through normalization into the shapes defined here.
+// Shared internal and public data model for the redesigned ask_user tool.
+// The external tool-call schema lives in schema.ts; everything past validation
+// works with the normalized shapes defined here.
 
-export type QuestionType = "choice" | "text";
-
-export type TerminalState = "submitted" | "cancelled" | "aborted" | "skipped";
+export type AskUserStatus = "submitted" | "partial" | "discuss" | "cancelled" | "aborted";
 
 export interface NormalizedOption {
   value: string;
@@ -17,102 +15,105 @@ interface BaseQuestion {
   id: string;
   header: string;
   prompt: string;
-  type: QuestionType;
   required: boolean;
 }
 
-interface StructuredQuestionBase extends BaseQuestion {
+export interface NormalizedChoiceQuestion extends BaseQuestion {
+  type: "choice";
   options: NormalizedOption[];
+  multi: boolean;
   allowOther: boolean;
-  allowDiscuss: boolean;
   recommendedIndexes: number[];
-  defaultIndexes: number[];
-  multi: boolean;
-}
-
-export interface NormalizedChoiceQuestion extends StructuredQuestionBase {
-  type: "choice";
+  initialIndexes: number[];
 }
 
 export interface NormalizedTextQuestion extends BaseQuestion {
   type: "text";
-  options: [];
-  default?: string;
+  initial?: string;
+  placeholder?: string;
 }
 
-export type NormalizedStructuredQuestion = NormalizedChoiceQuestion;
-
 export type NormalizedQuestion = NormalizedChoiceQuestion | NormalizedTextQuestion;
 
 export interface NormalizedQuestionnaire {
+  title?: string;
+  intro?: string;
   questions: NormalizedQuestion[];
-  allowSkip: boolean;
+  allowPartialSubmit: boolean;
+  allowDiscuss: boolean;
 }
 
-export interface Selection {
+/**
+ * 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;
-  optionIndex: number;
+  label: string;
   note?: string;
 }
 
 export interface ChoiceAnswer {
-  questionId: string;
-  source: "choice";
-  selections: Selection[];
+  kind: "choice";
+  selections: AnswerSelection[];
 }
 
-export interface OtherAnswer {
-  questionId: string;
-  source: "other";
+export interface CustomAnswer {
+  kind: "custom";
   value: string;
 }
 
-export interface DiscussAnswer {
-  questionId: string;
-  source: "discuss";
-  value?: string;
-}
-
 export interface TextAnswer {
-  questionId: string;
-  source: "text";
+  kind: "text";
   value: string;
 }
 
-export type Answer = ChoiceAnswer | OtherAnswer | DiscussAnswer | TextAnswer;
+export type Answer = ChoiceAnswer | CustomAnswer | TextAnswer;
 
-export interface QuestionnaireOutcome {
-  terminalState: TerminalState;
-  answers: Answer[];
-  skipped?: true;
+export interface AskUserOutcome {
+  status: AskUserStatus;
+  answersById: Record<string, Answer>;
+  missingQuestionIds: string[];
+  discussMessage?: string;
 }
 
-export interface AskUserDetails {
+export interface AskUserDetails extends AskUserOutcome {
+  title?: string;
+  intro?: string;
   questions: NormalizedQuestion[];
-  answers: Answer[];
-  answersById: Record<string, Answer | undefined>;
-  terminalState: TerminalState;
 }
 
-export const QUESTION_LIMITS = {
+export interface AskUserErrorDetails {
+  kind: "error";
+  message: string;
+}
+
+export type AskUserToolDetails = AskUserDetails | AskUserErrorDetails;
+
+export const ASK_USER_LIMITS = {
   minQuestions: 1,
   maxQuestions: 4,
-  maxHeaderLength: 60,
-  maxPromptLength: 4000,
   minChoiceOptions: 2,
   maxChoiceOptions: 12,
+  maxHeaderLength: 60,
+  maxPromptLength: 4000,
+  maxTitleLength: 120,
+  maxIntroLength: 4000,
+  maxPlaceholderLength: 200,
 } as const;
 
-export function isStructuredQuestion(
+export function isChoiceQuestion(
   question: NormalizedQuestion,
-): question is NormalizedStructuredQuestion {
-  return question.type !== "text";
+): question is NormalizedChoiceQuestion {
+  return question.type === "choice";
 }
 
-export function needsReview(questions: NormalizedQuestion[]): boolean {
-  return questions.length > 1 || questions.some((q) => q.type !== "text" && q.multi);
+export function isTextQuestion(question: NormalizedQuestion): question is NormalizedTextQuestion {
+  return question.type === "text";
 }
 
-export function primaryRecommendationIndex(question: NormalizedQuestion): number | undefined {
-  return isStructuredQuestion(question) ? question.recommendedIndexes[0] : undefined;
+export function isErrorDetails(details: AskUserToolDetails): details is AskUserErrorDetails {
+  return "kind" in details && details.kind === "error";
 }

package/src/ui/choose-renderer.ts

@@ -0,0 +1,11 @@
+import type { AskUserOutcome, NormalizedQuestionnaire } from "../types.ts";
+import { runOverlayQuestionnaire } from "./overlay.ts";
+import type { RunQuestionnaireOptions } from "./types.ts";
+
+export async function runQuestionnaire(
+  questionnaire: NormalizedQuestionnaire,
+  opts: RunQuestionnaireOptions,
+): Promise<AskUserOutcome | "unsupported"> {
+  if (typeof opts.ui.custom !== "function") return "unsupported";
+  return runOverlayQuestionnaire(questionnaire, opts);
+}

package/src/ui/overlay-actions.ts

@@ -0,0 +1,42 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { SelectList } from "@earendil-works/pi-tui";
+import type { AskUserController } from "../session/controller.ts";
+import { makeSelectListTheme } from "./overlay-render.ts";
+import { buildTextActionItems, type OverlayAction } from "./overlay-view.ts";
+
+export interface ActionListState {
+  entries: Array<{ action: OverlayAction; label: string }>;
+  list: SelectList | undefined;
+  index: number;
+}
+
+export function createActionList(args: {
+  controller: AskUserController;
+  theme: Theme;
+  actionIndex: number;
+  onIndexChange: (index: number) => void;
+  onAction: (action: OverlayAction) => void;
+}): ActionListState {
+  const actions = buildTextActionItems(args.controller);
+  const entries = actions.map(({ action, item }) => ({ action, label: item.label }));
+  if (actions.length === 0) {
+    return { entries, list: undefined, index: 0 };
+  }
+
+  const index = Math.max(0, Math.min(args.actionIndex, actions.length - 1));
+  const list = new SelectList(
+    actions.map(({ item }) => item),
+    Math.min(actions.length, 6),
+    makeSelectListTheme(args.theme),
+  );
+  list.onSelectionChange = (item) => {
+    const nextIndex = actions.findIndex(({ item: candidate }) => candidate.value === item.value);
+    if (nextIndex >= 0) args.onIndexChange(nextIndex);
+  };
+  list.onSelect = (item) => {
+    const action = actions.find(({ item: candidate }) => candidate.value === item.value)?.action;
+    if (action) args.onAction(action);
+  };
+  list.setSelectedIndex(index);
+  return { entries, list, index };
+}