@terreno/blocks 57.10.1

package/src/asks/fixtures/valid/markdown-announcement-draft.json

@@ -0,0 +1,39 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "Here is a draft announcement. Edit anything, then send it back.",
+    "title": "Launch announcement",
+    "initial": "# We're live\n\nToday we launched **Terreno Asks**: your agent can now ask you a question and wait for the answer.\n\n- Pick from options\n- Approve or deny\n- Edit a draft like this one\n",
+    "maxLength": 2000,
+    "submitLabel": "Send it back"
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "approve",
+        "label": "Approve draft",
+        "response": {
+          "action": "accept",
+          "content": {
+            "changed": false,
+            "markdown": "# We're live\n\nToday we launched **Terreno Asks**: your agent can now ask you a question and wait for the answer.\n\n- Pick from options\n- Approve or deny\n- Edit a draft like this one\n"
+          }
+        },
+        "style": "primary"
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "response": {
+          "action": "decline"
+        },
+        "style": "cancel"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "Here is a draft announcement. Edit anything, then send it back.",
+    "title": "Launch announcement",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/fixtures/valid/markdown-empty-draft.json

@@ -0,0 +1,34 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "Write the message you want me to send to the team."
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "approve",
+        "label": "Approve draft",
+        "response": {
+          "action": "accept",
+          "content": {
+            "changed": false,
+            "markdown": ""
+          }
+        },
+        "style": "primary"
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "response": {
+          "action": "decline"
+        },
+        "style": "cancel"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "Write the message you want me to send to the team.",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/fixtures/valid/markdown-initial-blank-below-min.json

@@ -0,0 +1,24 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "Add a note for the delivery driver.",
+    "initial": "   ",
+    "minLength": 1
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "response": {
+          "action": "decline"
+        },
+        "style": "cancel"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "Add a note for the delivery driver.",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/fixtures/valid/markdown-initial-over-max.json

@@ -0,0 +1,24 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "This summary is too long for the 80-character slot. Trim it, then send it back.",
+    "initial": "Our quarterly results beat every forecast, driven by strong growth in the team plan and lower churn.",
+    "maxLength": 80
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "response": {
+          "action": "decline"
+        },
+        "style": "cancel"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "This summary is too long for the 80-character slot. Trim it, then send it back.",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/fixtures/valid/markdown-long-text-cut.json

@@ -0,0 +1,37 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "I drafted the quarterly update for the board. It covers revenue, hiring, the product roadmap for next quarter, and the two risks we discussed on Monday. Edit anything that reads wrong, then send it back.",
+    "title": "Quarterly board update for the October meeting",
+    "initial": "# Q3 update\n\nRevenue grew 18%.\n"
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "approve",
+        "label": "Approve draft",
+        "response": {
+          "action": "accept",
+          "content": {
+            "changed": false,
+            "markdown": "# Q3 update\n\nRevenue grew 18%.\n"
+          }
+        },
+        "style": "primary"
+      },
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "response": {
+          "action": "decline"
+        },
+        "style": "cancel"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "I drafted the quarterly update for the board. It covers revenue, hiring, the product roadmap for next quarter, and the two risks we…",
+    "title": "Quarterly board update for the October…",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/fixtures/valid/markdown-no-decline.json

@@ -0,0 +1,28 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "Review the release notes before I publish them.",
+    "initial": "## 2.3.0\n\n- Markdown asks\n",
+    "allowDecline": false
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "approve",
+        "label": "Approve draft",
+        "response": {
+          "action": "accept",
+          "content": {
+            "changed": false,
+            "markdown": "## 2.3.0\n\n- Markdown asks\n"
+          }
+        },
+        "style": "primary"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "Review the release notes before I publish them.",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/fixtures/valid/markdown-no-initial-with-min.json

@@ -0,0 +1,25 @@
+{
+  "kind": "markdown",
+  "input": {
+    "prompt": "Write a short bio for your profile page.",
+    "placeholder": "A sentence or two about you",
+    "minLength": 20,
+    "maxLength": 400
+  },
+  "simple": {
+    "buttons": [
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "response": {
+          "action": "decline"
+        },
+        "style": "cancel"
+      }
+    ],
+    "handoff": true,
+    "kind": "markdown",
+    "text": "Write a short bio for your profile page.",
+    "toolCallId": "call_fixture"
+  }
+}

package/src/asks/formValues.ts

