@mrclrchtr/supi-ask-user 0.1.0

package/render.ts

@@ -0,0 +1,90 @@
+// Custom renderCall / renderResult for the `ask_user` tool. Keeps the in-line
+// session transcript readable: a one-line "asking N questions: …" header on
+// the call, and a compact ✓ / cancelled / aborted summary on the result.
+
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { Text, truncateToWidth } from "@mariozechner/pi-tui";
+import { formatSummaryBody } from "./format.ts";
+import { ASK_USER_ERROR_MARKER } from "./result.ts";
+import type { AskUserDetails, NormalizedQuestion } from "./types.ts";
+
+const MAX_HEADER_LIST = 60;
+
+export function renderAskUserCall(args: unknown, theme: Theme): Text {
+  const headers = extractHeadersFromArgs(args);
+  const count = headers.length;
+  let text = theme.fg("toolTitle", theme.bold("ask_user "));
+  text += theme.fg("muted", `${count || "?"} question${count === 1 ? "" : "s"}`);
+  if (count > 0) {
+    text += theme.fg("dim", ` (${truncateToWidth(headers.join(", "), MAX_HEADER_LIST)})`);
+  }
+  return new Text(text, 0, 0);
+}
+
+export function renderAskUserResult(
+  result: { details?: unknown; content: { type: string; text?: string }[] },
+  theme: Theme,
+): Text {
+  if (isErrorDetails(result.details)) {
+    return new Text(theme.fg("error", result.content[0]?.text ?? "Error"), 0, 0);
+  }
+  const details = coerceDetails(result.details);
+  if (!details) {
+    const fallback = result.content[0];
+    return new Text(fallback?.type === "text" ? (fallback.text ?? "") : "", 0, 0);
+  }
+  if (details.terminalState === "cancelled") {
+    return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+  }
+  if (details.terminalState === "aborted") {
+    return new Text(theme.fg("error", "Aborted"), 0, 0);
+  }
+  return new Text(formatSubmittedSummary(details, theme), 0, 0);
+}
+
+function isErrorDetails(details: unknown): boolean {
+  return (
+    !!details &&
+    typeof details === "object" &&
+    (details as Record<string, unknown>)[ASK_USER_ERROR_MARKER] === true
+  );
+}
+
+function extractHeadersFromArgs(args: unknown): string[] {
+  if (!args || typeof args !== "object") return [];
+  const questions = (args as { questions?: unknown }).questions;
+  if (!Array.isArray(questions)) return [];
+  return questions
+    .map((question) =>
+      question && typeof question === "object"
+        ? (question as { header?: unknown }).header
+        : undefined,
+    )
+    .filter((header): header is string => typeof header === "string" && header.length > 0);
+}
+
+function coerceDetails(details: unknown): AskUserDetails | null {
+  if (!details || typeof details !== "object") return null;
+  const obj = details as { terminalState?: unknown; questions?: unknown; answers?: unknown };
+  if (typeof obj.terminalState !== "string") return null;
+  if (!Array.isArray(obj.questions) || !Array.isArray(obj.answers)) return null;
+  return obj as AskUserDetails;
+}
+
+function formatSubmittedSummary(details: AskUserDetails, theme: Theme): string {
+  const byId = new Map(details.answers.map((answer) => [answer.questionId, answer]));
+  return details.questions
+    .map((question) => formatLine(question, byId.get(question.id), theme))
+    .join("\n");
+}
+
+function formatLine(
+  question: NormalizedQuestion,
+  answer: AskUserDetails["answers"][number] | undefined,
+  theme: Theme,
+): string {
+  if (!answer) {
+    return `${theme.fg("warning", "○ ")}${theme.fg("muted", question.header)}: (no answer)`;
+  }
+  return `${theme.fg("success", "✓ ")}${theme.fg("accent", question.header)}: ${theme.fg("text", formatSummaryBody(question, answer))}`;
+}

package/result.ts

