@terreno/blocks 57.10.1

package/src/asks/headless.ts

@@ -0,0 +1,130 @@
+import {z} from "zod";
+import {
+  ASK_KINDS,
+  ASK_SURFACES,
+  askAcceptResponseSchema,
+  askCancelResponseSchema,
+  askDeclineResponseSchema,
+} from "./schema";
+import {simpleCardSchema} from "./simpleCard";
+
+const TURN_SHAPES = "prompt, askResponse, or toolCallId with buttonId";
+
+export const askSurfaceSchema = z
+  .enum(ASK_SURFACES)
+  .describe(
+    'Where the user answers. "compact" is a watch or another small screen: the agent asks only questions whose buttons show every option, and keeps replies to two short sentences. Defaults to "full".'
+  );
+
+const toolCallIdSchema = z.string().min(1).describe("The pending ask's toolCallId.");
+
+/** An answer to a pending ask: the answer envelope plus the ask's `toolCallId`. */
+export const askResponseWithToolCallIdSchema = z.discriminatedUnion("action", [
+  askAcceptResponseSchema.extend({toolCallId: toolCallIdSchema}),
+  askDeclineResponseSchema.extend({toolCallId: toolCallIdSchema}),
+  askCancelResponseSchema.extend({toolCallId: toolCallIdSchema}),
+]);
+
+export type AskResponseWithToolCallId = z.infer<typeof askResponseWithToolCallIdSchema>;
+
+type TurnRequestFields = Partial<
+  Record<"askResponse" | "buttonId" | "prompt" | "toolCallId", unknown>
+>;
+
+/** Puts every issue on a field, because clients show request errors next to the field they name. */
+const checkTurnRequest = (body: TurnRequestFields, ctx: z.RefinementCtx): void => {
+  const sent = (["askResponse", "buttonId", "prompt", "toolCallId"] as const).filter(
+    (key) => body[key] !== undefined
+  );
+  const hasButton = sent.includes("buttonId") || sent.includes("toolCallId");
+  const shapeCount =
+    Number(sent.includes("prompt")) + Number(sent.includes("askResponse")) + Number(hasButton);
+  if (shapeCount === 0) {
+    ctx.addIssue({code: "custom", message: `Send one of ${TURN_SHAPES}.`, path: ["prompt"]});
+    return;
+  }
+  if (shapeCount > 1) {
+    for (const key of sent) {
+      ctx.addIssue({code: "custom", message: `Send only one of ${TURN_SHAPES}.`, path: [key]});
+    }
+    return;
+  }
+  if (hasButton && body.toolCallId === undefined) {
+    ctx.addIssue({code: "custom", message: "Send toolCallId with buttonId.", path: ["toolCallId"]});
+  }
+  if (hasButton && body.buttonId === undefined) {
+    ctx.addIssue({code: "custom", message: "Send buttonId with toolCallId.", path: ["buttonId"]});
+  }
+};
+
+/** The body of `POST /gpt/histories/:id/turn`. */
+export const turnRequestSchema = z
+  .object({
+    askResponse: askResponseWithToolCallIdSchema
+      .optional()
+      .describe("A full answer to the pending ask, as a client that renders the ask sends it."),
+    buttonId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The id of the simple card button the user pressed. Send it with toolCallId."),
+    prompt: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("A new message from the user. It cancels the pending ask, if there is one."),
+    surface: askSurfaceSchema.optional(),
+    toolCallId: toolCallIdSchema.optional(),
+  })
+  .strict()
+  .superRefine(checkTurnRequest)
+  .describe(`Send exactly one of ${TURN_SHAPES}, plus an optional surface.`);
+
+export type TurnRequest = z.infer<typeof turnRequestSchema>;
+
+export const pendingAskSummarySchema = z
+  .object({
+    kind: z.enum(ASK_KINDS),
+    simple: simpleCardSchema,
+    toolCallId: z.string().min(1),
+  })
+  .strict()
+  .describe(
+    "The ask the turn paused on. Answer it with its toolCallId and the id of one of simple.buttons."
+  );
+
+export type PendingAskSummary = z.infer<typeof pendingAskSummarySchema>;
+
+/** What `POST /gpt/histories/:id/turn` returns in `data` once the turn finishes. */
+export const turnResultSchema = z
+  .object({
+    error: z
+      .string()
+      .optional()
+      .describe(
+        "Set when the turn failed after it started. text holds what the agent said before the error."
+      ),
+    historyId: z.string().min(1).describe("The conversation's id."),
+    pendingAsk: pendingAskSummarySchema.optional(),
+    text: z.string().describe("The agent's reply, or an empty string when it only asked."),
+    title: z.string().optional().describe("The conversation's title, once it has one."),
+  })
+  .strict();
+
+export type TurnResult = z.infer<typeof turnResultSchema>;
+
+export const pendingAskListItemSchema = z
+  .object({
+    created: z.iso.datetime().describe("When the agent asked, as an ISO 8601 UTC timestamp."),
+    historyId: z.string().min(1).describe("The conversation the ask belongs to."),
+    kind: z.enum(ASK_KINDS),
+    simple: simpleCardSchema,
+    title: z.string().optional().describe("The conversation's title, once it has one."),
+    toolCallId: z.string().min(1),
+  })
+  .strict();
+
+export type PendingAskListItem = z.infer<typeof pendingAskListItemSchema>;
+
+/** What `GET /gpt/histories/pendingAsks` returns in `data`: the caller's pending asks, newest first. */
+export const pendingAskListSchema = z.array(pendingAskListItemSchema);