@@ -0,0 +1,320 @@
+import {z} from "zod";
+import {type AskErrorCode, type AskErrorDraft, formatAskPath, quoteValue} from "./errors";
+import {ASK_LIMITS} from "./limits";
+import type {FormAskInput, FormField, FormFieldType} from "./schema";
+
+/** A value a form answer holds for one field. */
+export type FormValue = boolean | number | string | string[];
+
+const emailSchema = z.email();
+const urlSchema = z.url({protocol: /^https?$/});
+const PHONE_CHARACTERS = /^\+?[0-9 ().-]+$/;
+const NON_DIGITS = /\D/g;
+
+/** The ISO 8601 shape each date field type takes, with an example for fixes. */
+const DATE_FORMATS = {
+  date: {example: "2026-10-01", format: "YYYY-MM-DD", schema: z.iso.date()},
+  datetime: {
+    example: "2026-10-01T09:30:00Z",
+    format: "an ISO 8601 date and time with Z or an offset such as +02:00 (seconds optional)",
+    schema: z.union([
+      z.iso.datetime({offset: true, precision: -1}),
+      z.iso.datetime({offset: true}),
+    ]),
+  },
+  time: {example: "09:30", format: "HH:mm (24-hour)", schema: z.iso.time({precision: -1})},
+} as const;
+
+const TYPE_NAMES: Record<FormFieldType, string> = {
+  boolean: "true or false",
+  date: "a date string",
+  datetime: "a datetime string",
+  email: "an email address",
+  multiselect: "a list of option ids",
+  number: "a number",
+  phone: "a phone number",
+  select: "an option id",
+  text: "a string",
+  textarea: "a string",
+  time: "a time string",
+  url: "an http or https URL",
+};
+
+const characters = (count: number): string => (count === 1 ? "1 character" : `${count} characters`);
+
+/** The longest value a field accepts, in UTF-16 code units. */
+export const formTextMaxLength = (field: FormField): number => {
+  if (field.type === "textarea") {
+    return field.maxLength ?? ASK_LIMITS.form.textareaMaxLength;
+  }
+  if (field.type === "text") {
+    return field.maxLength ?? ASK_LIMITS.form.textMaxLength;
+  }
+  return ASK_LIMITS.form.textMaxLength;
+};
+
+/**
+ * Whether a value counts as unanswered: a string with no visible characters, or an empty list.
+ * `false` and `0` are answers.
+ */
+export const isBlankFormValue = (value: unknown): boolean =>
+  (typeof value === "string" && value.trim() === "") ||
+  (Array.isArray(value) && value.length === 0);
+
+interface CheckContext {
+  field: FormField;
+  /** True when the value is the field's `default` in an ask, not a user's answer. */
+  isDefault: boolean;
+  segments: readonly PropertyKey[];
+}
+
+const draft = (
+  {segments}: CheckContext,
+  code: AskErrorCode,
+  message: string,
+  fix: string
+): AskErrorDraft => ({code, fix, message, segments});
+
+const mismatch = (context: CheckContext, detail?: string): AskErrorDraft => {
+  const path = formatAskPath(context.segments);
+  const expected = TYPE_NAMES[context.field.type];
+  return draft(
+    context,
+    "FIELD_TYPE_MISMATCH",
+    detail ??
+      `${path} must be ${expected} for the ${context.field.type} field "${context.field.id}".`,
+    `Make ${path} ${expected}.`
+  );
+};
+
+const checkLength = (context: CheckContext, value: string): AskErrorDraft[] => {
+  const path = formatAskPath(context.segments);
+  const max = formTextMaxLength(context.field);
+  const drafts: AskErrorDraft[] = [];
+  if (value.length > max) {
+    drafts.push(
+      draft(
+        context,
+        "TOO_LONG",
+        `${path} is ${characters(value.length)}, but the field allows at most ${max}.`,
+        `Shorten ${path} to ${characters(max)} or fewer.`
+      )
+    );
+  }
+  const {field} = context;
+  const min = field.type === "text" || field.type === "textarea" ? (field.minLength ?? 0) : 0;
+  const visibleLength = value.trim().length;
+  if (visibleLength === 0 && context.isDefault) {
+    drafts.push(
+      draft(
+        context,
+        "TOO_SHORT",
+        `${path} must contain visible text.`,
+        `Write at least one visible character in ${path}, or remove it.`
+      )
+    );
+  } else if (visibleLength < min) {
+    drafts.push(
+      draft(
+        context,
+        "TOO_SHORT",
+        `${path} is ${characters(visibleLength)}, but the field needs at least ${min}.`,
+        `Write at least ${characters(min)} in ${path}.`
+      )
+    );
+  }
+  return drafts;
+};
+
+const checkStringFormat = (context: CheckContext, value: string): AskErrorDraft[] => {
+  const path = formatAskPath(context.segments);
+  const {type} = context.field;
+  if (type === "email" && !emailSchema.safeParse(value).success) {
+    return [mismatch(context, `${path} ${quoteValue(value)} is not a valid email address.`)];
+  }
+  if (type === "url" && !urlSchema.safeParse(value).success) {
+    return [mismatch(context, `${path} ${quoteValue(value)} is not an http or https URL.`)];
+  }
+  if (type === "phone") {
+    const digits = value.replace(NON_DIGITS, "").length;
+    const {phoneDigitsMax, phoneDigitsMin} = ASK_LIMITS.form;
+    if (!PHONE_CHARACTERS.test(value) || digits < phoneDigitsMin || digits > phoneDigitsMax) {
+      return [
+        draft(
+          context,
+          "FIELD_TYPE_MISMATCH",
+          `${path} ${quoteValue(value)} is not a valid phone number.`,
+          `Make ${path} ${phoneDigitsMin}-${phoneDigitsMax} digits, optionally starting with "+", with only spaces, dots, dashes, or parentheses between them.`
+        ),
+      ];
+    }
+  }
+  return [];
+};
+
+const checkNumber = (context: CheckContext, value: unknown): AskErrorDraft[] => {
+  const {field} = context;
+  if (field.type !== "number") {
+    return [];
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return [mismatch(context)];
+  }
+  const path = formatAskPath(context.segments);
+  if (field.integer === true && !Number.isInteger(value)) {
+    return [
+      draft(
+        context,
+        "FIELD_TYPE_MISMATCH",
+        `${path} is ${value}, but the field takes whole numbers only.`,
+        `Make ${path} a whole number.`
+      ),
+    ];
+  }
+  if (field.min !== undefined && value < field.min) {
+    return [
+      draft(
+        context,
+        "OUT_OF_RANGE",
+        `${path} is ${value}, below the field's min of ${field.min}.`,
+        `Make ${path} at least ${field.min}.`
+      ),
+    ];
+  }
+  if (field.max !== undefined && value > field.max) {
+    return [
+      draft(
+        context,
+        "OUT_OF_RANGE",
+        `${path} is ${value}, above the field's max of ${field.max}.`,
+        `Make ${path} at most ${field.max}.`
+      ),
+    ];
+  }
+  return [];
+};
+
+const notOffered = (context: CheckContext, id: string, segments: PropertyKey[]): AskErrorDraft =>
+  context.isDefault
+    ? {
+        code: "DEFAULT_NOT_IN_OPTIONS",
+        fix: `Use an id from fields[${String(context.segments[1])}].options, or remove it from the default.`,
+        message: `Default ${quoteValue(id)} is not the id of any option of the field.`,
+        segments,
+      }
+    : {
+        code: "OPTION_NOT_OFFERED",
+        fix: `Use the id of one of the options of the field "${context.field.id}".`,
+        message: `${quoteValue(id)} is not one of the field's options.`,
+        segments,
+      };
+
+const checkOptions = (context: CheckContext, value: unknown): AskErrorDraft[] => {
+  const {field} = context;
+  if (field.type !== "select" && field.type !== "multiselect") {
+    return [];
+  }
+  const offered = new Set(field.options.map((option) => option.id));
+  if (field.type === "select") {
+    if (typeof value !== "string") {
+      return [mismatch(context)];
+    }
+    return offered.has(value) ? [] : [notOffered(context, value, [...context.segments])];
+  }
+  if (!Array.isArray(value) || value.some((id) => typeof id !== "string")) {
+    return [mismatch(context)];
+  }
+  const path = formatAskPath(context.segments);
+  if (value.length > ASK_LIMITS.choice.optionsMax) {
+    return [
+      draft(
+        context,
+        "TOO_MANY",
+        `${path} has more than ${ASK_LIMITS.choice.optionsMax} items.`,
+        `Remove items from ${path} until it has ${ASK_LIMITS.choice.optionsMax} or fewer.`
+      ),
+    ];
+  }
+  const firstIndexById = new Map<string, number>();
+  return (value as string[]).flatMap((id, index): AskErrorDraft[] => {
+    const segments = [...context.segments, index];
+    const firstIndex = firstIndexById.get(id);
+    if (firstIndex !== undefined) {
+      return [
+        {
+          code: "DUPLICATE_ID",
+          fix: `List each option id in ${path} once.`,
+          message: `${quoteValue(id)} is already listed at ${formatAskPath([...context.segments, firstIndex])}.`,
+          segments,
+        },
+      ];
+    }
+    firstIndexById.set(id, index);
+    return offered.has(id) ? [] : [notOffered(context, id, segments)];
+  });
+};
+
+/**
+ * Checks one present value against its field: its JSON type, then the type's own rules (length,
+ * format, range, calendar date, offered options). Used for every answer value and every default,
+ * so a default is always a value the field accepts. Blank values are the caller's concern, except
+ * that a blank default string fails with `TOO_SHORT`.
+ */
+export const checkFormValue = ({
+  field,
+  isDefault,
+  segments,
+  value,
+}: CheckContext & {value: unknown}): AskErrorDraft[] => {
+  const context: CheckContext = {field, isDefault, segments};
+  switch (field.type) {
+    case "boolean":
+      return typeof value === "boolean" ? [] : [mismatch(context)];
+    case "number":
+      return checkNumber(context, value);
+    case "select":
+    case "multiselect":
+      return checkOptions(context, value);
+    case "date":
+    case "time":
+    case "datetime": {
+      if (typeof value !== "string") {
+        return [mismatch(context)];
+      }
+      const {example, format, schema} = DATE_FORMATS[field.type];
+      if (schema.safeParse(value).success) {
+        return [];
+      }
+      const path = formatAskPath(segments);
+      return [
+        draft(
+          context,
+          "INVALID_DATE",
+          `${path} ${quoteValue(value)} is not a real ${field.type} in ${format}.`,
+          `Write ${path} as ${format}, such as "${example}".`
+        ),
+      ];
+    }
+    default: {
+      if (typeof value !== "string") {
+        return [mismatch(context)];
+      }
+      const lengthDrafts = checkLength(context, value);
+      if (lengthDrafts.length > 0 || value.trim() === "") {
+        return lengthDrafts;
+      }
+      return checkStringFormat(context, value);
+    }
+  }
+};
+
+/**
+ * The values a form starts with: each field's `default`, keyed by field id. Fields without a
+ * default are left out.
+ */
+export const formDefaultValues = (input: FormAskInput): Record<string, FormValue> =>
+  Object.fromEntries(
+    input.fields.flatMap((field) =>
+      field.default === undefined ? [] : [[field.id, field.default as FormValue]]
+    )
+  );