@@ -0,0 +1,69 @@
+// Hybrid result formatting: a concise natural-language summary the model can
+// continue from, plus structured per-question details for transcript rendering
+// and future state reconstruction.
+
+import { formatSummaryBody } from "./format.ts";
+import type {
+  Answer,
+  AskUserDetails,
+  NormalizedQuestion,
+  QuestionnaireOutcome,
+  TerminalState,
+} from "./types.ts";
+
+export interface HybridResult {
+  content: { type: "text"; text: string }[];
+  details: AskUserDetails;
+}
+
+export function buildResult(
+  questions: NormalizedQuestion[],
+  outcome: QuestionnaireOutcome,
+): HybridResult {
+  return {
+    content: [{ type: "text", text: summarize(questions, outcome) }],
+    details: {
+      questions,
+      answers: outcome.answers,
+      answersById: indexById(outcome.answers),
+      terminalState: outcome.terminalState,
+    },
+  };
+}
+
+function indexById(answers: Answer[]): Record<string, Answer> {
+  const out: Record<string, Answer> = {};
+  for (const answer of answers) out[answer.questionId] = answer;
+  return out;
+}
+
+export const ASK_USER_ERROR_MARKER = "__ask_user_error__";
+
+export function buildErrorResult(message: string): HybridResult {
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      questions: [],
+      answers: [],
+      answersById: {},
+      terminalState: "cancelled",
+      [ASK_USER_ERROR_MARKER]: true,
+    } as AskUserDetails & { [ASK_USER_ERROR_MARKER]: boolean },
+  };
+}
+
+function summarize(questions: NormalizedQuestion[], outcome: QuestionnaireOutcome): string {
+  if (outcome.terminalState !== "submitted") return summarizeTerminal(outcome.terminalState);
+  const byId = new Map(outcome.answers.map((answer) => [answer.questionId, answer]));
+  return questions.map((question) => formatAnswerLine(question, byId.get(question.id))).join("\n");
+}
+
+function summarizeTerminal(state: TerminalState): string {
+  if (state === "cancelled") return "User cancelled the questionnaire.";
+  return "Questionnaire was aborted before the user submitted answers.";
+}
+
+function formatAnswerLine(question: NormalizedQuestion, answer: Answer | undefined): string {
+  if (!answer) return `${question.header}: (no answer)`;
+  return `${question.header}: ${formatSummaryBody(question, answer)}`;
+}

package/schema.ts