package/src/asks/jsonSchema.test.ts

@@ -0,0 +1,171 @@
+import {describe, expect, it} from "bun:test";
+import {readdirSync, readFileSync} from "node:fs";
+import {join} from "node:path";
+import {z} from "zod";
+import {validAskFixtures} from "../tests/askFixtures";
+import {pendingAskListSchema, turnRequestSchema, turnResultSchema} from "./headless";
+import {askJsonSchemas} from "./jsonSchema";
+import {simpleCardSchema, toSimpleCard} from "./simpleCard";
+
+const SCHEMAS_DIR = join(import.meta.dir, "..", "..", "schemas");
+
+const documents = askJsonSchemas();
+
+/** A Zod schema rebuilt from a committed document, standing in for a client's JSON Schema validator. */
+const fromDocument = (fileName: string): z.ZodType => {
+  const document = documents[fileName];
+  if (!document) {
+    throw new Error(`No JSON Schema document named ${fileName}.`);
+  }
+  return z.fromJSONSchema(document as Parameters<typeof z.fromJSONSchema>[0]);
+};
+
+const CARDS = validAskFixtures().map((fixture) =>
+  toSimpleCard({input: fixture.input, kind: fixture.kind, toolCallId: "call_fixture"})
+);
+
+const [CARD] = CARDS;
+if (!CARD) {
+  throw new Error("The valid fixtures are missing.");
+}
+
+describe("askJsonSchemas", () => {
+  it("matches the files committed in blocks/schemas (run `bun run schemas` in blocks/ to update them)", () => {
+    const committed = Object.fromEntries(
+      readdirSync(SCHEMAS_DIR)
+        .sort()
+        .map((fileName) => [
+          fileName,
+          JSON.parse(readFileSync(join(SCHEMAS_DIR, fileName), "utf8")) as unknown,
+        ])
+    );
+    expect(committed).toEqual(documents);
+  });
+
+  it("writes draft-07 documents with a title and a description", () => {
+    expect(Object.keys(documents).sort()).toEqual([
+      "pendingAsksResponse.schema.json",
+      "simpleCard.schema.json",
+      "turnRequest.schema.json",
+      "turnResponse.schema.json",
+    ]);
+    for (const document of Object.values(documents)) {
+      expect(document.$schema).toBe("http://json-schema.org/draft-07/schema#");
+      expect(typeof document.title).toBe("string");
+      expect(typeof document.description).toBe("string");
+    }
+  });
+
+  it("names nested types so generated code gets readable names", () => {
+    const text = JSON.stringify(documents["turnResponse.schema.json"]);
+    for (const title of ["TurnResult", "PendingAskSummary", "SimpleCard", "SimpleCardButton"]) {
+      expect(text).toContain(`"title":"${title}"`);
+    }
+  });
+});
+
+describe("simpleCard.schema.json", () => {
+  const fromJson = fromDocument("simpleCard.schema.json");
+
+  it("accepts the card of every valid fixture, as simpleCardSchema does", () => {
+    for (const card of CARDS) {
+      expect(simpleCardSchema.safeParse(card).success).toBe(true);
+      expect(fromJson.safeParse(card).success).toBe(true);
+    }
+  });
+
+  it("rejects the cards simpleCardSchema rejects for their shape and limits", () => {
+    const button = {id: "skip", label: "Skip", response: {action: "decline"}, style: "cancel"};
+    const invalidCards = [
+      {...CARD, buttons: ["a", "b", "c", "d"].map((id) => ({...button, id}))},
+      {...CARD, buttons: [{...button, label: "x".repeat(21)}]},
+      {...CARD, buttons: [{...button, style: "danger"}]},
+      {...CARD, buttons: [{...button, response: {action: "skip"}}]},
+      {...CARD, text: "x".repeat(141)},
+      {...CARD, text: ""},
+      {...CARD, title: "x".repeat(41)},
+      {...CARD, kind: "signature"},
+      {...CARD, color: "red"},
+      {buttons: CARD.buttons, handoff: false, kind: "choice", toolCallId: "call_1"},
+    ];
+    for (const card of invalidCards) {
+      expect(simpleCardSchema.safeParse(card).success).toBe(false);
+      expect(fromJson.safeParse(card).success).toBe(false);
+    }
+  });
+});
+
+describe("turnRequest.schema.json", () => {
+  const fromJson = fromDocument("turnRequest.schema.json");
+
+  it("accepts every request shape turnRequestSchema accepts", () => {
+    const bodies = [
+      {prompt: "Help me pick a plan", surface: "compact"},
+      {askResponse: {action: "accept", content: {selected: ["team"]}, toolCallId: "call_1"}},
+      {askResponse: {action: "decline", toolCallId: "call_1"}},
+      {buttonId: "option:team", surface: "full", toolCallId: "call_1"},
+    ];
+    for (const body of bodies) {
+      expect(turnRequestSchema.safeParse(body).success).toBe(true);
+      expect(fromJson.safeParse(body).success).toBe(true);
+    }
+  });
+
+  it("rejects unknown fields, unknown surfaces, and answers without toolCallId", () => {
+    const bodies = [
+      {historyId: "h1", prompt: "Hi"},
+      {prompt: "Hi", surface: "watch"},
+      {askResponse: {action: "decline"}},
+      {askResponse: {action: "skip", toolCallId: "call_1"}},
+    ];
+    for (const body of bodies) {
+      expect(turnRequestSchema.safeParse(body).success).toBe(false);
+      expect(fromJson.safeParse(body).success).toBe(false);
+    }
+  });
+
+  it("leaves the one-shape rule to the server", () => {
+    expect(fromJson.safeParse({}).success).toBe(true);
+    expect(turnRequestSchema.safeParse({}).success).toBe(false);
+  });
+});
+
+describe("turnResponse.schema.json and pendingAsksResponse.schema.json", () => {
+  const turnResponse = fromDocument("turnResponse.schema.json");
+  const pendingAsksResponse = fromDocument("pendingAsksResponse.schema.json");
+  const result = {
+    historyId: "h1",
+    pendingAsk: {kind: "choice", simple: CARD, toolCallId: CARD.toolCallId},
+    text: "",
+    title: "Plans",
+  };
+  const item = {
+    created: "2026-09-27T12:00:00.000Z",
+    historyId: "h1",
+    kind: "choice",
+    simple: CARD,
+    toolCallId: CARD.toolCallId,
+  };
+
+  const requestId = "3f0c9a52-7d1e-4b8a-9c65-2a4e1b7d9f30";
+
+  it("accept the bodies the endpoints send, with or without the requestId TerrenoApp adds", () => {
+    expect(turnResultSchema.safeParse(result).success).toBe(true);
+    expect(pendingAskListSchema.safeParse([item]).success).toBe(true);
+    for (const envelope of [{}, {requestId}]) {
+      expect(turnResponse.safeParse({...envelope, data: result}).success).toBe(true);
+      expect(pendingAsksResponse.safeParse({...envelope, data: [item]}).success).toBe(true);
+      expect(pendingAsksResponse.safeParse({...envelope, data: []}).success).toBe(true);
+    }
+  });
+
+  it("reject bodies missing required fields, with a bad timestamp, or with an unknown field", () => {
+    expect(turnResponse.safeParse({data: {text: "Done."}}).success).toBe(false);
+    expect(turnResponse.safeParse(result).success).toBe(false);
+    expect(turnResponse.safeParse({data: result, requestID: requestId}).success).toBe(false);
+    expect(pendingAsksResponse.safeParse({data: [{...item, created: "yesterday"}]}).success).toBe(
+      false
+    );
+    expect(pendingAsksResponse.safeParse({data: [], requestId: 7}).success).toBe(false);
+  });
+});

