@terreno/blocks 57.10.1

package/dist/asks/schema.js

@@ -0,0 +1,864 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askAllowsDecline = exports.askOutputSchemas = exports.askInputSchemaFor = exports.askKindsForSurface = exports.isCompactAskKind = exports.compactAskInputSchemas = exports.askInputSchemas = exports.filesAskResponseSchema = exports.formAskResponseSchema = exports.markdownAskResponseSchema = exports.markdownAnswerSchema = exports.confirmAskResponseSchema = exports.confirmAnswerSchema = exports.choiceAskResponseSchema = exports.askResponseSchema = exports.askCancelResponseSchema = exports.askDeclineResponseSchema = exports.askAcceptResponseSchema = exports.choiceAnswerSchema = exports.filesAnswerSchema = exports.askFileRefSchema = exports.filesAskInputSchema = exports.filesCountBounds = exports.formAnswerSchema = exports.formAnswerEnvelopeSchema = exports.formAskInputSchema = exports.formFieldSchema = exports.FORM_FIELD_TYPES = exports.markdownAskInputSchema = exports.markdownLengthBounds = exports.confirmAskInputSchema = exports.confirmButtonLabels = exports.compactChoiceAskInputSchema = exports.choiceAskInputSchema = exports.visibleLabel = exports.choiceSelectionBounds = exports.CHOICE_SELECT_MODES = exports.choiceOptionSchema = exports.ASK_CANCEL_REASONS = exports.COMPACT_ASK_KINDS = exports.ASK_SURFACES = exports.ASK_KINDS = void 0;
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+const files_1 = require("./files");
+const formValues_1 = require("./formValues");
+const limits_1 = require("./limits");
+/** Ask kinds in the catalog. Each kind is offered to the model as the tool `ask_<kind>`. */
+exports.ASK_KINDS = ["choice", "confirm", "markdown", "form", "files"];
+/**
+ * Where the user answers. `compact` is a small screen, such as a watch: the model is offered only
+ * asks whose simple card shows every option, so the user never has to continue on a phone.
+ */
+exports.ASK_SURFACES = ["full", "compact"];
+/** Ask kinds the compact surface offers, each with a narrowed input schema. */
+exports.COMPACT_ASK_KINDS = ["choice", "confirm"];
+/** Reasons the server records when it answers an ask with `cancel` on the user's behalf. */
+exports.ASK_CANCEL_REASONS = {
+    oneAskAtATime: "one_ask_at_a_time",
+    userSentMessage: "user_sent_message",
+};
+const visibleText = (maxLength) => zod_1.z
+    .string()
+    .min(1)
+    .max(maxLength)
+    .refine((value) => value.length === 0 || value.trim().length > 0, {
+    message: "Must contain visible text, not only whitespace.",
+    params: { askCode: "TOO_SHORT" },
+});
+const sharedAskFields = {
+    allowDecline: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Show a Skip button so the user can decline to answer. Defaults to true."),
+    prompt: visibleText(limits_1.ASK_LIMITS.promptMaxLength).describe(`The question for the user, in plain text: no markdown and no links. 1-${limits_1.ASK_LIMITS.promptMaxLength} characters.`),
+    submitLabel: visibleText(limits_1.ASK_LIMITS.submitLabelMaxLength)
+        .optional()
+        .describe(`Label for the submit button, at most ${limits_1.ASK_LIMITS.submitLabelMaxLength} characters. Defaults to "Submit".`),
+    title: visibleText(limits_1.ASK_LIMITS.titleMaxLength)
+        .optional()
+        .describe(`A short heading above the question, at most ${limits_1.ASK_LIMITS.titleMaxLength} characters.`),
+};
+const choiceOption = (labelMaxLength) => zod_1.z
+    .object({
+    description: visibleText(limits_1.ASK_LIMITS.choice.optionDescriptionMaxLength)
+        .optional()
+        .describe(`One line under the label, at most ${limits_1.ASK_LIMITS.choice.optionDescriptionMaxLength} characters.`),
+    id: zod_1.z
+        .string()
+        .regex(limits_1.ASK_LIMITS.choice.optionIdPattern)
+        .describe(`Stable id returned in the answer: 1-${limits_1.ASK_LIMITS.choice.optionIdMaxLength} lowercase letters, digits, "_", or "-", starting with a letter or digit. Unique within the ask.`),
+    label: visibleText(labelMaxLength).describe(`What the user sees, at most ${labelMaxLength} characters.`),
+})
+    .strict();
+exports.choiceOptionSchema = choiceOption(limits_1.ASK_LIMITS.choice.optionLabelMaxLength);
+/** How many options a `choice` lets the user pick. */
+exports.CHOICE_SELECT_MODES = ["one", "many"];
+/**
+ * How many choices an answer to a `choice` must make, counting a typed Other answer as one.
+ * `select: "one"` is always exactly one. `select: "many"` defaults to at least 1 and at most every
+ * choice the ask offers: each option, plus Other when `allowOther` is true.
+ */
+const choiceSelectionBounds = (input) => {
+    if (input.select === "one") {
+        return { max: 1, min: 1 };
+    }
+    const choiceCount = input.options.length + (input.allowOther === true ? 1 : 0);
+    return { max: input.maxSelected ?? choiceCount, min: input.minSelected ?? 1 };
+};
+exports.choiceSelectionBounds = choiceSelectionBounds;
+const pluralOptions = (count) => (count === 1 ? "1 choice" : `${count} choices`);
+const checkDuplicateIds = ({ ctx, fix, ids, message, segments, }) => {
+    const firstIndexById = new Map();
+    ids.forEach((id, index) => {
+        const firstIndex = firstIndexById.get(id);
+        if (firstIndex === undefined) {
+            firstIndexById.set(id, index);
+            return;
+        }
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "DUPLICATE_ID",
+            fix,
+            message: message(id, firstIndex),
+            segments: segments(index),
+        }));
+    });
+    return firstIndexById;
+};
+/** `select: "one"` picks exactly one option; count bounds and Other belong to `select: "many"`. */
+const checkSelectOne = (input, ctx) => {
+    for (const field of ["minSelected", "maxSelected"]) {
+        const value = input[field];
+        if (value === undefined || value === 1) {
+            continue;
+        }
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "RANGE_INVALID",
+            fix: `Remove ${field}, or use select "many".`,
+            message: `select "one" picks exactly one option, so ${field} must be 1, not ${value}.`,
+            segments: [field],
+        }));
+    }
+    if (input.allowOther === true) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "OTHER_NOT_ALLOWED",
+            fix: 'Use select "many" (with maxSelected 1 for a single pick), or remove allowOther.',
+            message: 'allowOther needs select "many".',
+            segments: ["allowOther"],
+        }));
+    }
+    const defaults = input.default ?? [];
+    if (defaults.length > 1) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "SELECTION_COUNT",
+            fix: "Keep one option id in default, or remove default.",
+            message: `default lists ${defaults.length} option ids, but select "one" allows one.`,
+            segments: ["default"],
+        }));
+    }
+};
+const checkSelectMany = (input, ctx) => {
+    const choiceCount = input.options.length + (input.allowOther === true ? 1 : 0);
+    const { max, min } = (0, exports.choiceSelectionBounds)(input);
+    if (input.maxSelected !== undefined && input.maxSelected > choiceCount) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "RANGE_INVALID",
+            fix: `Set maxSelected to ${choiceCount} or fewer, or add options.`,
+            message: `maxSelected is ${input.maxSelected}, but the ask offers ${pluralOptions(choiceCount)}.`,
+            segments: ["maxSelected"],
+        }));
+    }
+    if (min > Math.min(max, choiceCount)) {
+        const isMaxSelectedBinding = input.maxSelected !== undefined && input.maxSelected <= choiceCount;
+        const limit = isMaxSelectedBinding
+            ? `maxSelected (${max})`
+            : `the ${pluralOptions(choiceCount)} the ask offers`;
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "RANGE_INVALID",
+            fix: "Lower minSelected, or raise maxSelected and add options.",
+            message: `minSelected (${min}) is more than ${limit}.`,
+            segments: ["minSelected"],
+        }));
+    }
+    const defaults = input.default ?? [];
+    if (defaults.length > max) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "SELECTION_COUNT",
+            fix: `Keep at most ${max} option ids in default.`,
+            message: `default lists ${defaults.length} option ids, but the ask allows at most ${max}.`,
+            segments: ["default"],
+        }));
+    }
+    checkDuplicateIds({
+        ctx,
+        fix: "List each option id in default once.",
+        ids: defaults,
+        message: (id, firstIndex) => `Default ${(0, errors_1.quoteValue)(id)} is already listed at ${(0, errors_1.formatAskPath)(["default", firstIndex])}.`,
+        segments: (index) => ["default", index],
+    });
+};
+const checkChoiceInput = (input, ctx) => {
+    const firstIndexById = checkDuplicateIds({
+        ctx,
+        fix: "Give every option a unique id.",
+        ids: input.options.map((option) => option.id),
+        message: (id, firstIndex) => `Option id ${(0, errors_1.quoteValue)(id)} is already used by ${(0, errors_1.formatAskPath)(["options", firstIndex])}.`,
+        segments: (index) => ["options", index, "id"],
+    });
+    if (input.select === "many") {
+        checkSelectMany(input, ctx);
+    }
+    else {
+        checkSelectOne(input, ctx);
+    }
+    if (input.otherLabel !== undefined && input.allowOther !== true) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "OTHER_NOT_ALLOWED",
+            fix: "Set allowOther to true, or remove otherLabel.",
+            message: "otherLabel is set, but allowOther is not true.",
+            segments: ["otherLabel"],
+        }));
+    }
+    const defaults = input.default ?? [];
+    defaults.forEach((id, index) => {
+        if (firstIndexById.has(id)) {
+            return;
+        }
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "DEFAULT_NOT_IN_OPTIONS",
+            fix: "Use an id from options, or remove it from default.",
+            message: `Default ${(0, errors_1.quoteValue)(id)} is not the id of any option.`,
+            segments: ["default", index],
+        }));
+    });
+};
+/**
+ * A compact ask shows each option as a button with its label uncut, so two options with the same
+ * label would be two buttons the user cannot tell apart. Zod counts a label's length in code points,
+ * but a simple card cuts labels by UTF-16 units, so a label with emoji can fit Zod's limit and still
+ * be cut on its button.
+ */
+const checkButtonLabelLength = ({ ctx, label, segments, }) => {
+    const { buttonLabelMaxLength } = limits_1.ASK_LIMITS.simpleCard;
+    if (label.length <= buttonLabelMaxLength) {
+        return;
+    }
+    const path = (0, errors_1.formatAskPath)(segments);
+    ctx.addIssue((0, errors_1.askIssue)({
+        code: "TOO_LONG",
+        fix: `Shorten ${path} to ${buttonLabelMaxLength} characters or fewer, or use fewer emoji.`,
+        message: `${path} is longer than ${buttonLabelMaxLength} characters, counting each emoji as 2 or more.`,
+        segments,
+    }));
+};
+/**
+ * A label as its button shows it. Spaces at either end don't show, so "Go " and "Go" look the same
+ * and are compared, and put on simple card buttons, without them.
+ */
+const visibleLabel = (label) => label.trim();
+exports.visibleLabel = visibleLabel;
+/** Says why two labels that differ only in spaces at either end count as the same. */
+const spacesNote = (label, otherLabel) => label === otherLabel ? "" : ", ignoring spaces at either end";
+const checkCompactChoiceInput = (input, ctx) => {
+    checkChoiceInput(input, ctx);
+    const firstIndexByLabel = new Map();
+    input.options.forEach((option, index) => {
+        checkButtonLabelLength({ ctx, label: option.label, segments: ["options", index, "label"] });
+        const firstIndex = firstIndexByLabel.get((0, exports.visibleLabel)(option.label));
+        if (firstIndex === undefined) {
+            firstIndexByLabel.set((0, exports.visibleLabel)(option.label), index);
+            return;
+        }
+        const note = spacesNote(option.label, input.options[firstIndex].label);
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "DUPLICATE_LABEL",
+            fix: "Give every option a different label.",
+            message: `Option label ${(0, errors_1.quoteValue)(option.label)} is already used by ${(0, errors_1.formatAskPath)(["options", firstIndex])}${note}.`,
+            segments: ["options", index, "label"],
+        }));
+    });
+};
+const choiceBaseFields = ({ defaultDescription, labelMaxLength, optionsMax, }) => ({
+    ...sharedAskFields,
+    default: zod_1.z.array(zod_1.z.string()).max(optionsMax).optional().describe(defaultDescription),
+    options: zod_1.z
+        .array(choiceOption(labelMaxLength))
+        .min(limits_1.ASK_LIMITS.choice.optionsMin)
+        .max(optionsMax)
+        .describe(`The options, in display order: ${limits_1.ASK_LIMITS.choice.optionsMin}-${optionsMax} items.`),
+});
+/** Input for `ask_choice`: pick one option, or several with `select: "many"`, from a list. */
+exports.choiceAskInputSchema = zod_1.z
+    .object({
+    ...choiceBaseFields({
+        defaultDescription: 'Option ids to preselect. With select "one", at most one id; with select "many", at most maxSelected ids.',
+        labelMaxLength: limits_1.ASK_LIMITS.choice.optionLabelMaxLength,
+        optionsMax: limits_1.ASK_LIMITS.choice.optionsMax,
+    }),
+    allowOther: zod_1.z
+        .boolean()
+        .optional()
+        .describe(`With select "many": add a free-text Other entry. The answer's other holds its text, at most ${limits_1.ASK_LIMITS.choice.otherMaxLength} characters, and counts as one choice.`),
+    maxSelected: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('With select "many": the most choices the user may make. Defaults to every choice: the option count, plus 1 with allowOther.'),
+    minSelected: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('With select "many": the fewest choices the user must make. Defaults to 1. 0 lets the user submit no choice.'),
+    otherLabel: visibleText(limits_1.ASK_LIMITS.choice.optionLabelMaxLength)
+        .optional()
+        .describe(`Label for the Other entry when allowOther is true, at most ${limits_1.ASK_LIMITS.choice.optionLabelMaxLength} characters. Defaults to "Other".`),
+    select: zod_1.z
+        .enum(exports.CHOICE_SELECT_MODES)
+        .describe('How many options the user picks: "one", or "many" (checkboxes).'),
+})
+    .strict()
+    .superRefine(checkChoiceInput);
+/**
+ * Input for `ask_choice` on the compact surface: pick one option by tapping its button, so the
+ * card never hands off. At most 3 options, labels of at most 20 characters (each emoji counts as 2
+ * or more), and no two labels alike. `select: "many"` and Other are not offered.
+ */
+exports.compactChoiceAskInputSchema = zod_1.z
+    .object({
+    ...choiceBaseFields({
+        defaultDescription: 'Option ids to preselect. With select "one", at most one id.',
+        labelMaxLength: limits_1.ASK_LIMITS.simpleCard.buttonLabelMaxLength,
+        optionsMax: limits_1.ASK_LIMITS.simpleCard.buttonsMax,
+    }),
+    select: zod_1.z.literal("one").describe('How many options the user picks. Only "one" is supported.'),
+})
+    .strict()
+    .superRefine(checkCompactChoiceInput);
+/** The button labels a `confirm` ask shows when it does not name its own. */
+const CONFIRM_DEFAULT_LABELS = { confirm: "Confirm", deny: "Cancel" };
+/** The labels of a `confirm` ask's approve and deny buttons, with the defaults filled in. */
+const confirmButtonLabels = (input) => ({
+    confirm: input.confirmLabel ?? CONFIRM_DEFAULT_LABELS.confirm,
+    deny: input.denyLabel ?? CONFIRM_DEFAULT_LABELS.deny,
+});
+exports.confirmButtonLabels = confirmButtonLabels;
+/**
+ * Both labels fit a simple card button uncut, so every surface shows the same words, and they
+ * differ, so the user can tell approve from deny.
+ */
+const checkConfirmInput = (input, ctx) => {
+    for (const field of ["confirmLabel", "denyLabel"]) {
+        const label = input[field];
+        if (label !== undefined) {
+            checkButtonLabelLength({ ctx, label, segments: [field] });
+        }
+    }
+    const { confirm, deny } = (0, exports.confirmButtonLabels)(input);
+    if ((0, exports.visibleLabel)(confirm) !== (0, exports.visibleLabel)(deny)) {
+        return;
+    }
+    const note = spacesNote(confirm, deny);
+    if (input.denyLabel === undefined) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "DUPLICATE_LABEL",
+            fix: `Give confirmLabel a label other than ${(0, errors_1.quoteValue)(deny)}, the deny button's label.`,
+            message: `confirmLabel ${(0, errors_1.quoteValue)(confirm)} is the same as the deny button's label${note}.`,
+            segments: ["confirmLabel"],
+        }));
+        return;
+    }
+    ctx.addIssue((0, errors_1.askIssue)({
+        code: "DUPLICATE_LABEL",
+        fix: `Give denyLabel a label other than ${(0, errors_1.quoteValue)(confirm)}, the approve button's label.`,
+        message: `denyLabel ${(0, errors_1.quoteValue)(deny)} is the same as the approve button's label${note}.`,
+        segments: ["denyLabel"],
+    }));
+};
+const confirmLabelField = (button, fallback) => visibleText(limits_1.ASK_LIMITS.confirm.labelMaxLength)
+    .optional()
+    .describe(`Label for the ${button} button, at most ${limits_1.ASK_LIMITS.confirm.labelMaxLength} characters. Defaults to "${fallback}".`);
+/**
+ * Input for `ask_confirm`: approve or deny one action. It has no Submit, so no `submitLabel`, and
+ * `allowDecline` defaults to false because deny is already the negative answer.
+ */
+exports.confirmAskInputSchema = zod_1.z
+    .object({
+    allowDecline: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Show a Skip button as well as deny. Defaults to false, because deny is the negative answer."),
+    confirmLabel: confirmLabelField("approve", CONFIRM_DEFAULT_LABELS.confirm),
+    denyLabel: confirmLabelField("deny", CONFIRM_DEFAULT_LABELS.deny),
+    destructive: zod_1.z
+        .boolean()
+        .optional()
+        .describe("True when the action deletes data or cannot be undone. The approve button then shows as destructive. Defaults to false."),
+    prompt: sharedAskFields.prompt,
+    title: sharedAskFields.title,
+})
+    .strict()
+    .superRefine(checkConfirmInput);
+/**
+ * How long an answer to a `markdown` ask may be. `max` counts UTF-16 code units (the `length` of a
+ * JavaScript string, so most emoji count as 2 or more) and defaults to the 20,000 cap. `min`
+ * counts the text without spaces at either end and defaults to 0.
+ */
+const markdownLengthBounds = (input) => ({
+    max: input.maxLength ?? limits_1.ASK_LIMITS.markdown.maxLength,
+    min: input.minLength ?? 0,
+});
+exports.markdownLengthBounds = markdownLengthBounds;
+/**
+ * Checks a draft's length against the cap in UTF-16 code units. Zod counts code points, so a draft
+ * with emoji could otherwise pass Zod and still be longer than a text field lets the user keep.
+ */
+const checkMarkdownCap = ({ ctx, segments, value, }) => {
+    const cap = limits_1.ASK_LIMITS.markdown.maxLength;
+    if (value.length <= cap) {
+        return;
+    }
+    const path = (0, errors_1.formatAskPath)(segments);
+    ctx.addIssue((0, errors_1.askIssue)({
+        code: "TOO_LONG",
+        fix: `Shorten ${path} to ${cap} characters or fewer.`,
+        message: `${path} is longer than ${cap} characters.`,
+        segments,
+    }));
+};
+/**
+ * `minLength` must not be above `maxLength`, or no answer could be sent. An `initial` draft outside
+ * the bounds is valid: the user edits it to fit, and the simple card offers no Approve draft.
+ */
+const checkMarkdownInput = (input, ctx) => {
+    if (input.initial !== undefined) {
+        checkMarkdownCap({ ctx, segments: ["initial"], value: input.initial });
+    }
+    const { max, min } = (0, exports.markdownLengthBounds)(input);
+    if (min <= max) {
+        return;
+    }
+    const limit = input.maxLength === undefined ? `the ${max}-character cap` : `maxLength (${max})`;
+    ctx.addIssue((0, errors_1.askIssue)({
+        code: "RANGE_INVALID",
+        fix: "Lower minLength, or raise maxLength.",
+        message: `minLength (${min}) is more than ${limit}.`,
+        segments: ["minLength"],
+    }));
+};
+/** Input for `ask_markdown`: the user edits a markdown draft and sends it back. */
+exports.markdownAskInputSchema = zod_1.z
+    .object({
+    ...sharedAskFields,
+    initial: zod_1.z
+        .string()
+        .max(limits_1.ASK_LIMITS.markdown.maxLength)
+        .optional()
+        .describe(`The draft the user starts from, in markdown, at most ${limits_1.ASK_LIMITS.markdown.maxLength} characters. Defaults to empty.`),
+    maxLength: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(limits_1.ASK_LIMITS.markdown.maxLength)
+        .optional()
+        .describe(`The longest answer the user may send, in characters. Defaults to ${limits_1.ASK_LIMITS.markdown.maxLength}, the most allowed.`),
+    minLength: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .max(limits_1.ASK_LIMITS.markdown.maxLength)
+        .optional()
+        .describe("The shortest answer the user may send, in characters, not counting spaces at either end. Defaults to 0."),
+    placeholder: visibleText(limits_1.ASK_LIMITS.markdown.placeholderMaxLength)
+        .optional()
+        .describe(`Hint text shown while the editor is empty, at most ${limits_1.ASK_LIMITS.markdown.placeholderMaxLength} characters.`),
+})
+    .strict()
+    .superRefine(checkMarkdownInput);
+/** The field types a `form` offers. Every field is flat: no nesting and no conditional fields. */
+exports.FORM_FIELD_TYPES = [
+    "text",
+    "textarea",
+    "email",
+    "url",
+    "phone",
+    "number",
+    "date",
+    "time",
+    "datetime",
+    "boolean",
+    "select",
+    "multiselect",
+];
+const formFieldBase = (type) => ({
+    helperText: visibleText(limits_1.ASK_LIMITS.form.helperTextMaxLength)
+        .optional()
+        .describe(`One line under the field, at most ${limits_1.ASK_LIMITS.form.helperTextMaxLength} characters.`),
+    id: zod_1.z
+        .string()
+        .regex(limits_1.ASK_LIMITS.choice.optionIdPattern)
+        .describe(`The key of this field's value in the answer: 1-${limits_1.ASK_LIMITS.choice.optionIdMaxLength} lowercase letters, digits, "_", or "-", starting with a letter or digit. Unique within the form.`),
+    label: visibleText(limits_1.ASK_LIMITS.form.labelMaxLength).describe(`What the user sees, at most ${limits_1.ASK_LIMITS.form.labelMaxLength} characters.`),
+    required: zod_1.z
+        .boolean()
+        .optional()
+        .describe("True when the answer must hold a non-blank value for this field. Defaults to false."),
+    type: zod_1.z.literal(type),
+});
+const formTextField = (type, cap) => zod_1.z
+    .object({
+    ...formFieldBase(type),
+    default: zod_1.z.string().optional().describe("The text the field starts with."),
+    maxLength: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(cap)
+        .optional()
+        .describe(`The most characters the value may have. Defaults to ${cap}, the most allowed.`),
+    minLength: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .max(cap)
+        .optional()
+        .describe("The fewest characters a non-blank value may have, not counting spaces at either end. Defaults to 0."),
+})
+    .strict();
+const formStringField = (type, example) => zod_1.z
+    .object({
+    ...formFieldBase(type),
+    default: zod_1.z
+        .string()
+        .optional()
+        .describe(`The value the field starts with, such as ${example}.`),
+})
+    .strict();
+const formDateField = (type, format) => zod_1.z
+    .object({
+    ...formFieldBase(type),
+    default: zod_1.z.string().optional().describe(`The value the field starts with, as ${format}.`),
+})
+    .strict();
+const formOption = zod_1.z
+    .object({
+    id: exports.choiceOptionSchema.shape.id,
+    label: exports.choiceOptionSchema.shape.label,
+})
+    .strict();
+const formOptions = formOption
+    .array()
+    .min(limits_1.ASK_LIMITS.choice.optionsMin)
+    .max(limits_1.ASK_LIMITS.choice.optionsMax)
+    .describe(`The options, in display order: ${limits_1.ASK_LIMITS.choice.optionsMin}-${limits_1.ASK_LIMITS.choice.optionsMax} items, each {id, label}.`);
+exports.formFieldSchema = zod_1.z.discriminatedUnion("type", [
+    formTextField("text", limits_1.ASK_LIMITS.form.textMaxLength),
+    formTextField("textarea", limits_1.ASK_LIMITS.form.textareaMaxLength),
+    formStringField("email", '"ada@example.com"'),
+    formStringField("url", '"https://example.com"'),
+    formStringField("phone", '"+1 415 555 2671"'),
+    zod_1.z
+        .object({
+        ...formFieldBase("number"),
+        default: zod_1.z.number().optional().describe("The number the field starts with."),
+        integer: zod_1.z.boolean().optional().describe("True to accept whole numbers only."),
+        max: zod_1.z.number().optional().describe("The largest value allowed."),
+        min: zod_1.z.number().optional().describe("The smallest value allowed."),
+    })
+        .strict(),
+    formDateField("date", 'YYYY-MM-DD, such as "2026-10-01"'),
+    formDateField("time", '24-hour HH:mm, such as "09:30"'),
+    formDateField("datetime", 'an ISO 8601 date and time with Z or an offset, seconds optional, such as "2026-10-01T09:30Z"'),
+    zod_1.z
+        .object({
+        ...formFieldBase("boolean"),
+        default: zod_1.z.boolean().optional().describe("Whether the checkbox starts checked."),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...formFieldBase("select"),
+        default: zod_1.z.string().optional().describe("The option id selected at first."),
+        options: formOptions,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...formFieldBase("multiselect"),
+        default: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("The option ids selected at first, each listed once."),
+        options: formOptions,
+    })
+        .strict(),
+]);
+/**
+ * Field ids are unique, length and number bounds have their minimum at or below their maximum,
+ * option ids are unique within a field, and every default is a value its field accepts.
+ */
+const checkFormInput = (input, ctx) => {
+    checkDuplicateIds({
+        ctx,
+        fix: "Give every field a unique id.",
+        ids: input.fields.map((field) => field.id),
+        message: (id, firstIndex) => `Field id ${(0, errors_1.quoteValue)(id)} is already used by ${(0, errors_1.formatAskPath)(["fields", firstIndex])}.`,
+        segments: (index) => ["fields", index, "id"],
+    });
+    input.fields.forEach((field, index) => {
+        if ((field.type === "text" || field.type === "textarea") && field.minLength !== undefined) {
+            const max = (0, formValues_1.formTextMaxLength)(field);
+            if (field.minLength > max) {
+                ctx.addIssue((0, errors_1.askIssue)({
+                    code: "RANGE_INVALID",
+                    fix: "Lower minLength, or raise maxLength.",
+                    message: `minLength (${field.minLength}) is more than maxLength (${max}).`,
+                    segments: ["fields", index, "minLength"],
+                }));
+            }
+        }
+        if (field.type === "number" &&
+            field.min !== undefined &&
+            field.max !== undefined &&
+            field.min > field.max) {
+            ctx.addIssue((0, errors_1.askIssue)({
+                code: "RANGE_INVALID",
+                fix: "Lower min, or raise max.",
+                message: `min (${field.min}) is more than max (${field.max}).`,
+                segments: ["fields", index, "min"],
+            }));
+        }
+        if (field.type === "select" || field.type === "multiselect") {
+            checkDuplicateIds({
+                ctx,
+                fix: "Give every option of the field a unique id.",
+                ids: field.options.map((option) => option.id),
+                message: (id, firstIndex) => `Option id ${(0, errors_1.quoteValue)(id)} is already used by ${(0, errors_1.formatAskPath)(["fields", index, "options", firstIndex])}.`,
+                segments: (optionIndex) => ["fields", index, "options", optionIndex, "id"],
+            });
+        }
+        if (field.default === undefined) {
+            return;
+        }
+        for (const draft of (0, formValues_1.checkFormValue)({
+            field,
+            isDefault: true,
+            segments: ["fields", index, "default"],
+            value: field.default,
+        })) {
+            ctx.addIssue((0, errors_1.askIssue)(draft));
+        }
+    });
+};
+/** Input for `ask_form`: a few flat fields the user fills in and submits at once. */
+exports.formAskInputSchema = zod_1.z
+    .object({
+    ...sharedAskFields,
+    fields: zod_1.z
+        .array(exports.formFieldSchema)
+        .min(limits_1.ASK_LIMITS.form.fieldsMin)
+        .max(limits_1.ASK_LIMITS.form.fieldsMax)
+        .describe(`The fields, in display order: ${limits_1.ASK_LIMITS.form.fieldsMin}-${limits_1.ASK_LIMITS.form.fieldsMax} items. Each has a type (${exports.FORM_FIELD_TYPES.join(", ")}).`),
+})
+    .strict()
+    .superRefine(checkFormInput);
+/** The `content` of an accepted answer from any client, before its values meet their fields. */
+exports.formAnswerEnvelopeSchema = zod_1.z
+    .object({ values: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()) })
+    .strict();
+/**
+ * The `content` of an accepted `form` answer: one value per answered field, keyed by field id.
+ * Unanswered optional fields are left out.
+ */
+exports.formAnswerSchema = zod_1.z
+    .object({
+    values: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.array(zod_1.z.string())])),
+})
+    .strict();
+/** How many files an answer to a `files` ask must carry: 1 to 10 unless the ask narrows it. */
+const filesCountBounds = (input) => ({
+    max: input.maxFiles ?? limits_1.ASK_LIMITS.files.maxFiles,
+    min: input.minFiles ?? limits_1.ASK_LIMITS.files.minFiles,
+});
+exports.filesCountBounds = filesCountBounds;
+const checkFilesInput = (input, ctx) => {
+    checkDuplicateIds({
+        ctx,
+        fix: "List each accept value once.",
+        ids: input.accept,
+        message: (value, firstIndex) => `${(0, errors_1.quoteValue)(value)} is already listed at ${(0, errors_1.formatAskPath)(["accept", firstIndex])}.`,
+        segments: (index) => ["accept", index],
+    });
+    const { max, min } = (0, exports.filesCountBounds)(input);
+    if (min <= max) {
+        return;
+    }
+    const limit = input.maxFiles === undefined ? `the ${max}-file cap` : `maxFiles (${input.maxFiles})`;
+    ctx.addIssue((0, errors_1.askIssue)({
+        code: "RANGE_INVALID",
+        fix: "Lower minFiles, or raise maxFiles.",
+        message: `minFiles (${min}) is more than ${limit}.`,
+        segments: ["minFiles"],
+    }));
+};
+const fileCountField = (description) => zod_1.z
+    .number()
+    .int()
+    .min(limits_1.ASK_LIMITS.files.minFiles)
+    .max(limits_1.ASK_LIMITS.files.maxFiles)
+    .optional()
+    .describe(description);
+/** Input for `ask_files`: the user uploads one or more images or documents. */
+exports.filesAskInputSchema = zod_1.z
+    .object({
+    ...sharedAskFields,
+    accept: zod_1.z
+        .array(zod_1.z.enum(files_1.ASK_FILE_ACCEPT))
+        .min(1)
+        .max(files_1.ASK_FILE_ACCEPT.length)
+        .describe('The kinds of file the user may send, each listed once: "image" (JPEG, PNG, GIF, WebP), "pdf", "text" (plain text), "csv", or "json".'),
+    maxFiles: fileCountField(`The most files the user may send: ${limits_1.ASK_LIMITS.files.minFiles}-${limits_1.ASK_LIMITS.files.maxFiles}. Defaults to ${limits_1.ASK_LIMITS.files.maxFiles}.`),
+    minFiles: fileCountField(`The fewest files the user must send: ${limits_1.ASK_LIMITS.files.minFiles}-${limits_1.ASK_LIMITS.files.maxFiles}. Defaults to ${limits_1.ASK_LIMITS.files.minFiles}.`),
+})
+    .strict()
+    .superRefine(checkFilesInput);
+/**
+ * Exactly one of `fileId` and `url` names the bytes. A `url` must be a base64 `data:` URL whose
+ * media type is the declared `mimeType`, so the server never fetches a remote URL.
+ */
+const checkFileRef = (ref, ctx) => {
+    if (ref.fileId === undefined && ref.url === undefined) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "MISSING_REQUIRED",
+            fix: 'Add "fileId" (an upload from POST /files/upload) or "url" (a base64 data: URL).',
+            message: "A file needs a fileId or a url.",
+            segments: [],
+        }));
+        return;
+    }
+    if (ref.fileId !== undefined && ref.url !== undefined) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "INVALID_FORMAT",
+            fix: "Send fileId or url, not both.",
+            message: "A file has both a fileId and a url.",
+            segments: ["url"],
+        }));
+        return;
+    }
+    if (ref.url !== undefined && (0, files_1.parseAskDataUrl)(ref.url) === undefined) {
+        ctx.addIssue((0, errors_1.askIssue)({
+            code: "INVALID_FORMAT",
+            fix: 'Send the bytes as a base64 data: URL, such as "data:image/png;base64,...".',
+            message: "url is not a base64 data: URL.",
+            segments: ["url"],
+        }));
+    }
+};
+/** One file in an accepted `files` answer: an upload (`fileId`) or inline bytes (`url`). */
+exports.askFileRefSchema = zod_1.z
+    .object({
+    fileId: zod_1.z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("The id of the user's upload from POST /files/upload."),
+    filename: visibleText(limits_1.ASK_LIMITS.files.filenameMaxLength).describe("The file's name as the user picked it."),
+    mimeType: zod_1.z.string().min(1).max(127).describe('The file\'s MIME type, such as "image/png".'),
+    size: zod_1.z.number().int().min(0).describe("The file's size in bytes."),
+    url: zod_1.z.string().optional().describe("The file's bytes as a base64 data: URL."),
+})
+    .strict()
+    .superRefine(checkFileRef);
+/** The `content` of an accepted `files` answer: the files the user sent, in the order they chose. */
+exports.filesAnswerSchema = zod_1.z.object({ files: zod_1.z.array(exports.askFileRefSchema) }).strict();
+/** The `content` of an accepted `choice` answer. */
+exports.choiceAnswerSchema = zod_1.z
+    .object({
+    other: visibleText(limits_1.ASK_LIMITS.choice.otherMaxLength).optional(),
+    selected: zod_1.z.array(zod_1.z.string()).max(limits_1.ASK_LIMITS.choice.optionsMax),
+})
+    .strict();
+exports.askAcceptResponseSchema = zod_1.z
+    .object({
+    action: zod_1.z.literal("accept"),
+    content: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+})
+    .strict();
+exports.askDeclineResponseSchema = zod_1.z.object({ action: zod_1.z.literal("decline") }).strict();
+exports.askCancelResponseSchema = zod_1.z
+    .object({
+    action: zod_1.z.literal("cancel"),
+    reason: visibleText(limits_1.ASK_LIMITS.cancelReasonMaxLength).optional(),
+})
+    .strict();
+/**
+ * The answer envelope for every ask (the MCP elicitation shape). `accept` carries the kind's
+ * answer in `content`; `decline` means the user pressed Skip; `cancel` means the ask was dropped.
+ */
+exports.askResponseSchema = zod_1.z.discriminatedUnion("action", [
+    exports.askAcceptResponseSchema,
+    exports.askDeclineResponseSchema,
+    exports.askCancelResponseSchema,
+]);
+/** The answer envelope for `ask_choice`, with `content` typed. Used as the tool's output schema. */
+exports.choiceAskResponseSchema = zod_1.z.discriminatedUnion("action", [
+    zod_1.z.object({ action: zod_1.z.literal("accept"), content: exports.choiceAnswerSchema }).strict(),
+    exports.askDeclineResponseSchema,
+    exports.askCancelResponseSchema,
+]);
+/** The `content` of an accepted `confirm` answer: true approves the action, false denies it. */
+exports.confirmAnswerSchema = zod_1.z.object({ confirmed: zod_1.z.boolean() }).strict();
+/** The answer envelope for `ask_confirm`, with `content` typed. Used as the tool's output schema. */
+exports.confirmAskResponseSchema = zod_1.z.discriminatedUnion("action", [
+    zod_1.z.object({ action: zod_1.z.literal("accept"), content: exports.confirmAnswerSchema }).strict(),
+    exports.askDeclineResponseSchema,
+    exports.askCancelResponseSchema,
+]);
+/**
+ * The `content` of an accepted `markdown` answer: the text the user sends back, and whether it
+ * differs from the ask's `initial` draft.
+ */
+exports.markdownAnswerSchema = zod_1.z
+    .object({
+    changed: zod_1.z.boolean(),
+    markdown: zod_1.z.string().max(limits_1.ASK_LIMITS.markdown.maxLength),
+})
+    .strict()
+    .superRefine((answer, ctx) => {
+    checkMarkdownCap({ ctx, segments: ["markdown"], value: answer.markdown });
+});
+/** The answer envelope for `ask_markdown`, with `content` typed. Used as the tool's output schema. */
+exports.markdownAskResponseSchema = zod_1.z.discriminatedUnion("action", [
+    zod_1.z.object({ action: zod_1.z.literal("accept"), content: exports.markdownAnswerSchema }).strict(),
+    exports.askDeclineResponseSchema,
+    exports.askCancelResponseSchema,
+]);
+/** The answer envelope for `ask_form`, with `content` typed. Used as the tool's output schema. */
+exports.formAskResponseSchema = zod_1.z.discriminatedUnion("action", [
+    zod_1.z.object({ action: zod_1.z.literal("accept"), content: exports.formAnswerSchema }).strict(),
+    exports.askDeclineResponseSchema,
+    exports.askCancelResponseSchema,
+]);
+/** The answer envelope for `ask_files`, with `content` typed. Used as the tool's output schema. */
+exports.filesAskResponseSchema = zod_1.z.discriminatedUnion("action", [
+    zod_1.z.object({ action: zod_1.z.literal("accept"), content: exports.filesAnswerSchema }).strict(),
+    exports.askDeclineResponseSchema,
+    exports.askCancelResponseSchema,
+]);
+/** Input schemas by kind. */
+exports.askInputSchemas = {
+    choice: exports.choiceAskInputSchema,
+    confirm: exports.confirmAskInputSchema,
+    files: exports.filesAskInputSchema,
+    form: exports.formAskInputSchema,
+    markdown: exports.markdownAskInputSchema,
+};
+/** Input schemas by kind on the compact surface. Every compact input is also a valid full input. */
+exports.compactAskInputSchemas = {
+    choice: exports.compactChoiceAskInputSchema,
+    // A confirm always fits a simple card (two buttons with labels that show uncut).
+    confirm: exports.confirmAskInputSchema,
+};
+const isCompactAskKind = (kind) => exports.COMPACT_ASK_KINDS.includes(kind);
+exports.isCompactAskKind = isCompactAskKind;
+/** The kinds a surface offers, in the given order. The compact surface drops kinds it cannot show. */
+const askKindsForSurface = ({ kinds, surface, }) => (surface === "compact" ? kinds.filter(exports.isCompactAskKind) : [...kinds]);
+exports.askKindsForSurface = askKindsForSurface;
+/**
+ * The input schema for a kind on a surface. Throws for an unknown kind or surface, and when the
+ * compact surface does not offer the kind.
+ */
+const askInputSchemaFor = ({ kind, surface = "full", }) => {
+    if (!Object.hasOwn(exports.askInputSchemas, kind)) {
+        throw new Error(`Unknown ask kind "${String(kind)}".`);
+    }
+    if (!exports.ASK_SURFACES.includes(surface)) {
+        throw new Error(`Unknown ask surface "${String(surface)}".`);
+    }
+    if (surface === "full") {
+        return exports.askInputSchemas[kind];
+    }
+    if (!(0, exports.isCompactAskKind)(kind)) {
+        throw new Error(`The compact surface does not offer ask kind "${String(kind)}".`);
+    }
+    return exports.compactAskInputSchemas[kind];
+};
+exports.askInputSchemaFor = askInputSchemaFor;
+/** Output (answer envelope) schemas by kind. */
+exports.askOutputSchemas = {
+    choice: exports.choiceAskResponseSchema,
+    confirm: exports.confirmAskResponseSchema,
+    files: exports.filesAskResponseSchema,
+    form: exports.formAskResponseSchema,
+    markdown: exports.markdownAskResponseSchema,
+};
+/**
+ * Whether the user may skip the ask. `allowDecline` defaults to true, except on `confirm`, where
+ * deny is already the negative answer.
+ */
+const askAllowsDecline = ({ input, kind }) => kind === "confirm" ? input.allowDecline === true : input.allowDecline !== false;
+exports.askAllowsDecline = askAllowsDecline;