@@ -0,0 +1,103 @@
+// External (model-facing) parameter schema for the `ask_user` tool.
+// Rich-TUI-first redesign: explicit question kinds, explicit escape hatches,
+// and first-class option previews for structured comparisons.
+
+import { type Static, Type } from "@sinclair/typebox";
+
+const StructuredOptionSchema = Type.Object({
+  value: Type.String({ description: "Stable identifier returned in the answer" }),
+  label: Type.String({ description: "Display label shown to the user" }),
+  description: Type.Optional(
+    Type.String({ description: "Optional one-line clarification shown under the label" }),
+  ),
+  preview: Type.Optional(
+    Type.String({
+      description:
+        "Optional rich preview content shown in the TUI (markdown, code, or ASCII mockups)",
+    }),
+  ),
+});
+
+const StructuredQuestionBaseSchema = {
+  id: Type.String({ description: "Unique question id within this questionnaire" }),
+  header: Type.String({ description: "Short label (chip) describing the decision" }),
+  prompt: Type.String({ description: "Full question text shown to the user" }),
+  options: Type.Array(StructuredOptionSchema, {
+    description: "Allowed answers (2-8). Use distinct, mutually exclusive options.",
+  }),
+  allowOther: Type.Optional(
+    Type.Boolean({
+      description: "Allow an explicit custom answer path instead of forcing one of the options",
+    }),
+  ),
+  allowDiscuss: Type.Optional(
+    Type.Boolean({
+      description:
+        "Allow the user to choose discussion instead of committing to a decision right now",
+    }),
+  ),
+} as const;
+
+const ChoiceQuestionSchema = Type.Object({
+  type: Type.Literal("choice"),
+  ...StructuredQuestionBaseSchema,
+  recommendation: Type.Optional(
+    Type.String({ description: "Recommended option `value` (must match one of `options`)" }),
+  ),
+});
+
+const MultiChoiceQuestionSchema = Type.Object({
+  type: Type.Literal("multichoice"),
+  ...StructuredQuestionBaseSchema,
+  recommendation: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Recommended option `value`s for multi-select questions (each must match one of `options`)",
+    }),
+  ),
+});
+
+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" }),
+  prompt: Type.String({ description: "Full question text shown to the user" }),
+});
+
+const YesNoQuestionSchema = Type.Object({
+  type: Type.Literal("yesno"),
+  id: Type.String({ description: "Unique question id within this questionnaire" }),
+  header: Type.String({ description: "Short label (chip) describing the decision" }),
+  prompt: Type.String({ description: "Full yes/no question shown to the user" }),
+  allowOther: Type.Optional(
+    Type.Boolean({ description: "Allow an explicit custom answer path besides yes/no" }),
+  ),
+  allowDiscuss: Type.Optional(
+    Type.Boolean({ description: "Allow discussion instead of choosing yes or no" }),
+  ),
+  recommendation: Type.Optional(
+    Type.Union([Type.Literal("yes"), Type.Literal("no")], {
+      description: "Recommended answer (`yes` or `no`)",
+    }),
+  ),
+});
+
+const QuestionSchema = Type.Union([
+  ChoiceQuestionSchema,
+  MultiChoiceQuestionSchema,
+  TextQuestionSchema,
+  YesNoQuestionSchema,
+]);
+
+export const AskUserParamsSchema = Type.Object({
+  questions: Type.Array(QuestionSchema, {
+    description: "Between 1 and 4 focused decision questions",
+  }),
+});
+
+export type AskUserParams = Static<typeof AskUserParamsSchema>;
+export type ExternalQuestion = Static<typeof QuestionSchema>;
+export type ExternalChoiceQuestion = Static<typeof ChoiceQuestionSchema>;
+export type ExternalMultiChoiceQuestion = Static<typeof MultiChoiceQuestionSchema>;
+export type ExternalTextQuestion = Static<typeof TextQuestionSchema>;
+export type ExternalYesNoQuestion = Static<typeof YesNoQuestionSchema>;

package/types.ts

