@terreno/blocks 57.10.1

package/src/asks/prompt.ts

@@ -0,0 +1,173 @@
+import {ASK_LIMITS} from "./limits";
+import {type AskKind, type AskSurface, type CompactAskKind, isCompactAskKind} from "./schema";
+
+const CHOICE_ANSWER_EXAMPLE =
+  '- An accepted answer looks like {"action": "accept", "content": {"selected": ["<id>"]}}.';
+
+const CHOICE_DECLINE_RULE =
+  "- allowDecline: optional, default true (the user sees Skip). Set it to false only when you cannot continue without an answer.";
+
+const CHOICE_ID_RULE = `- id: 1-${ASK_LIMITS.choice.optionIdMaxLength} lowercase letters, digits, "_", or "-", starting with a letter or digit. Unique within the ask.`;
+
+const sharedRules = (): string =>
+  [
+    "Rules for every ask:",
+    `- prompt: required. Plain text with no markdown and no links, 1-${ASK_LIMITS.promptMaxLength} characters.`,
+    `- title: optional, at most ${ASK_LIMITS.titleMaxLength} characters.`,
+    "- Each ask kind below lists its other fields, including whether the user can skip it.",
+  ].join("\n");
+
+const compactSharedRules = (): string =>
+  [
+    sharedRules(),
+    `- The screen is small: it shows only the first ${ASK_LIMITS.simpleCard.textMaxLength} characters of prompt and the first ${ASK_LIMITS.simpleCard.titleMaxLength} characters of title, so keep both within those lengths.`,
+  ].join("\n");
+
+const choiceRules = (): string => {
+  const {choice, simpleCard} = ASK_LIMITS;
+  return [
+    "ask_choice: the user picks one or more options from a list you provide.",
+    '- select: "one" for exactly one option, or "many" to let the user pick several.',
+    `- options: ${choice.optionsMin}-${choice.optionsMax} items, each {id, label, description?}.`,
+    CHOICE_ID_RULE,
+    `- label: at most ${choice.optionLabelMaxLength} characters. description: optional, at most ${choice.optionDescriptionMaxLength} characters.`,
+    '- default: optional list of option ids to preselect, each listed once. With "one", at most one id; with "many", at most maxSelected ids.',
+    '- minSelected, maxSelected: optional whole numbers, "many" only. The user picks from minSelected (default 1, at least 0) to maxSelected (default: every choice) choices.',
+    `- allowOther: optional, "many" only. true adds a text field where the user types an answer of their own, up to ${choice.otherMaxLength} characters. It counts as one choice. otherLabel: optional label for that field, at most ${choice.optionLabelMaxLength} characters. For one option or Other, use "many" with maxSelected 1.`,
+    `- submitLabel: optional label for the submit button, at most ${ASK_LIMITS.submitLabelMaxLength} characters.`,
+    CHOICE_DECLINE_RULE,
+    `- Prefer select "one" with at most ${simpleCard.buttonsMax} options with labels of ${simpleCard.buttonLabelMaxLength} characters or fewer; small screens show those as buttons.`,
+    CHOICE_ANSWER_EXAMPLE,
+    '- With Other, it looks like {"action": "accept", "content": {"selected": ["<id>"], "other": "<text the user typed>"}}.',
+  ].join("\n");
+};
+
+const compactChoiceRules = (): string => {
+  const {choice, simpleCard} = ASK_LIMITS;
+  return [
+    "ask_choice: the user picks one option by tapping its button.",
+    '- select: always "one".',
+    `- options: ${choice.optionsMin}-${simpleCard.buttonsMax} items, each {id, label, description?}.`,
+    CHOICE_ID_RULE,
+    `- label: at most ${simpleCard.buttonLabelMaxLength} characters, counting each emoji as 2 or more, and no two options share a label.`,
+    `- description: optional, at most ${choice.optionDescriptionMaxLength} characters. The buttons show only labels, so put what the user needs to decide in prompt and the labels.`,
+    "- default: optional list with at most one option id to preselect.",
+    CHOICE_DECLINE_RULE,
+    CHOICE_ANSWER_EXAMPLE,
+  ].join("\n");
+};
+
+/** A confirm always fits a simple card, so the full and compact surfaces share these rules. */
+const confirmRules = (): string => {
+  const {labelMaxLength} = ASK_LIMITS.confirm;
+  return [
+    "ask_confirm: the user approves or denies one action you describe in prompt.",
+    `- confirmLabel, denyLabel: optional labels for the approve and deny buttons, at most ${labelMaxLength} characters each, counting each emoji as 2 or more, and different from each other. They default to "Confirm" and "Cancel". Name the action, such as "Delete 14 todos" and "Keep them".`,
+    "- destructive: optional, default false. Set it to true when the action deletes data or cannot be undone; the approve button then shows as destructive.",
+    "- allowDecline: optional, default false, because the deny button is the negative answer. Set it to true to show Skip as well.",
+    `- Before you call a tool that deletes data, sends something on the user's behalf, spends money, or cannot be undone, call ask_confirm and say in prompt exactly what will happen. Make the call only after {"confirmed": true}.`,
+    '- An accepted answer looks like {"action": "accept", "content": {"confirmed": true}}. {"confirmed": false} means the user said no, so do not take the action.',
+  ].join("\n");
+};
+
+const markdownRules = (): string => {
+  const {markdown} = ASK_LIMITS;
+  return [
+    "ask_markdown: the user edits a markdown draft you write and sends it back.",
+    `- initial: optional, the draft in markdown, at most ${markdown.maxLength} characters. Put the whole draft here, not in prompt.`,
+    `- minLength, maxLength: optional whole numbers. The answer must have at least minLength (default 0) and at most maxLength (default ${markdown.maxLength}, the most allowed) characters. minLength must not be more than maxLength.`,
+    `- placeholder: optional hint shown while the editor is empty, at most ${markdown.placeholderMaxLength} characters.`,
+    `- submitLabel: optional label for the submit button, at most ${ASK_LIMITS.submitLabelMaxLength} characters.`,
+    "- allowDecline: optional, default true (the user sees Skip).",
+    '- An accepted answer looks like {"action": "accept", "content": {"markdown": "<the text>", "changed": true}}. changed is false when the user sent your draft unchanged.',
+  ].join("\n");
+};
+
+const formRules = (): string => {
+  const {choice, form} = ASK_LIMITS;
+  return [
+    "ask_form: the user fills in a few fields and submits them at once.",
+    `- fields: ${form.fieldsMin}-${form.fieldsMax} items, in display order, each {id, type, label, helperText?, required?, default?} plus the rules of its type. Fields are flat: no nesting, no conditional fields, and no password fields.`,
+    `- id: 1-${choice.optionIdMaxLength} lowercase letters, digits, "_", or "-", starting with a letter or digit. Unique within the form. It keys the field's value in the answer.`,
+    `- label: at most ${form.labelMaxLength} characters. helperText: optional, at most ${form.helperTextMaxLength} characters. required: optional, default false; true means the answer must hold a non-blank value.`,
+    `- type "text" (one line) or "textarea" (several lines): optional minLength and maxLength. maxLength is at most ${form.textMaxLength} for text and ${form.textareaMaxLength} for textarea. The value is a string.`,
+    `- type "email", "url" (http or https), or "phone" (${form.phoneDigitsMin}-${form.phoneDigitsMax} digits): the value is a string in that format.`,
+    '- type "number": optional min, max, and integer (true for whole numbers only). The value is a number.',
+    '- type "date" (YYYY-MM-DD), "time" (24-hour HH:mm), or "datetime" (ISO 8601 with Z or an offset; seconds are optional, such as "2026-10-01T09:30Z" or "2026-10-01T09:30:00+02:00"): the value is a string in that format.',
+    '- type "boolean": a checkbox. The value is true or false.',
+    `- type "select" (pick one) or "multiselect" (pick any): options, ${choice.optionsMin}-${choice.optionsMax} items, each {id, label}. The value is an option id, or a list of option ids.`,
+    "- default: optional, a value the field accepts, filled in when the form opens.",
+    `- submitLabel: optional label for the submit button, at most ${ASK_LIMITS.submitLabelMaxLength} characters.`,
+    "- allowDecline: optional, default true (the user sees Skip).",
+    '- An accepted answer looks like {"action": "accept", "content": {"values": {"<field id>": <value>}}}. Optional fields the user left empty are left out.',
+  ].join("\n");
+};
+
+const filesRules = (): string => {
+  const {files} = ASK_LIMITS;
+  return [
+    "ask_files: the user uploads one or more images or documents.",
+    '- accept: required list, each value once: "image" (JPEG, PNG, GIF, or WebP), "pdf", "text" (plain text), "csv", or "json".',
+    `- minFiles, maxFiles: optional whole numbers from ${files.minFiles} to ${files.maxFiles}. The user sends from minFiles (default ${files.minFiles}) to maxFiles (default ${files.maxFiles}) files.`,
+    `- submitLabel: optional label for the submit button, at most ${ASK_LIMITS.submitLabelMaxLength} characters.`,
+    "- allowDecline: optional, default true (the user sees Skip).",
+    `- The answer lists each file's filename, mimeType, and size, and the tool result then shows you each file: images and PDFs as they are, and text, CSV, and JSON as text cut to ${files.textMaxBytes} bytes.`,
+  ].join("\n");
+};
+
+const KIND_RULES: Record<AskKind, () => string> = {
+  choice: choiceRules,
+  confirm: confirmRules,
+  files: filesRules,
+  form: formRules,
+  markdown: markdownRules,
+};
+
+const COMPACT_KIND_RULES: Record<CompactAskKind, () => string> = {
+  choice: compactChoiceRules,
+  confirm: confirmRules,
+};
+
+const formatSection = ({
+  kindRules,
+  kinds,
+  shared,
+}: {
+  kindRules: string[];
+  kinds: readonly AskKind[];
+  shared: string;
+}): string => {
+  if (kinds.length === 0) {
+    return "";
+  }
+  const toolNames = kinds.map((kind) => `ask_${kind}`).join(", ");
+  return [`Ask tools you can call: ${toolNames}.`, shared, ...kindRules].join("\n\n");
+};
+
+/**
+ * The system prompt section that describes the enabled ask kinds and their limits. Every number
+ * comes from `ASK_LIMITS`. With `surface: "compact"`, it lists only the kinds the compact surface
+ * offers, with their narrowed limits. Returns an empty string when no kinds are offered.
+ */
+export const askPromptSection = ({
+  kinds,
+  surface = "full",
+}: {
+  kinds: readonly AskKind[];
+  surface?: AskSurface;
+}): string => {
+  const uniqueKinds = [...new Set(kinds)];
+  if (surface === "compact") {
+    const compactKinds = uniqueKinds.filter(isCompactAskKind);
+    return formatSection({
+      kindRules: compactKinds.map((kind) => COMPACT_KIND_RULES[kind]()),
+      kinds: compactKinds,
+      shared: compactSharedRules(),
+    });
+  }
+  return formatSection({
+    kindRules: uniqueKinds.map((kind) => KIND_RULES[kind]()),
+    kinds: uniqueKinds,
+    shared: sharedRules(),
+  });
+};