package/src/asks/headless.test.ts

@@ -0,0 +1,146 @@
+import {describe, expect, it} from "bun:test";
+import {pendingAskListItemSchema, turnRequestSchema, turnResultSchema} from "./headless";
+import {toSimpleCard} from "./simpleCard";
+
+const SHAPES = "prompt, askResponse, or toolCallId with buttonId";
+
+const requestIssues = (body: unknown): {code: string; message: string; path: string}[] => {
+  const result = turnRequestSchema.safeParse(body);
+  if (result.success) {
+    return [];
+  }
+  return result.error.issues.map(({code, message, path}) => ({
+    code,
+    message,
+    path: path.join("."),
+  }));
+};
+
+const CARD = toSimpleCard({
+  input: {
+    options: [
+      {id: "yes", label: "Yes"},
+      {id: "no", label: "No"},
+    ],
+    prompt: "Ship it?",
+    select: "one",
+  },
+  kind: "choice",
+  toolCallId: "call_1",
+});
+
+describe("turnRequestSchema", () => {
+  it("accepts each request shape, with or without a surface", () => {
+    const bodies = [
+      {prompt: "Help me pick a plan"},
+      {prompt: "Help me pick a plan", surface: "compact"},
+      {
+        askResponse: {action: "accept", content: {selected: ["team"]}, toolCallId: "call_1"},
+        surface: "full",
+      },
+      {askResponse: {action: "decline", toolCallId: "call_1"}},
+      {askResponse: {action: "cancel", reason: "Changed my mind", toolCallId: "call_1"}},
+      {buttonId: "option:team", surface: "compact", toolCallId: "call_1"},
+    ];
+    for (const body of bodies) {
+      expect(requestIssues(body)).toEqual([]);
+    }
+  });
+
+  it("asks for one shape when the body has none", () => {
+    const expected = [{code: "custom", message: `Send one of ${SHAPES}.`, path: "prompt"}];
+    expect(requestIssues({})).toEqual(expected);
+    expect(requestIssues({surface: "compact"})).toEqual(expected);
+  });
+
+  it("names every field of a body that mixes shapes", () => {
+    const message = `Send only one of ${SHAPES}.`;
+    expect(requestIssues({buttonId: "yes", prompt: "Hi", toolCallId: "call_1"})).toEqual([
+      {code: "custom", message, path: "buttonId"},
+      {code: "custom", message, path: "prompt"},
+      {code: "custom", message, path: "toolCallId"},
+    ]);
+    expect(
+      requestIssues({askResponse: {action: "decline", toolCallId: "call_1"}, prompt: "Hi"})
+    ).toEqual([
+      {code: "custom", message, path: "askResponse"},
+      {code: "custom", message, path: "prompt"},
+    ]);
+  });
+
+  it("asks for the missing half of a button press", () => {
+    expect(requestIssues({buttonId: "option:yes"})).toEqual([
+      {code: "custom", message: "Send toolCallId with buttonId.", path: "toolCallId"},
+    ]);
+    expect(requestIssues({toolCallId: "call_1"})).toEqual([
+      {code: "custom", message: "Send buttonId with toolCallId.", path: "buttonId"},
+    ]);
+  });
+
+  it("rejects unknown fields, an unknown surface, empty strings, and an answer without toolCallId", () => {
+    expect(requestIssues({historyId: "abc", prompt: "Hi"}).map(({code}) => code)).toEqual([
+      "unrecognized_keys",
+    ]);
+    expect(requestIssues({prompt: "Hi", surface: "watch"}).map(({path}) => path)).toEqual([
+      "surface",
+    ]);
+    expect(requestIssues({prompt: ""}).map(({path}) => path)).toEqual(["prompt"]);
+    expect(requestIssues({buttonId: "", toolCallId: "call_1"}).map(({path}) => path)).toEqual([
+      "buttonId",
+    ]);
+    expect(requestIssues({askResponse: {action: "decline"}}).map(({path}) => path)).toEqual([
+      "askResponse.toolCallId",
+    ]);
+  });
+});
+
+describe("turnResultSchema", () => {
+  it("accepts a finished turn and a turn that paused on an ask", () => {
+    expect(turnResultSchema.safeParse({historyId: "h1", text: "Done."}).success).toBe(true);
+    expect(
+      turnResultSchema.safeParse({
+        historyId: "h1",
+        pendingAsk: {kind: "choice", simple: CARD, toolCallId: "call_1"},
+        text: "",
+        title: "Shipping",
+      }).success
+    ).toBe(true);
+  });
+
+  it("accepts a turn that failed after it started", () => {
+    expect(
+      turnResultSchema.safeParse({error: "The model is unavailable.", historyId: "h1", text: ""})
+        .success
+    ).toBe(true);
+  });
+
+  it("requires historyId and text", () => {
+    expect(turnResultSchema.safeParse({text: "Done."}).success).toBe(false);
+    expect(turnResultSchema.safeParse({historyId: "h1"}).success).toBe(false);
+  });
+});
+
+describe("pendingAskListItemSchema", () => {
+  const item = {
+    created: "2026-09-27T12:00:00.000Z",
+    historyId: "h1",
+    kind: "choice",
+    simple: CARD,
+    title: "Shipping",
+    toolCallId: "call_1",
+  };
+
+  it("accepts a pending ask with its card", () => {
+    expect(pendingAskListItemSchema.safeParse(item).success).toBe(true);
+  });
+
+  it("requires created to be an ISO 8601 UTC timestamp", () => {
+    expect(pendingAskListItemSchema.safeParse({...item, created: "yesterday"}).success).toBe(false);
+  });
+
+  it("rejects a card that is not a simple card", () => {
+    expect(
+      pendingAskListItemSchema.safeParse({...item, simple: {...CARD, buttons: "none"}}).success
+    ).toBe(false);
+  });
+});