@mrclrchtr/supi-ask-user 1.3.1 → 1.5.0

package/src/normalize.ts

@@ -1,13 +1,18 @@
-// 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.
+// Validation and normalization for ask_user tool calls.
 
-import type { AskUserParams, ExternalQuestion } from "./schema.ts";
+import type {
+  AskUserParams,
+  ExternalChoiceQuestion,
+  ExternalQuestion,
+  ExternalTextQuestion,
+} from "./schema.ts";
 import {
+  ASK_USER_LIMITS,
+  type NormalizedChoiceQuestion,
   type NormalizedOption,
   type NormalizedQuestion,
   type NormalizedQuestionnaire,
-  QUESTION_LIMITS,
+  type NormalizedTextQuestion,
 } from "./types.ts";
 
 export class AskUserValidationError extends Error {
@@ -18,212 +23,218 @@ export class AskUserValidationError extends Error {
 }
 
 export function normalizeQuestionnaire(params: AskUserParams): NormalizedQuestionnaire {
-  validateQuestionnaireShape(params);
-  return {
-    questions: params.questions.map((q) => normalizeQuestion(q)),
-    allowSkip: params.allowSkip ?? false,
-  };
-}
-
-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}).`,
-    );
+  validateQuestionCount(params.questions.length);
+  const title = trimOptional(params.title);
+  const intro = trimOptional(params.intro);
+  if (title && title.length > ASK_USER_LIMITS.maxTitleLength) {
+    throw new AskUserValidationError(`title exceeds ${ASK_USER_LIMITS.maxTitleLength} characters.`);
   }
+  if (intro && intro.length > ASK_USER_LIMITS.maxIntroLength) {
+    throw new AskUserValidationError(`intro exceeds ${ASK_USER_LIMITS.maxIntroLength} characters.`);
+  }
+
   const seen = new Set<string>();
-  for (const q of params.questions) {
-    const questionId = q.id.trim();
-    if (questionId.length === 0) continue;
-    if (seen.has(questionId)) {
+  const questions = params.questions.map((question) => {
+    const normalized = normalizeQuestion(question);
+    if (seen.has(normalized.id)) {
       throw new AskUserValidationError(
-        `Duplicate question id "${questionId}" — question ids must be unique within a questionnaire.`,
+        `Duplicate question id "${normalized.id}" — ids must be unique within one form.`,
       );
     }
-    seen.add(questionId);
-  }
+    seen.add(normalized.id);
+    return normalized;
+  });
+
+  return {
+    ...(title ? { title } : {}),
+    ...(intro ? { intro } : {}),
+    questions,
+    allowPartialSubmit: params.allowPartialSubmit ?? false,
+    allowDiscuss: params.allowDiscuss ?? false,
+  };
 }
 
-function normalizeQuestion(q: ExternalQuestion): NormalizedQuestion {
-  validateCommonFields(q);
-  switch (q.type) {
-    case "choice":
-      return normalizeChoice(q);
-    case "text":
-      return normalizeText(q);
-  }
+function normalizeQuestion(question: ExternalQuestion): NormalizedQuestion {
+  validateCommonFields(question);
+  return question.type === "choice" ? normalizeChoice(question) : normalizeText(question);
 }
 
-function validateCommonFields(q: ExternalQuestion): void {
-  if (q.id.trim().length === 0) {
-    throw new AskUserValidationError("Question id must be a non-empty string.");
+function validateQuestionCount(count: number): void {
+  if (count < ASK_USER_LIMITS.minQuestions || count > ASK_USER_LIMITS.maxQuestions) {
+    throw new AskUserValidationError(
+      `ask_user supports ${ASK_USER_LIMITS.minQuestions}-${ASK_USER_LIMITS.maxQuestions} questions only (got ${count}).`,
+    );
   }
-  if (q.header.trim().length === 0) {
-    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty header.`);
+}
+
+function validateCommonFields(question: ExternalQuestion): void {
+  const id = question.id.trim();
+  const header = question.header.trim();
+  const prompt = question.prompt.trim();
+
+  if (!id) throw new AskUserValidationError("Question id must be a non-empty string.");
+  if (!header) {
+    throw new AskUserValidationError(`Question "${question.id}" must include a non-empty header.`);
   }
-  if (q.header.length > QUESTION_LIMITS.maxHeaderLength) {
+  if (header.length > ASK_USER_LIMITS.maxHeaderLength) {
     throw new AskUserValidationError(
-      `Question "${q.id}" header exceeds ${QUESTION_LIMITS.maxHeaderLength} characters.`,
+      `Question "${question.id}" header exceeds ${ASK_USER_LIMITS.maxHeaderLength} characters.`,
     );
   }
-  if (q.prompt.trim().length === 0) {
-    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty prompt.`);
+  if (!prompt) {
+    throw new AskUserValidationError(`Question "${question.id}" must include a non-empty prompt.`);
   }
-  if (q.prompt.length > QUESTION_LIMITS.maxPromptLength) {
+  if (prompt.length > ASK_USER_LIMITS.maxPromptLength) {
     throw new AskUserValidationError(
-      `Question "${q.id}" prompt exceeds ${QUESTION_LIMITS.maxPromptLength} characters.`,
+      `Question "${question.id}" prompt exceeds ${ASK_USER_LIMITS.maxPromptLength} characters.`,
     );
   }
 }
 
-function normalizeChoice(q: {
-  type: "choice";
-  id: string;
-  header: string;
-  prompt: string;
-  required?: boolean;
-  multi?: boolean;
-  options: { value: string; label: string; description?: string; preview?: string }[];
-  allowOther?: boolean;
-  allowDiscuss?: boolean;
-  recommendation?: string | string[];
-  default?: string | string[];
-}): NormalizedQuestion {
-  const id = q.id.trim();
-  const options = normalizeStructuredOptions(id, q.options);
-  const multi = q.multi ?? false;
-  const recommendation = q.recommendation;
-  const defaultValue = q.default;
-
-  validateRecDefaultShape(id, recommendation, multi, "recommendation");
-  validateRecDefaultShape(id, defaultValue, multi, "default");
+function normalizeChoice(question: ExternalChoiceQuestion): NormalizedChoiceQuestion {
+  const options = normalizeOptions(question.id.trim(), question.options);
+  const multi = question.multi ?? false;
+  const allowOther = question.allowOther ?? false;
+  if (multi && allowOther) {
+    throw new AskUserValidationError(
+      `choice question "${question.id}" cannot use allowOther together with multi-select.`,
+    );
+  }
+
+  validateSelectionShape(question.id, question.recommendation, multi, "recommendation");
+  validateSelectionShape(question.id, question.initial, multi, "initial");
 
   return {
-    id,
-    header: q.header,
+    id: question.id.trim(),
+    header: question.header.trim(),
+    prompt: question.prompt.trim(),
+    required: question.required ?? true,
     type: "choice",
-    prompt: q.prompt,
-    required: q.required ?? true,
-    multi,
     options,
-    allowOther: q.allowOther ?? false,
-    allowDiscuss: q.allowDiscuss ?? false,
-    recommendedIndexes: resolveRecDefault(id, options, recommendation, multi, "recommendation"),
-    defaultIndexes: resolveRecDefault(id, options, defaultValue, multi, "default"),
+    multi,
+    allowOther,
+    recommendedIndexes: resolveIndexes({
+      questionId: question.id,
+      options,
+      value: question.recommendation,
+      multi,
+      kind: "recommendation",
+    }),
+    initialIndexes: resolveIndexes({
+      questionId: question.id,
+      options,
+      value: question.initial,
+      multi,
+      kind: "initial",
+    }),
   };
 }
 
-function validateRecDefaultShape(
-  questionId: string,
-  value: string | string[] | undefined,
-  multi: boolean,
-  kind: string,
-): void {
-  if (value === undefined) return;
-  if (!multi && Array.isArray(value)) {
-    throw new AskUserValidationError(
-      `single-select question "${questionId}" ${kind} must be a string, not an array.`,
-    );
-  }
-  if (multi && !Array.isArray(value)) {
+function normalizeText(question: ExternalTextQuestion): NormalizedTextQuestion {
+  const placeholder = trimOptional(question.placeholder);
+  if (placeholder && placeholder.length > ASK_USER_LIMITS.maxPlaceholderLength) {
     throw new AskUserValidationError(
-      `multi-select question "${questionId}" ${kind} must be an array, not a string.`,
+      `Question "${question.id}" placeholder exceeds ${ASK_USER_LIMITS.maxPlaceholderLength} characters.`,
     );
   }
-}
 
-function normalizeText(q: {
-  id: string;
-  header: string;
-  prompt: string;
-  required?: boolean;
-  default?: string;
-}): NormalizedQuestion {
   return {
-    id: q.id.trim(),
-    header: q.header,
+    id: question.id.trim(),
+    header: question.header.trim(),
+    prompt: question.prompt.trim(),
+    required: question.required ?? true,
     type: "text",
-    prompt: q.prompt,
-    required: q.required ?? true,
-    options: [],
-    ...(q.default !== undefined ? { default: q.default.trim() } : {}),
+    ...(question.initial !== undefined ? { initial: question.initial } : {}),
+    ...(placeholder ? { placeholder } : {}),
   };
 }
 
-function normalizeStructuredOptions(
+function normalizeOptions(
   questionId: string,
-  options: { value: string; label: string; description?: string; preview?: string }[],
+  options: ExternalChoiceQuestion["options"],
 ): NormalizedOption[] {
-  const optionCount = options.length;
   if (
-    optionCount < QUESTION_LIMITS.minChoiceOptions ||
-    optionCount > QUESTION_LIMITS.maxChoiceOptions
+    options.length < ASK_USER_LIMITS.minChoiceOptions ||
+    options.length > ASK_USER_LIMITS.maxChoiceOptions
   ) {
     throw new AskUserValidationError(
-      `choice question "${questionId}" must have ${QUESTION_LIMITS.minChoiceOptions}-${QUESTION_LIMITS.maxChoiceOptions} options (got ${optionCount}).`,
+      `choice question "${questionId}" must have ${ASK_USER_LIMITS.minChoiceOptions}-${ASK_USER_LIMITS.maxChoiceOptions} options (got ${options.length}).`,
     );
   }
-  const seenValues = new Set<string>();
-  return options.map((opt) => {
-    const value = opt.value.trim();
-    if (value.length === 0 || opt.label.trim().length === 0) {
+
+  const seen = new Set<string>();
+  return options.map((option) => {
+    const value = option.value.trim();
+    const label = option.label.trim();
+    if (!value || !label) {
       throw new AskUserValidationError(
         `choice question "${questionId}" has an option with empty value or label.`,
       );
     }
-    if (seenValues.has(value)) {
+    if (seen.has(value)) {
       throw new AskUserValidationError(
         `choice question "${questionId}" has duplicate option value "${value}".`,
       );
     }
-    seenValues.add(value);
+    seen.add(value);
     return {
       value,
-      label: opt.label,
-      description: opt.description,
-      preview: opt.preview,
+      label,
+      description: trimOptional(option.description),
+      preview: trimOptional(option.preview),
     };
   });
 }
 
-// biome-ignore lint/complexity/useMaxParams: five distinct positional params are cleaner than a non-reusable options object for this internal helper
-function resolveRecDefault(
+function validateSelectionShape(
   questionId: string,
-  options: NormalizedOption[],
   value: string | string[] | undefined,
   multi: boolean,
-  kind: "recommendation" | "default",
-): number[] {
-  if (value === undefined) return [];
-  const verb = kind === "recommendation" ? "recommends" : "defaults to";
-  if (!multi) {
-    const trimmed = (value as string).trim();
-    const idx = options.findIndex((opt) => opt.value === trimmed);
-    if (idx < 0) {
-      throw new AskUserValidationError(
-        `choice question "${questionId}" ${verb} "${trimmed}", which is not one of its option values.`,
-      );
-    }
-    return [idx];
+  kind: "recommendation" | "initial",
+): void {
+  if (value === undefined) return;
+  if (multi && !Array.isArray(value)) {
+    throw new AskUserValidationError(
+      `multi-select question "${questionId}" ${kind} must be an array, not a string.`,
+    );
   }
-  const values = value as string[];
-  if (values.length === 0) return [];
+  if (!multi && Array.isArray(value)) {
+    throw new AskUserValidationError(
+      `single-select question "${questionId}" ${kind} must be a string, not an array.`,
+    );
+  }
+}
+
+function resolveIndexes(args: {
+  questionId: string;
+  options: NormalizedOption[];
+  value: string | string[] | undefined;
+  multi: boolean;
+  kind: "recommendation" | "initial";
+}): number[] {
+  const { questionId, options, value, multi, kind } = args;
+  if (value === undefined) return [];
+  const values = multi ? (value as string[]) : [value as string];
   const seen = new Set<string>();
-  return values.map((v) => {
-    const trimmed = v.trim();
+  return values.map((entry: string) => {
+    const trimmed = entry.trim();
     if (seen.has(trimmed)) {
       throw new AskUserValidationError(
-        `choice question "${questionId}" has duplicate ${kind === "recommendation" ? "recommended" : "default"} value "${trimmed}".`,
+        `choice question "${questionId}" has duplicate ${kind} value "${trimmed}".`,
       );
     }
     seen.add(trimmed);
-    const idx = options.findIndex((opt) => opt.value === trimmed);
-    if (idx < 0) {
+    const index = options.findIndex((option) => option.value === trimmed);
+    if (index < 0) {
       throw new AskUserValidationError(
-        `choice question "${questionId}" ${verb} "${trimmed}", which is not one of its option values.`,
+        `choice question "${questionId}" ${kind} value "${trimmed}" does not match any option value.`,
       );
     }
-    return idx;
+    return index;
   });
 }
+
+function trimOptional(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}

package/src/render/result.ts

@@ -0,0 +1,102 @@
+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(formatChoiceSelectionSummary).join("; ");
+    case "custom":
+      return `Other — ${answer.value}`;
+    case "text":
+      return answer.value;
+  }
+}
+
+function formatChoiceSelectionSummary(selection: { label: string; note?: string }): string {
+  return selection.note ? `${selection.label} (note: ${selection.note})` : selection.label;
+}
+
+function summarizeOutcome(questions: NormalizedQuestion[], outcome: AskUserOutcome): string {
+  if (outcome.status === "cancelled") return "User cancelled the form.";
+  if (outcome.status === "aborted") return "The form was aborted before completion.";
+
+  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}`;
+}