@mrclrchtr/supi-ask-user 1.3.1 → 1.4.0

package/src/render/result.ts

@@ -0,0 +1,98 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type {
+  Answer,
+  AskUserDetails,
+  AskUserErrorDetails,
+  AskUserOutcome,
+  AskUserToolDetails,
+  NormalizedQuestion,
+  NormalizedQuestionnaire,
+} from "../types.ts";
+
+export type AskUserToolResult = AgentToolResult<AskUserToolDetails>;
+
+export function buildResult(
+  questionnaire: NormalizedQuestionnaire,
+  outcome: AskUserOutcome,
+): AskUserToolResult {
+  const details: AskUserDetails = {
+    ...(questionnaire.title ? { title: questionnaire.title } : {}),
+    ...(questionnaire.intro ? { intro: questionnaire.intro } : {}),
+    questions: questionnaire.questions,
+    status: outcome.status,
+    answersById: outcome.answersById,
+    missingQuestionIds: outcome.missingQuestionIds,
+    ...(outcome.discussMessage ? { discussMessage: outcome.discussMessage } : {}),
+  };
+
+  return {
+    content: [{ type: "text", text: summarizeOutcome(questionnaire.questions, outcome) }],
+    details,
+  };
+}
+
+export function buildErrorResult(message: string): AskUserToolResult {
+  const details: AskUserErrorDetails = { kind: "error", message };
+  return {
+    content: [{ type: "text", text: message }],
+    details,
+  };
+}
+
+export function formatAnswerSummary(_question: NormalizedQuestion, answer: Answer): string {
+  switch (answer.kind) {
+    case "choice":
+      return answer.selections.map((selection) => selection.label).join("; ");
+    case "custom":
+      return `Other — ${answer.value}`;
+    case "text":
+      return answer.value;
+  }
+}
+
+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.";
+
+  const lines = formatAnsweredLines(questions, outcome.answersById);
+  const missing = formatMissingHeaders(questions, outcome.missingQuestionIds);
+
+  if (outcome.status === "submitted") {
+    return lines.length > 0 ? lines.join("\n") : "User submitted the form.";
+  }
+
+  if (outcome.status === "partial") {
+    return [
+      "User submitted a partial form.",
+      ...lines,
+      ...(missing ? [`Missing required answers: ${missing}`] : []),
+    ].join("\n");
+  }
+
+  return [
+    "User wants to discuss before deciding.",
+    ...(outcome.discussMessage ? [`Discussion request: ${outcome.discussMessage}`] : []),
+    ...lines,
+    ...(missing ? [`Still missing: ${missing}`] : []),
+  ].join("\n");
+}
+
+function formatAnsweredLines(
+  questions: NormalizedQuestion[],
+  answersById: Record<string, Answer>,
+): string[] {
+  return questions.flatMap((question) => {
+    const answer = answersById[question.id];
+    return answer ? [`${question.header}: ${formatAnswerSummary(question, answer)}`] : [];
+  });
+}
+
+export function formatMissingHeaders(
+  questions: NormalizedQuestion[],
+  missingQuestionIds: string[],
+): string | undefined {
+  const headers = questions
+    .filter((question) => missingQuestionIds.includes(question.id))
+    .map((question) => question.header);
+  return headers.length > 0 ? headers.join(", ") : undefined;
+}

package/src/render/transcript.ts

@@ -0,0 +1,65 @@
+import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { AskUserParams } from "../schema.ts";
+import type { AskUserDetails, AskUserToolDetails } from "../types.ts";
+import { isErrorDetails } from "../types.ts";
+import { formatAnswerSummary, formatMissingHeaders } from "./result.ts";
+
+export function renderAskUserCall(args: AskUserParams, theme: Theme): Text {
+  const title = args.title?.trim();
+  const headers = args.questions.map((question) => question.header.trim()).filter(Boolean);
+  const label = title || `${headers.length} question${headers.length === 1 ? "" : "s"}`;
+  const suffix = title && headers.length > 0 ? ` (${headers.join(", ")})` : headers.join(", ");
+  const text = `${theme.fg("toolTitle", theme.bold("ask_user "))}${theme.fg("muted", label)}${suffix ? theme.fg("dim", ` ${suffix}`) : ""}`;
+  return new Text(text, 0, 0);
+}
+
+export function renderAskUserResult(
+  result: Pick<AgentToolResult<AskUserToolDetails>, "content" | "details">,
+  theme: Theme,
+): Text {
+  if (isErrorDetails(result.details)) {
+    return new Text(theme.fg("error", result.details.message), 0, 0);
+  }
+
+  const lines = buildResultLines(result.details, theme);
+  return new Text(lines.join("\n"), 0, 0);
+}
+
+function buildResultLines(details: AskUserDetails, theme: Theme): string[] {
+  const answersById = details.answersById;
+  const answerLines = details.questions.flatMap((question) => {
+    const answer = answersById[question.id];
+    return answer
+      ? [
+          `${theme.fg("success", "✓ ")}${theme.fg("accent", question.header)}: ${theme.fg("text", formatAnswerSummary(question, answer))}`,
+        ]
+      : [];
+  });
+
+  switch (details.status) {
+    case "submitted":
+      return answerLines.length > 0 ? answerLines : [theme.fg("success", "Submitted")];
+    case "partial": {
+      const missing = formatMissingHeaders(details.questions, details.missingQuestionIds);
+      return [
+        theme.fg("warning", "Partial"),
+        ...answerLines,
+        ...(missing ? [theme.fg("dim", `Missing required: ${missing}`)] : []),
+      ];
+    }
+    case "discuss": {
+      const missing = formatMissingHeaders(details.questions, details.missingQuestionIds);
+      return [
+        theme.fg("warning", "Discuss"),
+        ...(details.discussMessage ? [theme.fg("text", `Message: ${details.discussMessage}`)] : []),
+        ...answerLines,
+        ...(missing ? [theme.fg("dim", `Still missing: ${missing}`)] : []),
+      ];
+    }
+    case "cancelled":
+      return [theme.fg("warning", "Cancelled")];
+    case "aborted":
+      return [theme.fg("error", "Aborted")];
+  }
+}

package/src/render/tree-summary.ts

@@ -0,0 +1,10 @@
+import type { NormalizedQuestionnaire } from "../types.ts";
+
+export function buildTreeSummaryLabel(
+  questionnaire: Pick<NormalizedQuestionnaire, "title" | "questions">,
+): string {
+  const base =
+    questionnaire.title?.trim() || questionnaire.questions.map((q) => q.header).join(", ");
+  const trimmed = base.length > 70 ? `${base.slice(0, 67)}...` : base;
+  return `ask_user · ${trimmed}`;
+}

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,163 @@
+import type {
+  Answer,
+  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);
+  }
+
+  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);
+  }
+}
+
+function normalizeAnswer(answer: Answer): Answer {
+  switch (answer.kind) {
+    case "choice":
+      return {
+        kind: "choice",
+        selections: answer.selections.map((selection) => ({
+          value: selection.value.trim(),
+          label: selection.label.trim(),
+        })),
+      };
+    case "custom":
+      return { kind: "custom", value: answer.value.trim() };
+    case "text":
+      return { kind: "text", value: answer.value.trim() };
+  }
+}
+
+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,98 @@ 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 {
+export interface AnswerSelection {
   value: string;
-  optionIndex: number;
-  note?: string;
+  label: 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";
 }