@pi9/ask 0.1.0

package/src/replay-renderer.ts

@@ -0,0 +1,85 @@
+import type { MessageRenderOptions, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { parseAskReplayDetails, type AskReplayDetails } from "./replay.js";
+
+interface RenderMessage {
+  content?: unknown;
+  details?: unknown;
+}
+
+type Selection = AskReplayDetails["answer"]["selections"][number];
+type RecordValue = Record<string, unknown>;
+
+/**
+ * Render a completed ask replay for registration with
+ * `pi.registerMessageRenderer("ask:reanswer", renderAskReanswerMessage)`.
+ *
+ * The renderer deliberately returns a Text component rather than pre-wrapped
+ * strings. Text performs wrapping using terminal column widths, including
+ * when the theme has added ANSI styling to the label.
+ */
+export const renderAskReanswerMessage = (
+  message: RenderMessage,
+  options: Pick<MessageRenderOptions, "expanded">,
+  theme: Pick<Theme, "fg"> | undefined,
+): Text => renderMessage(message, options, theme);
+
+function renderMessage(
+  message: RenderMessage,
+  options: Pick<MessageRenderOptions, "expanded">,
+  theme: Pick<Theme, "fg"> | undefined,
+): Text {
+  const details = parseAskReplayDetails(message.details);
+  const content = details
+    ? formatDetails(details, options.expanded, theme)
+    : textualContent(message.content);
+  return new Text(content, 0, 0);
+}
+
+function formatDetails(details: AskReplayDetails, expanded: boolean, theme: Pick<Theme, "fg"> | undefined): string {
+  const label = colorLabel("Revised answer", theme);
+  const selections = details.answer.selections;
+  const freeform = details.answer.freeform;
+
+  if (!expanded) {
+    const lines: string[] = [label];
+    if (selections.length > 0) lines.push(`Selected: ${selections.map(selection => selection.label).join(", ")}`);
+    if (freeform) lines.push(`Freeform: ${freeform}`);
+    if (selections.length === 0 && !freeform) lines.push("No answer provided.");
+    return lines.join(" · ");
+  }
+
+  const lines: string[] = [label, `Question: ${details.question}`];
+  if (details.context) lines.push(`Context: ${details.context}`);
+  if (selections.length > 0) {
+    lines.push("Selections:");
+    for (const selection of selections) {
+      let line = `- ${selection.label}`;
+      if (selection.description) line += ` — ${selection.description}`;
+      if (selection.comment) line += ` (${selection.comment})`;
+      lines.push(line);
+    }
+  }
+  if (freeform) lines.push(`Freeform: ${freeform}`);
+  if (selections.length === 0 && !freeform) lines.push("No answer provided.");
+  return lines.join("\n");
+}
+
+function textualContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(isRecord)
+    .filter(item => item.type === "text" && typeof item.text === "string")
+    .map(item => item.text as string)
+    .join("\n");
+}
+
+function colorLabel(label: string, theme: Pick<Theme, "fg"> | undefined): string {
+  return typeof theme?.fg === "function" ? theme.fg("customMessageLabel", label) : label;
+}
+
+function isRecord(value: unknown): value is RecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/replay.ts