@@ -0,0 +1,151 @@
+// 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.
+
+export type QuestionType = "choice" | "multichoice" | "text" | "yesno";
+
+export type TerminalState = "submitted" | "cancelled" | "aborted";
+
+export interface NormalizedOption {
+  value: string;
+  label: string;
+  description?: string;
+  preview?: string;
+}
+
+interface BaseQuestion {
+  id: string;
+  header: string;
+  prompt: string;
+  type: QuestionType;
+}
+
+interface StructuredQuestionBase extends BaseQuestion {
+  options: NormalizedOption[];
+  allowOther: boolean;
+  allowDiscuss: boolean;
+  recommendedIndexes: number[];
+}
+
+export interface NormalizedChoiceQuestion extends StructuredQuestionBase {
+  type: "choice";
+}
+
+export interface NormalizedMultiChoiceQuestion extends StructuredQuestionBase {
+  type: "multichoice";
+}
+
+export interface NormalizedYesNoQuestion extends StructuredQuestionBase {
+  type: "yesno";
+}
+
+export interface NormalizedTextQuestion extends BaseQuestion {
+  type: "text";
+  options: [];
+}
+
+export type NormalizedStructuredQuestion =
+  | NormalizedChoiceQuestion
+  | NormalizedMultiChoiceQuestion
+  | NormalizedYesNoQuestion;
+
+export type NormalizedQuestion =
+  | NormalizedChoiceQuestion
+  | NormalizedMultiChoiceQuestion
+  | NormalizedTextQuestion
+  | NormalizedYesNoQuestion;
+
+export interface NormalizedQuestionnaire {
+  questions: NormalizedQuestion[];
+}
+
+export interface OptionAnswer {
+  questionId: string;
+  source: "option";
+  value: string;
+  optionIndex: number;
+  note?: string;
+}
+
+export interface MultiSelection {
+  value: string;
+  optionIndex: number;
+  note?: string;
+}
+
+export interface OptionsAnswer {
+  questionId: string;
+  source: "options";
+  values: string[];
+  optionIndexes: number[];
+  selections: MultiSelection[];
+}
+
+export interface OtherAnswer {
+  questionId: string;
+  source: "other";
+  value: string;
+}
+
+export interface DiscussAnswer {
+  questionId: string;
+  source: "discuss";
+  value?: string;
+}
+
+export interface TextAnswer {
+  questionId: string;
+  source: "text";
+  value: string;
+}
+
+export interface YesNoAnswer {
+  questionId: string;
+  source: "yesno";
+  value: "yes" | "no";
+  optionIndex: 0 | 1;
+  note?: string;
+}
+
+export type Answer =
+  | OptionAnswer
+  | OptionsAnswer
+  | OtherAnswer
+  | DiscussAnswer
+  | TextAnswer
+  | YesNoAnswer;
+
+export interface QuestionnaireOutcome {
+  terminalState: TerminalState;
+  answers: Answer[];
+}
+
+export interface AskUserDetails {
+  questions: NormalizedQuestion[];
+  answers: Answer[];
+  answersById: Record<string, Answer>;
+  terminalState: TerminalState;
+}
+
+export const QUESTION_LIMITS = {
+  minQuestions: 1,
+  maxQuestions: 4,
+  maxHeaderLength: 40,
+  maxPromptLength: 2000,
+  minChoiceOptions: 2,
+  maxChoiceOptions: 8,
+} as const;
+
+export function isStructuredQuestion(
+  question: NormalizedQuestion,
+): question is NormalizedStructuredQuestion {
+  return question.type !== "text";
+}
+
+export function needsReview(questions: NormalizedQuestion[]): boolean {
+  return questions.length > 1 || questions.some((q) => q.type === "multichoice");
+}
+
+export function primaryRecommendationIndex(question: NormalizedQuestion): number | undefined {
+  return isStructuredQuestion(question) ? question.recommendedIndexes[0] : undefined;
+}

package/ui-fallback.ts