package/src/asks/jsonSchema.ts

@@ -0,0 +1,89 @@
+import {z} from "zod";
+import {
+  askResponseWithToolCallIdSchema,
+  pendingAskListItemSchema,
+  pendingAskListSchema,
+  pendingAskSummarySchema,
+  turnRequestSchema,
+  turnResultSchema,
+} from "./headless";
+import {askResponseSchema} from "./schema";
+import {simpleCardButtonSchema, simpleCardSchema} from "./simpleCard";
+
+/** Titles for nested schemas, so types generated from the documents get readable names. */
+const NESTED_TITLES = new Map<z.core.$ZodType, string>([
+  [askResponseSchema, "AskResponse"],
+  [askResponseWithToolCallIdSchema, "AskAnswer"],
+  [pendingAskListItemSchema, "PendingAsk"],
+  [pendingAskSummarySchema, "PendingAskSummary"],
+  [simpleCardButtonSchema, "SimpleCardButton"],
+  [simpleCardSchema, "SimpleCard"],
+  [turnResultSchema, "TurnResult"],
+]);
+
+interface JsonSchemaDocument {
+  description: string;
+  schema: z.ZodType;
+  title: string;
+}
+
+const requestIdSchema = z
+  .string()
+  .optional()
+  .describe(
+    "The request's id. Apps built with TerrenoApp add it to every JSON response; quote it when reporting a problem."
+  );
+
+const DOCUMENTS: Record<string, JsonSchemaDocument> = {
+  "pendingAsksResponse.schema.json": {
+    description:
+      "The response body of GET /gpt/histories/pendingAsks: the caller's pending asks, newest first.",
+    schema: z.object({data: pendingAskListSchema, requestId: requestIdSchema}).strict(),
+    title: "PendingAsksResponse",
+  },
+  "simpleCard.schema.json": {
+    description:
+      "The small-screen form of an ask: short text and at most three buttons, each carrying the exact answer it sends. Button ids are unique within a card, which JSON Schema cannot express.",
+    schema: simpleCardSchema,
+    title: "SimpleCard",
+  },
+  "turnRequest.schema.json": {
+    description:
+      "The request body of POST /gpt/histories/{id}/turn. Send exactly one of prompt, askResponse, or toolCallId with buttonId, plus an optional surface. JSON Schema cannot express that rule; the server enforces it.",
+    schema: turnRequestSchema,
+    title: "TurnRequest",
+  },
+  "turnResponse.schema.json": {
+    description: "The response body of POST /gpt/histories/{id}/turn, sent once the turn finishes.",
+    schema: z.object({data: turnResultSchema, requestId: requestIdSchema}).strict(),
+    title: "TurnResponse",
+  },
+};
+
+const toDocument = ({description, schema, title}: JsonSchemaDocument): Record<string, unknown> => {
+  const {
+    $schema,
+    description: _schemaDescription,
+    title: _schemaTitle,
+    ...rest
+  } = z.toJSONSchema(schema, {
+    override: ({jsonSchema, zodSchema}) => {
+      const nestedTitle = NESTED_TITLES.get(zodSchema);
+      if (nestedTitle) {
+        jsonSchema.title = nestedTitle;
+      }
+    },
+    target: "draft-7",
+  });
+  return {$schema, description, title, ...rest};
+};
+
+/**
+ * JSON Schema (draft-07) documents for native clients, such as a watch app generating Swift
+ * `Codable` types: the simple card and the bodies of the two headless endpoints. Keyed by the file
+ * name they are committed under in `blocks/schemas/`.
+ */
+export const askJsonSchemas = (): Record<string, Record<string, unknown>> =>
+  Object.fromEntries(
+    Object.entries(DOCUMENTS).map(([fileName, document]) => [fileName, toDocument(document)])
+  );