@@ -0,0 +1,100 @@
+import type { SessionEntry, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import { Check } from "typebox/value";
+
+import { AskAnswerSchema, AskParamsSchema, AskReplayDetailsSchema } from "./schema.js";
+import { formatAskAnswer } from "./response.js";
+import type { AskAnswer, AskParams, AskReplayDetails, ValidatedAskParams } from "./types.js";
+import { validateAskParams } from "./validation.js";
+
+export const ASK_REPLAY_CUSTOM_TYPE = "ask:reanswer" as const;
+
+export type { AskReplayDetails } from "./types.js";
+
+export type AskReplayMessage = {
+  customType: typeof ASK_REPLAY_CUSTOM_TYPE;
+  content: string;
+  display: false;
+  details: AskReplayDetails;
+};
+
+/** Parse the canonical answer shape used by native results and replay details. */
+export function parseAskAnswer(value: unknown): AskAnswer | undefined {
+  return Check(AskAnswerSchema, value) ? value : undefined;
+}
+
+/** Parse canonical replay details, without validating the containing message. */
+export function parseAskReplayDetails(value: unknown): AskReplayDetails | undefined {
+  return Check(AskReplayDetailsSchema, value) ? value : undefined;
+}
+
+export type AskReplayResolution =
+  | { status: "resolved"; toolCallId: string; params: ValidatedAskParams }
+  | {
+      status: "not-replayable";
+      reason: "no-entry" | "not-assistant" | "not-ask" | "multiple-tool-calls" | "mixed-tools" | "invalid-arguments";
+    };
+
+export function buildAskReplayMessage(toolCallId: string, params: ValidatedAskParams, answer: AskAnswer): AskReplayMessage {
+  return {
+    customType: ASK_REPLAY_CUSTOM_TYPE,
+    content: formatAskAnswer(answer).replaceAll("\n", " · "),
+    display: false,
+    details: {
+      toolCallId,
+      question: params.question,
+      ...(params.context !== undefined ? { context: params.context } : {}),
+      allowMultiple: params.allowMultiple,
+      answer,
+    },
+  };
+}
+
+/** Resolve only the selected leaf, or its immediate parent when Pi created a branch summary. */
+export function resolveAskReplayTarget(
+  event: Pick<SessionTreeEvent, "newLeafId" | "summaryEntry">,
+  getEntry: (id: string) => SessionEntry | undefined | null,
+): AskReplayResolution {
+  if (!event.newLeafId) return rejected("no-entry");
+
+  let entry = getEntry(event.newLeafId);
+  const summary = event.summaryEntry?.id === event.newLeafId
+    ? event.summaryEntry
+    : entry?.type === "branch_summary" ? entry : undefined;
+  if (summary) entry = summary.parentId ? getEntry(summary.parentId) : undefined;
+  if (!entry) return rejected("no-entry");
+
+  let selectedToolCallId: string | undefined;
+  if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "ask") {
+    selectedToolCallId = entry.message.toolCallId;
+    entry = entry.parentId ? getEntry(entry.parentId) : undefined;
+  }
+  if (!entry) return rejected("no-entry");
+  if (entry.type !== "message" || entry.message.role !== "assistant") return rejected("not-assistant");
+
+  const calls = entry.message.content.filter((item) => item.type === "toolCall");
+  const askCalls = calls.filter((call) => call.name === "ask");
+  if (calls.length !== 1) {
+    if (askCalls.length > 0 && askCalls.length < calls.length) return rejected("mixed-tools");
+    if (askCalls.length > 1) return rejected("multiple-tool-calls");
+    return rejected("not-ask");
+  }
+  const call = calls[0];
+  if (call.name !== "ask" || (selectedToolCallId !== undefined && call.id !== selectedToolCallId)) return rejected("not-ask");
+
+  const params = validateStoredArgs(call.arguments);
+  if (!params) return rejected("invalid-arguments");
+  return { status: "resolved", toolCallId: call.id, params };
+}
+
+export function validateStoredArgs(value: unknown): ValidatedAskParams | undefined {
+  if (!Check(AskParamsSchema, value)) return undefined;
+  try {
+    return validateAskParams(value as AskParams);
+  } catch {
+    return undefined;
+  }
+}
+
+function rejected(reason: Exclude<AskReplayResolution, { status: "resolved" }>["reason"]): AskReplayResolution {
+  return { status: "not-replayable", reason };
+}

package/src/response.ts

@@ -0,0 +1,31 @@
+import type { AskAnswer, AskResponse, AskToolDetails } from "./types.js";
+
+export function formatAskAnswer(answer: AskAnswer): string {
+  const lines = answer.selections.map((selection) => {
+    const description = selection.description ? ` — ${selection.description}` : "";
+    const comment = selection.comment ? ` (${selection.comment})` : "";
+    return `Selected: ${selection.label}${description}${comment}`;
+  });
+  if (answer.freeform) lines.push(`Freeform: ${answer.freeform}`);
+  return lines.join("\n") || "No answer provided.";
+}
+
+export function buildAnsweredResponse(question: string, answer: AskAnswer): AskResponse {
+  return buildResponse(formatAskAnswer(answer), { status: "answered", question, answer });
+}
+
+export function buildUnansweredResponse(question: string): AskResponse {
+  return buildResponse("The question timed out without an answer.", { status: "unanswered", question });
+}
+
+export function buildCancelledResponse(question: string): AskResponse {
+  return buildResponse("User cancelled the question.", { status: "cancelled", question });
+}
+
+export function buildUiUnavailableResponse(question: string): AskResponse {
+  return buildResponse("Interactive UI is unavailable.", { status: "ui_unavailable", question });
+}
+
+function buildResponse(text: string, details: AskToolDetails): AskResponse {
+  return { content: [{ type: "text", text }], details };
+}