@@ -0,0 +1,274 @@
+// Dialog/input fallback for environments where ctx.ui.custom() is unavailable.
+// This path intentionally preserves the redesigned answer semantics while
+// flattening preview-heavy affordances into plain dialog lists.
+
+import { QuestionnaireFlow } from "./flow.ts";
+import { DISCUSS_LABEL, decorateOption, formatReviewLine, OTHER_LABEL } from "./format.ts";
+import type {
+  Answer,
+  NormalizedQuestion,
+  NormalizedStructuredQuestion,
+  QuestionnaireOutcome,
+} from "./types.ts";
+
+export interface FallbackDialogOptions {
+  signal?: AbortSignal;
+}
+
+export interface FallbackUi {
+  select(
+    title: string,
+    options: string[],
+    opts?: FallbackDialogOptions,
+  ): Promise<string | undefined>;
+  input(
+    title: string,
+    placeholder?: string,
+    opts?: FallbackDialogOptions,
+  ): Promise<string | undefined>;
+}
+
+interface RunOptions {
+  ui: FallbackUi;
+  signal?: AbortSignal;
+}
+
+type StepOutcome = "answered" | "cancelled" | "aborted";
+type CollectOutcome = Exclude<StepOutcome, "answered">;
+
+const REVIEW_SUBMIT = "Submit answers";
+const REVIEW_CANCEL = "Cancel questionnaire";
+const MULTI_SUBMIT = "Submit selections";
+
+export async function runFallbackQuestionnaire(
+  questions: NormalizedQuestion[],
+  options: RunOptions,
+): Promise<QuestionnaireOutcome> {
+  const flow = new QuestionnaireFlow(questions);
+  while (!flow.isTerminal()) {
+    if (options.signal?.aborted) {
+      flow.abort();
+      break;
+    }
+    const question = flow.currentQuestion;
+    if (!question) break;
+    const step = await askAndStore(question, flow, options);
+    if (step === "aborted") flow.abort();
+    else if (step === "cancelled") flow.cancel();
+    else await applyAdvance(flow, options);
+  }
+  return flow.outcome();
+}
+
+async function applyAdvance(flow: QuestionnaireFlow, opts: RunOptions): Promise<void> {
+  flow.advance();
+  if (flow.currentMode !== "reviewing" || !flow.allAnswered()) return;
+  const review = await runReviewStep(flow, opts);
+  if (review === "aborted") flow.abort();
+  else if (review === "cancelled") flow.cancel();
+  else flow.submit();
+}
+
+async function runReviewStep(
+  flow: QuestionnaireFlow,
+  opts: RunOptions,
+): Promise<"submit" | "cancelled" | "aborted"> {
+  const summary = flow.questions
+    .map(
+      (question) =>
+        `${question.header}: ${formatReviewLine(question, flow.getAnswer(question.id))}`,
+    )
+    .join("  |  ");
+  const choice = await opts.ui.select(
+    `Review answers — ${summary}`,
+    [REVIEW_SUBMIT, REVIEW_CANCEL],
+    {
+      signal: opts.signal,
+    },
+  );
+  if (opts.signal?.aborted) return "aborted";
+  if (choice === undefined || choice === REVIEW_CANCEL) return "cancelled";
+  return "submit";
+}
+
+async function askAndStore(
+  question: NormalizedQuestion,
+  flow: QuestionnaireFlow,
+  opts: RunOptions,
+): Promise<StepOutcome> {
+  const answer = await collectAnswer(question, opts);
+  if (answer === "aborted" || answer === "cancelled") return answer;
+  flow.setAnswer(answer);
+  return "answered";
+}
+
+function collectAnswer(
+  question: NormalizedQuestion,
+  opts: RunOptions,
+): Promise<Answer | CollectOutcome> {
+  if (question.type === "text") return collectText(question, opts);
+  if (question.type === "multichoice") return collectMultichoice(question, opts);
+  return collectStructured(question, opts, question.type === "yesno" ? "yesno" : "option");
+}
+
+async function collectText(
+  question: Extract<NormalizedQuestion, { type: "text" }>,
+  opts: RunOptions,
+): Promise<Answer | CollectOutcome> {
+  while (true) {
+    const value = await opts.ui.input(question.prompt, undefined, { signal: opts.signal });
+    if (opts.signal?.aborted) return "aborted";
+    if (value === undefined) return "cancelled";
+    const trimmed = value.trim();
+    if (trimmed.length > 0) return { questionId: question.id, source: "text", value: trimmed };
+  }
+}
+
+async function collectStructured(
+  question: NormalizedStructuredQuestion,
+  opts: RunOptions,
+  source: "option" | "yesno",
+): Promise<Answer | CollectOutcome> {
+  const labels = structuredChoiceLabels(question);
+  const choice = await opts.ui.select(question.prompt, labels, { signal: opts.signal });
+  if (opts.signal?.aborted) return "aborted";
+  if (choice === undefined) return "cancelled";
+  const index = labels.indexOf(choice);
+  if (index < 0) return "cancelled";
+  if (index < question.options.length) {
+    const option = question.options[index];
+    return source === "yesno"
+      ? {
+          questionId: question.id,
+          source: "yesno",
+          value: option.value as "yes" | "no",
+          optionIndex: index as 0 | 1,
+        }
+      : { questionId: question.id, source: "option", value: option.value, optionIndex: index };
+  }
+  return collectStructuredAction(question, index - question.options.length, opts);
+}
+
+function structuredChoiceLabels(question: NormalizedStructuredQuestion): string[] {
+  const labels = question.options.map((option, index) =>
+    numberedLabel(
+      index,
+      appendDescription(
+        decorateOption(option.label, question.recommendedIndexes.includes(index)),
+        option.description,
+      ),
+    ),
+  );
+  let offset = question.options.length;
+  if (question.allowOther) {
+    labels.push(numberedLabel(offset, OTHER_LABEL));
+    offset += 1;
+  }
+  if (question.allowDiscuss) labels.push(numberedLabel(offset, DISCUSS_LABEL));
+  return labels;
+}
+
+async function collectStructuredAction(
+  question: NormalizedStructuredQuestion,
+  actionIndex: number,
+  opts: RunOptions,
+): Promise<Answer | CollectOutcome> {
+  if (question.allowOther && actionIndex === 0) return collectOther(question, opts);
+  return collectDiscuss(question, opts);
+}
+
+async function collectOther(
+  question: NormalizedStructuredQuestion,
+  opts: RunOptions,
+): Promise<Answer | CollectOutcome> {
+  while (true) {
+    const value = await opts.ui.input(`${question.prompt} (${OTHER_LABEL})`, undefined, {
+      signal: opts.signal,
+    });
+    if (opts.signal?.aborted) return "aborted";
+    if (value === undefined) return "cancelled";
+    const trimmed = value.trim();
+    if (trimmed.length > 0) return { questionId: question.id, source: "other", value: trimmed };
+  }
+}
+
+async function collectDiscuss(
+  question: NormalizedStructuredQuestion,
+  opts: RunOptions,
+): Promise<Answer | CollectOutcome> {
+  const value = await opts.ui.input(`${question.prompt} (${DISCUSS_LABEL})`, "Optional context", {
+    signal: opts.signal,
+  });
+  if (opts.signal?.aborted) return "aborted";
+  if (value === undefined) return "cancelled";
+  const trimmed = value.trim();
+  return trimmed.length > 0
+    ? { questionId: question.id, source: "discuss", value: trimmed }
+    : { questionId: question.id, source: "discuss" };
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fallback multiselect loop is intentionally linear
+async function collectMultichoice(
+  question: Extract<NormalizedQuestion, { type: "multichoice" }>,
+  opts: RunOptions,
+): Promise<Answer | CollectOutcome> {
+  const selected = new Set<number>();
+  while (true) {
+    const labels = multichoiceLabels(question, selected);
+    const choice = await opts.ui.select(question.prompt, labels, { signal: opts.signal });
+    if (opts.signal?.aborted) return "aborted";
+    if (choice === undefined) return "cancelled";
+    const index = labels.indexOf(choice);
+    if (index < 0) return "cancelled";
+    if (index < question.options.length) {
+      if (selected.has(index)) selected.delete(index);
+      else selected.add(index);
+      continue;
+    }
+    const submitIndex = question.options.length;
+    if (index === submitIndex) {
+      if (selected.size === 0) continue;
+      const optionIndexes = [...selected].sort((a, b) => a - b);
+      const selections = optionIndexes.map((optionIndex) => ({
+        optionIndex,
+        value: question.options[optionIndex].value,
+      }));
+      return {
+        questionId: question.id,
+        source: "options",
+        values: selections.map((selection) => selection.value),
+        optionIndexes,
+        selections,
+      };
+    }
+    return collectDiscuss(question, opts);
+  }
+}
+
+function multichoiceLabels(
+  question: Extract<NormalizedQuestion, { type: "multichoice" }>,
+  selected: Set<number>,
+): string[] {
+  const labels = question.options.map((option, index) => {
+    const checked = selected.has(index) ? "[x]" : "[ ]";
+    const recommended = question.recommendedIndexes.includes(index);
+    return numberedLabel(
+      index,
+      appendDescription(
+        `${checked} ${decorateOption(option.label, recommended)}`,
+        option.description,
+      ),
+    );
+  });
+  labels.push(numberedLabel(question.options.length, MULTI_SUBMIT));
+  if (question.allowDiscuss) labels.push(numberedLabel(question.options.length + 1, DISCUSS_LABEL));
+  return labels;
+}
+
+function numberedLabel(index: number, label: string): string {
+  return `${index + 1}. ${label}`;
+}
+
+function appendDescription(label: string, description: string | undefined): string {
+  return description ? `${label} — ${description}` : label;
+}