package/src/asks/limits.ts

@@ -0,0 +1,58 @@
+/**
+ * Hard limits for asks. The schemas, the prompt section, the docs, and the tests all read these
+ * values, so change them here only.
+ */
+export const ASK_LIMITS = {
+  cancelReasonMaxLength: 200,
+  choice: {
+    optionDescriptionMaxLength: 280,
+    optionIdMaxLength: 64,
+    /** Must allow exactly `optionIdMaxLength` characters. */
+    optionIdPattern: /^[a-z0-9][a-z0-9_-]{0,63}$/,
+    optionLabelMaxLength: 120,
+    optionsMax: 50,
+    optionsMin: 2,
+    otherMaxLength: 500,
+  },
+  confirm: {
+    /** Every confirm label fits a simple card button uncut. */
+    labelMaxLength: 20,
+  },
+  files: {
+    /** The per-file cap when the host sets no `maxFileSizeBytes`, matching `/files/upload`. */
+    defaultMaxFileSizeBytes: 10 * 1024 * 1024,
+    filenameMaxLength: 255,
+    maxFiles: 10,
+    minFiles: 1,
+    /** Text, CSV, and JSON files reach the model cut to this many bytes, with a note. */
+    textMaxBytes: 100_000,
+  },
+  form: {
+    fieldsMax: 8,
+    fieldsMin: 1,
+    helperTextMaxLength: 280,
+    labelMaxLength: 120,
+    /** The fewest and most digits in a `phone` value. */
+    phoneDigitsMax: 15,
+    phoneDigitsMin: 7,
+    /** The cap on a `textarea` value and on a `textarea` field's `maxLength`. */
+    textareaMaxLength: 10_000,
+    /** The cap on a `text`, `email`, `url`, or `phone` value, and on a `text` field's `maxLength`. */
+    textMaxLength: 2000,
+  },
+  markdown: {
+    /** The cap on `initial`, on `maxLength`, and on every answer. */
+    maxLength: 20_000,
+    placeholderMaxLength: 120,
+  },
+  pendingAsksPerHistory: 1,
+  promptMaxLength: 500,
+  simpleCard: {
+    buttonLabelMaxLength: 20,
+    buttonsMax: 3,
+    textMaxLength: 140,
+    titleMaxLength: 40,
+  },
+  submitLabelMaxLength: 24,
+  titleMaxLength: 80,
+} as const;