package/src/rpc.ts

@@ -0,0 +1,133 @@
+import type { AskAnswer, AskOption, ValidatedAskParams } from "./types.js";
+
+export interface AskDialogUI {
+  select(title: string, options: string[], dialogOptions?: { signal?: AbortSignal }): Promise<string | undefined>;
+  input(title: string, placeholder?: string, dialogOptions?: { signal?: AbortSignal }): Promise<string | undefined>;
+}
+
+type AskSelection = AskAnswer["selections"][number];
+
+const FREEFORM_CHOICE = "Type a response…";
+
+export async function askWithRpc(
+  ui: AskDialogUI,
+  params: ValidatedAskParams,
+  signal?: AbortSignal,
+): Promise<AskAnswer | null> {
+  const prompt = params.context ? `${params.context}\n\n${params.question}` : params.question;
+  if (signal?.aborted) return null;
+
+  return params.allowMultiple
+    ? runMultiSelect(ui, prompt, params.options, params.allowFreeform, signal)
+    : runSingleSelect(ui, prompt, params.options, params.allowFreeform, signal);
+}
+
+async function runSingleSelect(
+  ui: AskDialogUI,
+  prompt: string,
+  options: AskOption[],
+  allowFreeform: boolean,
+  signal?: AbortSignal,
+): Promise<AskAnswer | null> {
+  const choices = options.map((option, index) => `${index + 1}. ${formatOption(option)}`);
+  if (allowFreeform) choices.push(`${options.length + 1}. ${FREEFORM_CHOICE}`);
+
+  const selected = await selectDialog(ui, prompt, choices, signal);
+  if (selected == null || signal?.aborted) return null;
+
+  const selectedIndex = choices.indexOf(selected);
+  if (selectedIndex === -1) return null;
+  if (selectedIndex === options.length) {
+    const freeform = await readInput(ui, prompt, signal);
+    return freeform === null ? null : makeAnswer([], freeform);
+  }
+
+  const selectedOption = options[selectedIndex];
+  if (!selectedOption) return null;
+  const selections = await collectComments(ui, prompt, [selectedOption], signal);
+  return selections === null ? null : makeAnswer(selections);
+}
+
+async function runMultiSelect(
+  ui: AskDialogUI,
+  prompt: string,
+  options: AskOption[],
+  allowFreeform: boolean,
+  signal?: AbortSignal,
+): Promise<AskAnswer | null> {
+  const numberedOptions = options
+    .map((option, index) => `${index + 1}. ${formatOption(option)}`)
+    .join("\n");
+  const selectionPrompt = `${prompt}\n\n${numberedOptions}\n\nEnter option numbers separated by commas:`;
+  const rawSelection = await readInput(ui, selectionPrompt, signal);
+  if (rawSelection === null) return null;
+
+  const selectedOptions = parseSelections(rawSelection, options);
+  const freeform = allowFreeform
+    ? await readInput(ui, `${prompt}\n\nAdditional response (optional):`, signal)
+    : undefined;
+  if (freeform === null) return null;
+
+  const selections = await collectComments(ui, prompt, selectedOptions, signal);
+  return selections === null ? null : makeAnswer(selections, freeform);
+}
+
+function parseSelections(raw: string, options: AskOption[]): AskOption[] {
+  const indices = new Set<number>();
+  for (const token of raw.split(",")) {
+    const value = token.trim();
+    if (!/^\d+$/.test(value)) continue;
+
+    const index = Number(value) - 1;
+    if (Number.isSafeInteger(index) && index >= 0 && index < options.length) indices.add(index);
+  }
+  return options.filter((_option, index) => indices.has(index));
+}
+
+async function collectComments(
+  ui: AskDialogUI,
+  prompt: string,
+  options: AskOption[],
+  signal?: AbortSignal,
+): Promise<AskSelection[] | null> {
+  const selections: AskSelection[] = options.map(toSelection);
+  for (let index = 0; index < options.length; index++) {
+    const option = options[index];
+    const selection = selections[index];
+    if (!option || !selection) continue;
+
+    const comment = await readInput(ui, `${prompt}\n\nComment for \"${option.label}\" (optional):`, signal);
+    if (comment === null) return null;
+    if (comment) selection.comment = comment;
+  }
+  return selections;
+}
+
+async function readInput(ui: AskDialogUI, title: string, signal?: AbortSignal): Promise<string | null> {
+  if (signal?.aborted) return null;
+  const value = await inputDialog(ui, title, signal);
+  if (value == null || signal?.aborted) return null;
+  return value.trim();
+}
+
+function toSelection(option: AskOption): AskSelection {
+  const selection: AskSelection = { label: option.label };
+  if (option.description !== undefined) selection.description = option.description;
+  return selection;
+}
+
+function makeAnswer(selections: AskSelection[], freeform?: string): AskAnswer {
+  return freeform ? { selections, freeform } : { selections };
+}
+
+function formatOption(option: AskOption): string {
+  return option.description ? `${option.label} — ${option.description}` : option.label;
+}
+
+function selectDialog(ui: AskDialogUI, title: string, options: string[], signal?: AbortSignal) {
+  return signal ? ui.select(title, options, { signal }) : ui.select(title, options);
+}
+
+function inputDialog(ui: AskDialogUI, title: string, signal?: AbortSignal) {
+  return signal ? ui.input(title, undefined, { signal }) : ui.input(title);
+}