package/src/asks/schema.test.ts

@@ -0,0 +1,198 @@
+import {describe, expect, it} from "bun:test";
+import {validAskFixtures} from "../tests/askFixtures";
+import {acceptedFileMimeTypes} from "./files";
+import {formDefaultValues} from "./formValues";
+import {
+  ASK_KINDS,
+  type AskKind,
+  askAllowsDecline,
+  askInputSchemaFor,
+  askKindsForSurface,
+  COMPACT_ASK_KINDS,
+  choiceAskInputSchema,
+  compactChoiceAskInputSchema,
+  confirmAskInputSchema,
+  confirmButtonLabels,
+  filesAskInputSchema,
+  filesCountBounds,
+  formAskInputSchema,
+  isCompactAskKind,
+  markdownAskInputSchema,
+  markdownLengthBounds,
+} from "./schema";
+
+describe("askKindsForSurface", () => {
+  it("keeps every kind on the full surface", () => {
+    const kinds: AskKind[] = ["confirm", "choice"];
+    const offered = askKindsForSurface({kinds, surface: "full"});
+    expect(offered).toEqual(["confirm", "choice"]);
+    expect(offered).not.toBe(kinds);
+  });
+
+  it("keeps only the compact kinds on the compact surface", () => {
+    expect(askKindsForSurface({kinds: ASK_KINDS, surface: "compact"})).toEqual([
+      ...COMPACT_ASK_KINDS,
+    ]);
+    expect(askKindsForSurface({kinds: [], surface: "compact"})).toEqual([]);
+  });
+
+  it("offers choice and confirm on the compact surface", () => {
+    expect([...COMPACT_ASK_KINDS]).toEqual(["choice", "confirm"]);
+  });
+});
+
+describe("askInputSchemaFor", () => {
+  it("returns the full schema by default and the narrowed schema for compact", () => {
+    expect(askInputSchemaFor({kind: "choice"})).toBe(choiceAskInputSchema);
+    expect(askInputSchemaFor({kind: "choice", surface: "full"})).toBe(choiceAskInputSchema);
+    expect(askInputSchemaFor({kind: "choice", surface: "compact"})).toBe(
+      compactChoiceAskInputSchema
+    );
+    expect(askInputSchemaFor({kind: "confirm"})).toBe(confirmAskInputSchema);
+    expect(askInputSchemaFor({kind: "confirm", surface: "compact"})).toBe(confirmAskInputSchema);
+    expect(askInputSchemaFor({kind: "markdown"})).toBe(markdownAskInputSchema);
+  });
+
+  it("returns the form schema on the full surface and throws on compact", () => {
+    expect(askInputSchemaFor({kind: "form"})).toBe(formAskInputSchema);
+    expect(isCompactAskKind("form")).toBe(false);
+    expect(() => askInputSchemaFor({kind: "form", surface: "compact"})).toThrow(
+      'The compact surface does not offer ask kind "form".'
+    );
+  });
+
+  it("does not offer markdown on the compact surface, because a draft cannot be edited there", () => {
+    expect(isCompactAskKind("markdown")).toBe(false);
+    expect(() => askInputSchemaFor({kind: "markdown", surface: "compact"})).toThrow(
+      'The compact surface does not offer ask kind "markdown".'
+    );
+  });
+
+  it("only narrows: every fixture the compact schema accepts, the full schema accepts", () => {
+    for (const fixture of validAskFixtures()) {
+      if (!isCompactAskKind(fixture.kind)) {
+        continue;
+      }
+      const compact = askInputSchemaFor({kind: fixture.kind, surface: "compact"});
+      if (compact.safeParse(fixture.input).success) {
+        expect(askInputSchemaFor({kind: fixture.kind}).safeParse(fixture.input).success).toBe(true);
+      }
+    }
+  });
+});
+
+describe("askAllowsDecline", () => {
+  it("defaults to true for choice and to false for confirm", () => {
+    const prompt = "Go ahead?";
+    expect(
+      askAllowsDecline({
+        input: {
+          options: [
+            {id: "yes", label: "Yes"},
+            {id: "no", label: "No"},
+          ],
+          prompt,
+          select: "one",
+        },
+        kind: "choice",
+      })
+    ).toBe(true);
+    expect(askAllowsDecline({input: {prompt}, kind: "confirm"})).toBe(false);
+  });
+
+  it("follows allowDecline when the ask sets it", () => {
+    const prompt = "Go ahead?";
+    expect(askAllowsDecline({input: {allowDecline: true, prompt}, kind: "confirm"})).toBe(true);
+    expect(askAllowsDecline({input: {allowDecline: false, prompt}, kind: "confirm"})).toBe(false);
+  });
+
+  it("defaults to true for markdown", () => {
+    const prompt = "Edit the draft.";
+    expect(askAllowsDecline({input: {prompt}, kind: "markdown"})).toBe(true);
+    expect(askAllowsDecline({input: {allowDecline: false, prompt}, kind: "markdown"})).toBe(false);
+  });
+});
+
+describe("ASK_KINDS", () => {
+  it("appends each new kind, so existing tool order is kept", () => {
+    expect([...ASK_KINDS]).toEqual(["choice", "confirm", "markdown", "form", "files"]);
+  });
+});
+
+describe("files asks", () => {
+  it("are offered on the full surface only, because files cannot be picked on a small screen", () => {
+    expect(askInputSchemaFor({kind: "files"})).toBe(filesAskInputSchema);
+    expect(isCompactAskKind("files")).toBe(false);
+    expect(() => askInputSchemaFor({kind: "files", surface: "compact"})).toThrow(
+      'The compact surface does not offer ask kind "files".'
+    );
+  });
+
+  it("allow declining by default", () => {
+    const input = {accept: ["image" as const], prompt: "Upload it."};
+    expect(askAllowsDecline({input, kind: "files"})).toBe(true);
+    expect(askAllowsDecline({input: {...input, allowDecline: false}, kind: "files"})).toBe(false);
+  });
+
+  it("take 1 to 10 files unless the ask narrows the count", () => {
+    expect(filesCountBounds({accept: ["pdf"]})).toEqual({max: 10, min: 1});
+    expect(filesCountBounds({accept: ["pdf"], maxFiles: 3, minFiles: 2})).toEqual({
+      max: 3,
+      min: 2,
+    });
+  });
+
+  it("map each accept value to the MIME types of the /files/upload allowlist", () => {
+    expect(acceptedFileMimeTypes(["image", "pdf", "text", "csv", "json"])).toEqual([
+      "image/jpeg",
+      "image/png",
+      "image/gif",
+      "image/webp",
+      "application/pdf",
+      "text/plain",
+      "text/csv",
+      "application/json",
+    ]);
+    expect(acceptedFileMimeTypes(["csv"])).toEqual(["text/csv"]);
+  });
+});
+
+describe("askAllowsDecline for form", () => {
+  it("defaults to true", () => {
+    const input = {fields: [{id: "name", label: "Name", type: "text" as const}], prompt: "Go."};
+    expect(askAllowsDecline({input, kind: "form"})).toBe(true);
+    expect(askAllowsDecline({input: {...input, allowDecline: false}, kind: "form"})).toBe(false);
+  });
+});
+
+describe("formDefaultValues", () => {
+  it("keys each field's default by id and leaves fields without one out", () => {
+    expect(
+      formDefaultValues({
+        fields: [
+          {default: "Acme", id: "company", label: "Company", type: "text"},
+          {id: "seats", label: "Seats", type: "number"},
+          {default: false, id: "notify", label: "Notify", type: "boolean"},
+          {default: 0, id: "count", label: "Count", type: "number"},
+        ],
+        prompt: "Go.",
+      })
+    ).toEqual({company: "Acme", count: 0, notify: false});
+  });
+});
+
+describe("markdownLengthBounds", () => {
+  it("defaults to 0 through the 20,000-character cap", () => {
+    expect(markdownLengthBounds({})).toEqual({max: 20_000, min: 0});
+    expect(markdownLengthBounds({maxLength: 400, minLength: 20})).toEqual({max: 400, min: 20});
+  });
+});
+
+describe("confirmButtonLabels", () => {
+  it("uses the ask's labels, defaulting to Confirm and Cancel", () => {
+    expect(confirmButtonLabels({prompt: "Go?"})).toEqual({confirm: "Confirm", deny: "Cancel"});
+    expect(
+      confirmButtonLabels({confirmLabel: "Delete 14 todos", denyLabel: "Keep them", prompt: "Go?"})
+    ).toEqual({confirm: "Delete 14 todos", deny: "Keep them"});
+  });
+});