package/src/asks/prompt.test.ts

@@ -0,0 +1,200 @@
+import {describe, expect, it} from "bun:test";
+import {askPromptSection} from "./prompt";
+
+const CHOICE_SECTION = `Ask tools you can call: ask_choice.
+
+Rules for every ask:
+- prompt: required. Plain text with no markdown and no links, 1-500 characters.
+- title: optional, at most 80 characters.
+- Each ask kind below lists its other fields, including whether the user can skip it.
+
+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: 2-50 items, each {id, label, description?}.
+- id: 1-64 lowercase letters, digits, "_", or "-", starting with a letter or digit. Unique within the ask.
+- label: at most 120 characters. description: optional, at most 280 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 500 characters. It counts as one choice. otherLabel: optional label for that field, at most 120 characters. For one option or Other, use "many" with maxSelected 1.
+- submitLabel: optional label for the submit button, at most 24 characters.
+- allowDecline: optional, default true (the user sees Skip). Set it to false only when you cannot continue without an answer.
+- Prefer select "one" with at most 3 options with labels of 20 characters or fewer; small screens show those as buttons.
+- An accepted answer looks like {"action": "accept", "content": {"selected": ["<id>"]}}.
+- With Other, it looks like {"action": "accept", "content": {"selected": ["<id>"], "other": "<text the user typed>"}}.`;
+
+const COMPACT_CHOICE_SECTION = `Ask tools you can call: ask_choice.
+
+Rules for every ask:
+- prompt: required. Plain text with no markdown and no links, 1-500 characters.
+- title: optional, at most 80 characters.
+- Each ask kind below lists its other fields, including whether the user can skip it.
+- The screen is small: it shows only the first 140 characters of prompt and the first 40 characters of title, so keep both within those lengths.
+
+ask_choice: the user picks one option by tapping its button.
+- select: always "one".
+- options: 2-3 items, each {id, label, description?}.
+- id: 1-64 lowercase letters, digits, "_", or "-", starting with a letter or digit. Unique within the ask.
+- label: at most 20 characters, counting each emoji as 2 or more, and no two options share a label.
+- description: optional, at most 280 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.
+- allowDecline: optional, default true (the user sees Skip). Set it to false only when you cannot continue without an answer.
+- An accepted answer looks like {"action": "accept", "content": {"selected": ["<id>"]}}.`;
+
+const CONFIRM_RULES = `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 20 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.`;
+
+const MARKDOWN_RULES = `ask_markdown: the user edits a markdown draft you write and sends it back.
+- initial: optional, the draft in markdown, at most 20000 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 20000, the most allowed) characters. minLength must not be more than maxLength.
+- placeholder: optional hint shown while the editor is empty, at most 120 characters.
+- submitLabel: optional label for the submit button, at most 24 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.`;
+
+const FORM_RULES = `ask_form: the user fills in a few fields and submits them at once.
+- fields: 1-8 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-64 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 120 characters. helperText: optional, at most 280 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 2000 for text and 10000 for textarea. The value is a string.
+- type "email", "url" (http or https), or "phone" (7-15 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, 2-50 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 24 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.`;
+
+const FILES_RULES = `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 1 to 10. The user sends from minFiles (default 1) to maxFiles (default 10) files.
+- submitLabel: optional label for the submit button, at most 24 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 100000 bytes.`;
+
+const sectionOf = (section: string, kindRules: string[]): string =>
+  [section.replace("ask_choice.", "ask_choice, ask_confirm."), ...kindRules].join("\n\n");
+
+describe("askPromptSection", () => {
+  it("describes ask_choice with the limits from ASK_LIMITS", () => {
+    expect(askPromptSection({kinds: ["choice"]})).toBe(CHOICE_SECTION);
+  });
+
+  it("lists each kind once when a kind repeats", () => {
+    expect(askPromptSection({kinds: ["choice", "choice"]})).toBe(CHOICE_SECTION);
+  });
+
+  it("returns an empty string when no kinds are enabled", () => {
+    expect(askPromptSection({kinds: []})).toBe("");
+  });
+
+  it("describes the full surface by default", () => {
+    expect(askPromptSection({kinds: ["choice"], surface: "full"})).toBe(CHOICE_SECTION);
+  });
+
+  it("describes ask_confirm after ask_choice, with the button label limit", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm"]})).toBe(
+      sectionOf(CHOICE_SECTION, [CONFIRM_RULES])
+    );
+  });
+
+  it("describes ask_confirm alone, with the shared rules", () => {
+    const section = askPromptSection({kinds: ["confirm"]});
+    expect(section.startsWith("Ask tools you can call: ask_confirm.\n\nRules for every ask:")).toBe(
+      true
+    );
+    expect(section.endsWith(`\n\n${CONFIRM_RULES}`)).toBe(true);
+    expect(section).not.toContain("ask_choice");
+  });
+
+  it("describes ask_markdown after ask_confirm, with the length limits from ASK_LIMITS", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm", "markdown"]})).toBe(
+      [
+        CHOICE_SECTION.replace("ask_choice.", "ask_choice, ask_confirm, ask_markdown."),
+        CONFIRM_RULES,
+        MARKDOWN_RULES,
+      ].join("\n\n")
+    );
+  });
+
+  it("describes ask_form after ask_markdown, with the field limits from ASK_LIMITS", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm", "markdown", "form"]})).toBe(
+      [
+        CHOICE_SECTION.replace("ask_choice.", "ask_choice, ask_confirm, ask_markdown, ask_form."),
+        CONFIRM_RULES,
+        MARKDOWN_RULES,
+        FORM_RULES,
+      ].join("\n\n")
+    );
+  });
+
+  it("describes ask_files after ask_form, with the file limits from ASK_LIMITS", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm", "markdown", "form", "files"]})).toBe(
+      [
+        CHOICE_SECTION.replace(
+          "ask_choice.",
+          "ask_choice, ask_confirm, ask_markdown, ask_form, ask_files."
+        ),
+        CONFIRM_RULES,
+        MARKDOWN_RULES,
+        FORM_RULES,
+        FILES_RULES,
+      ].join("\n\n")
+    );
+  });
+
+  it("leaves submitLabel and the Skip default out of the shared rules, since confirm differs", () => {
+    const section = askPromptSection({kinds: ["confirm"]});
+    expect(section).not.toContain("submitLabel");
+    expect(section).not.toContain("default true");
+    expect(section).toContain("- allowDecline: optional, default false");
+  });
+});
+
+describe("askPromptSection on the compact surface", () => {
+  it("describes ask_choice with the simple card limits from ASK_LIMITS", () => {
+    expect(askPromptSection({kinds: ["choice"], surface: "compact"})).toBe(COMPACT_CHOICE_SECTION);
+  });
+
+  it("lists each kind once when a kind repeats", () => {
+    expect(askPromptSection({kinds: ["choice", "choice"], surface: "compact"})).toBe(
+      COMPACT_CHOICE_SECTION
+    );
+  });
+
+  it("returns an empty string when no kinds are enabled", () => {
+    expect(askPromptSection({kinds: [], surface: "compact"})).toBe("");
+  });
+
+  it("offers ask_confirm with the same rules, because it always fits a simple card", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm"], surface: "compact"})).toBe(
+      sectionOf(COMPACT_CHOICE_SECTION, [CONFIRM_RULES])
+    );
+  });
+
+  it("leaves ask_markdown out, because a draft cannot be edited on a small screen", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm", "markdown"], surface: "compact"})).toBe(
+      sectionOf(COMPACT_CHOICE_SECTION, [CONFIRM_RULES])
+    );
+    expect(askPromptSection({kinds: ["markdown"], surface: "compact"})).toBe("");
+  });
+
+  it("leaves ask_form out, because fields cannot be filled in on a small screen", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm", "form"], surface: "compact"})).toBe(
+      sectionOf(COMPACT_CHOICE_SECTION, [CONFIRM_RULES])
+    );
+    expect(askPromptSection({kinds: ["form"], surface: "compact"})).toBe("");
+  });
+
+  it("leaves ask_files out, because files cannot be picked on a small screen", () => {
+    expect(askPromptSection({kinds: ["choice", "confirm", "files"], surface: "compact"})).toBe(
+      sectionOf(COMPACT_CHOICE_SECTION, [CONFIRM_RULES])
+    );
+    expect(askPromptSection({kinds: ["files"], surface: "compact"})).toBe("");
+  });
+});