package/src/schema.ts

@@ -0,0 +1,43 @@
+import { Type } from "typebox";
+
+import { MAX_TIMEOUT_MS } from "./config.js";
+
+export const AskOptionSchema = Type.Object({
+  label: Type.String({ minLength: 1, description: "Short option title; keep distinct across options." }),
+  description: Type.Optional(Type.String({ description: "Brief explanation when the label alone is ambiguous." })),
+  preview: Type.Optional(Type.String({ description: "Markdown shown to the user, e.g. code, plans, or comparisons; not returned in the answer." })),
+}, { additionalProperties: false });
+
+export const AskParamsSchema = Type.Object({
+  question: Type.String({ minLength: 1 }),
+  context: Type.Optional(Type.String({ description: "Optional background shown above the question, e.g. what prompted the ask." })),
+  options: Type.Array(AskOptionSchema, { minItems: 1, description: "Suggested answers." }),
+  allowMultiple: Type.Optional(Type.Boolean({ default: false, description: "Allow selecting multiple options. Defaults to false." })),
+  allowFreeform: Type.Optional(Type.Boolean({ default: true, description: "Allow a typed response. Defaults to true." })),
+  timeout: Type.Optional(Type.Integer({ minimum: 0, maximum: MAX_TIMEOUT_MS, description: "Timeout in ms for answers that would go stale; the call returns unanswered on expiry. Zero disables any default." })),
+}, { additionalProperties: false });
+
+export const AskSelectionSchema = Type.Object({
+  label: Type.String({ minLength: 1 }),
+  description: Type.Optional(Type.String({ minLength: 1 })),
+  comment: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+export const AskAnswerSchema = Type.Object({
+  selections: Type.Array(AskSelectionSchema),
+  freeform: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+export const AskReplayDetailsSchema = Type.Object({
+  toolCallId: Type.String({ minLength: 1 }),
+  question: Type.String({ minLength: 1 }),
+  context: Type.Optional(Type.String({ minLength: 1 })),
+  allowMultiple: Type.Boolean(),
+  answer: AskAnswerSchema,
+}, { additionalProperties: false });
+
+export const AskAnsweredDetailsSchema = Type.Object({
+  status: Type.Literal("answered"),
+  question: Type.String({ minLength: 1 }),
+  answer: AskAnswerSchema,
+}, { additionalProperties: false });

package/src/state.ts

@@ -0,0 +1,203 @@
+import type { AskAnswer, AskOption, ValidatedAskParams } from "./types.js";
+
+export type QuestionnaireOptionRow = { kind: "option"; option: AskOption };
+export type QuestionnaireFreeformRow = { kind: "freeform" };
+export type QuestionnaireSubmitRow = { kind: "submit" };
+export type QuestionnaireRow =
+  | QuestionnaireOptionRow
+  | QuestionnaireFreeformRow
+  | QuestionnaireSubmitRow;
+
+export type QuestionnaireEditor =
+  | { kind: "select" }
+  | { kind: "comment"; target: QuestionnaireOptionRow; draft: string }
+  | { kind: "freeform"; target: QuestionnaireFreeformRow; draft: string };
+
+type QuestionnaireConfig = Pick<ValidatedAskParams, "allowMultiple" | "allowFreeform">;
+type QuestionnaireInput = QuestionnaireConfig & Pick<ValidatedAskParams, "options">;
+
+export interface QuestionnaireState {
+  config: QuestionnaireConfig;
+  rows: readonly QuestionnaireRow[];
+  highlightedRow: number;
+  checked: Set<string>;
+  comments: Map<string, string>;
+  freeformDraft: string;
+  freeformChecked: boolean;
+  editor: QuestionnaireEditor;
+  answer: AskAnswer | null;
+}
+
+export type QuestionnaireEvent =
+  | { type: "move"; delta: number }
+  | { type: "activate" }
+  | { type: "toggle" }
+  | { type: "openComment" }
+  | { type: "edit"; value: string }
+  | { type: "saveEditor" }
+  | { type: "cancelEditor" }
+  | { type: "submit" };
+
+export function createQuestionnaireState(input: QuestionnaireInput): QuestionnaireState {
+  if (input.options.length === 0) throw new Error("Questionnaire requires at least one option");
+
+  return {
+    config: {
+      allowMultiple: input.allowMultiple,
+      allowFreeform: input.allowFreeform,
+    },
+    rows: createRows(input),
+    highlightedRow: 0,
+    checked: new Set(),
+    comments: new Map(),
+    freeformDraft: "",
+    freeformChecked: false,
+    editor: { kind: "select" },
+    answer: null,
+  };
+}
+
+export function transitionQuestionnaire(state: QuestionnaireState, event: QuestionnaireEvent): QuestionnaireState {
+  if (state.answer) return state;
+  const next = clone(state);
+
+  switch (event.type) {
+    case "move":
+      if (next.editor.kind === "select") {
+        next.highlightedRow = wrapRow(next.highlightedRow + event.delta, next.rows.length);
+      }
+      break;
+    case "activate":
+      if (next.editor.kind === "select") activateRow(next);
+      break;
+    case "toggle":
+      if (next.editor.kind === "select") toggleRow(next);
+      break;
+    case "openComment": {
+      if (next.editor.kind !== "select") break;
+      const row = currentRow(next);
+      if (row.kind !== "option") break;
+      next.editor = {
+        kind: "comment",
+        target: row,
+        draft: next.comments.get(row.option.label) ?? "",
+      };
+      break;
+    }
+    case "edit":
+      if (next.editor.kind !== "select") next.editor = { ...next.editor, draft: event.value };
+      break;
+    case "saveEditor": {
+      if (next.editor.kind === "select") break;
+      const editor = next.editor;
+      const saved = editor.draft.trim();
+      if (editor.kind === "comment") {
+        const label = editor.target.option.label;
+        if (saved) next.comments.set(label, saved);
+        else next.comments.delete(label);
+      } else {
+        next.freeformDraft = saved;
+        if (next.config.allowMultiple) next.freeformChecked = saved.length > 0;
+      }
+      next.editor = { kind: "select" };
+      if (editor.kind === "freeform" && !next.config.allowMultiple && saved) {
+        next.answer = finalAnswer(next);
+      }
+      break;
+    }
+    case "cancelEditor":
+      if (next.editor.kind !== "select") next.editor = { kind: "select" };
+      break;
+    case "submit":
+      next.answer = finalAnswer(next);
+      break;
+  }
+  return next;
+}
+
+function createRows(input: QuestionnaireInput): QuestionnaireRow[] {
+  return [
+    ...input.options.map((option): QuestionnaireOptionRow => ({ kind: "option", option })),
+    ...(input.allowFreeform ? [{ kind: "freeform" } as const] : []),
+    ...(input.allowMultiple ? [{ kind: "submit" } as const] : []),
+  ];
+}
+
+function currentRow(state: QuestionnaireState): QuestionnaireRow {
+  return state.rows[state.highlightedRow]!;
+}
+
+function activateRow(state: QuestionnaireState): void {
+  const row = currentRow(state);
+  switch (row.kind) {
+    case "option":
+      toggleOption(state, row.option);
+      break;
+    case "freeform":
+      openFreeform(state, row);
+      break;
+    case "submit":
+      state.answer = finalAnswer(state);
+      break;
+  }
+}
+
+function toggleRow(state: QuestionnaireState): void {
+  const row = currentRow(state);
+  switch (row.kind) {
+    case "option":
+      toggleOption(state, row.option);
+      break;
+    case "freeform":
+      if (state.config.allowMultiple) state.freeformChecked = !state.freeformChecked;
+      else openFreeform(state, row);
+      break;
+    case "submit":
+      state.answer = finalAnswer(state);
+      break;
+  }
+}
+
+function toggleOption(state: QuestionnaireState, option: AskOption): void {
+  if (!state.config.allowMultiple) {
+    state.checked = new Set([option.label]);
+    state.answer = finalAnswer(state);
+  } else if (state.checked.has(option.label)) {
+    state.checked.delete(option.label);
+  } else {
+    state.checked.add(option.label);
+  }
+}
+
+function openFreeform(state: QuestionnaireState, target: QuestionnaireFreeformRow): void {
+  state.editor = { kind: "freeform", target, draft: state.freeformDraft };
+}
+
+function finalAnswer(state: QuestionnaireState): AskAnswer {
+  const selections = state.rows.flatMap((row) => {
+    if (row.kind !== "option" || !state.checked.has(row.option.label)) return [];
+    const comment = state.comments.get(row.option.label);
+    return [{
+      label: row.option.label,
+      ...(row.option.description === undefined ? {} : { description: row.option.description }),
+      ...(comment ? { comment } : {}),
+    }];
+  });
+  const freeform = state.config.allowMultiple && !state.freeformChecked ? "" : state.freeformDraft.trim();
+  return {
+    selections,
+    ...(freeform ? { freeform } : {}),
+  };
+}
+
+function wrapRow(row: number, rowCount: number): number {
+  return ((row % rowCount) + rowCount) % rowCount;
+}
+
+function clone(state: QuestionnaireState): QuestionnaireState {
+  return {
+    ...state,
+    checked: new Set(state.checked),
+    comments: new Map(state.comments),
+  };
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+import type { Static } from "typebox";
+
+import type {
+  AskAnswerSchema,
+  AskAnsweredDetailsSchema,
+  AskOptionSchema,
+  AskParamsSchema,
+  AskReplayDetailsSchema,
+  AskSelectionSchema,
+} from "./schema.js";
+
+export type AskOption = Static<typeof AskOptionSchema>;
+export type AskParams = Static<typeof AskParamsSchema>;
+export type AskSelection = Static<typeof AskSelectionSchema>;
+export type AskAnswer = Static<typeof AskAnswerSchema>;
+export type AskReplayDetails = Static<typeof AskReplayDetailsSchema>;
+export type AskAnsweredDetails = Static<typeof AskAnsweredDetailsSchema>;
+
+export type ValidatedAskParams = Omit<AskParams, "allowMultiple" | "allowFreeform"> & {
+  allowMultiple: boolean;
+  allowFreeform: boolean;
+};
+
+export type AskToolDetails =
+  | AskAnsweredDetails
+  | { status: "unanswered"; question: string }
+  | { status: "cancelled"; question: string }
+  | { status: "ui_unavailable"; question: string };
+
+export type AskResponse = {
+  content: Array<{ type: "text"; text: string }>;
+  details: AskToolDetails;
+};

package/src/validation.ts

@@ -0,0 +1,48 @@
+import type { AskOption, AskParams, ValidatedAskParams } from "./types.js";
+
+export function validateAskParams(params: AskParams): ValidatedAskParams {
+  const question = params.question.trim();
+  if (!question) throw new Error("Ask question must not be empty.");
+
+  const context = trimOptional(params.context);
+  const options = params.options.map(normalizeOption);
+  const labels = new Set<string>();
+  for (const option of options) {
+    if (labels.has(option.label)) throw new Error(`Ask options contain duplicate label: ${option.label}.`);
+    labels.add(option.label);
+  }
+
+  const allowFreeform = params.allowFreeform ?? true;
+  if (options.length === 0) throw new Error("Ask needs at least one option.");
+
+  return {
+    question,
+    ...(context === undefined ? {} : { context }),
+    options,
+    allowMultiple: params.allowMultiple ?? false,
+    allowFreeform,
+    ...(params.timeout === undefined ? {} : { timeout: params.timeout }),
+  };
+}
+
+function normalizeOption(option: AskOption): AskOption {
+  const label = option.label.trim();
+  if (!label) throw new Error("Ask option label must not be empty.");
+  const description = trimOptional(option.description);
+  const preview = preserveOptional(option.preview);
+  return {
+    label,
+    ...(description === undefined ? {} : { description }),
+    ...(preview === undefined ? {} : { preview }),
+  };
+}
+
+function trimOptional(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function preserveOptional(value: string | undefined): string | undefined {
+  return value?.trim() ? value : undefined;
+}