@terreno/blocks 57.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flourish Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @terreno/blocks
+
+Shared contracts for agent-driven UI — ask schemas, answer validation, and simple cards.
+
+Runtime-agnostic Zod contracts shared by `@terreno/ai` (server) and `@terreno/ui` (renderer), plus
+JSON Schema documents and fixtures for native clients such as a Swift watch app. The only runtime
+dependency is `zod`.
+
+## Install
+
+```bash
+bun add @terreno/blocks
+```
+
+Most apps get it through `@terreno/ai` and `@terreno/ui`. Install it directly to validate asks or
+answers in your own code, or to build a client that answers asks without React.
+
+## Quick start
+
+```typescript
+import {type ChoiceAsk, toSimpleCard, validateAskInput, validateAskResponse} from "@terreno/blocks";
+
+const ask: ChoiceAsk = {
+  input: {
+    options: [
+      {id: "starter", label: "Starter"},
+      {id: "team", label: "Team"},
+    ],
+    prompt: "Which plan should I set up?",
+    select: "one",
+  },
+  kind: "choice",
+};
+
+const inputErrors = validateAskInput(ask); // [] when the ask is valid
+const answerErrors = validateAskResponse({
+  ...ask,
+  response: {action: "accept", content: {selected: ["team"]}},
+});
+const card = toSimpleCard({...ask, toolCallId: "call_1"}); // title, text, and up to 3 buttons
+```
+
+## What's included
+
+- Ask schemas for every kind (`choice`, `confirm`, `markdown`, `form`, `files`) and the answer
+  envelope (`accept`, `decline`, `cancel`)
+- `validateAskInput` and `validateAskResponse`, with stable error codes (`ASK_ERROR_CODES`) and
+  limits (`ASK_LIMITS`)
+- Simple cards for small screens: `toSimpleCard`, `resolveButtonAnswer`, and the compact surface
+- Bodies of the headless `pendingAsks` and `turn` endpoints
+- JSON Schema documents (`@terreno/blocks/schemas/*`) and valid and invalid fixtures
+  (`@terreno/blocks/fixtures/*`)
+
+## Documentation
+
+- Reference: [docs/reference/agent-ui-asks.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/agent-ui-asks.md)
+- How-to: [docs/how-to/agent-ui-asks.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/agent-ui-asks.md)
+- Explanation: [docs/explanation/agent-ui-asks.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/explanation/agent-ui-asks.md)
+
+## License and Contributing
+
+Licensed under the [MIT License](https://github.com/TerrenoLabs/terreno/blob/master/LICENSE). See [CONTRIBUTING.md](https://github.com/TerrenoLabs/terreno/blob/master/CONTRIBUTING.md) for contribution guidelines.

package/biome.jsonc

@@ -0,0 +1,18 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": ["../biome.jsonc"],
+  "files": {
+    "includes": [
+      "package.json",
+      "src/**/*.ts",
+      "scripts/**/*.ts",
+      "!!**/node_modules",
+      "!!node_modules",
+      "!!**/dist",
+      "!!dist",
+      "!!**/coverage",
+      "!!coverage"
+    ]
+  },
+  "root": true
+}

package/bunfig.toml

@@ -0,0 +1,6 @@
+[test]
+root = "./src"
+# `scripts/` holds dev-only generators (`bun run schemas`). `src/asks/jsonSchema.test.ts` fails
+# when their committed output is stale, and the new-file coverage gate reads this list.
+coveragePathIgnorePatterns = ["**/dist/**", "**/*.test.ts", "**/tests/**", "**/node_modules/**", "../**", "scripts/**"]
+coverageThreshold = { line = 95, function = 95 }

package/dist/asks/errors.d.ts

@@ -0,0 +1,77 @@
+import type { z } from "zod";
+/**
+ * Every ask error code, with its meaning. `validateAskInput` and `validateAskResponse` return all
+ * of them except `UNKNOWN_BUTTON`, which the headless `turn` endpoint returns, and
+ * `FILE_NOT_OWNED`, which the server returns when it loads an uploaded file.
+ */
+export declare const ASK_ERROR_CODES: {
+    readonly CHANGED_MISMATCH: "A markdown answer's changed flag does not match whether its text differs from the draft.";
+    readonly DECLINE_NOT_ALLOWED: "The answer skips an ask that does not allow skipping.";
+    readonly DEFAULT_NOT_IN_OPTIONS: "A default names an option id that the ask does not offer.";
+    readonly DUPLICATE_ID: "An id appears twice where ids must be unique: options, default, accept, or an answer.";
+    readonly DUPLICATE_LABEL: "Two buttons would share a label: options of a compact ask, or a confirm's approve and deny.";
+    readonly FIELD_TYPE_MISMATCH: "A form value or default does not fit its field's type: the wrong JSON type, not a whole number, or not a valid email, URL, or phone number.";
+    readonly FILE_COUNT: "A files answer has fewer files than minFiles or more than maxFiles.";
+    readonly FILE_NOT_OWNED: "A files answer names a fileId that is not an upload of the caller, or the host has no file storage.";
+    readonly FILE_TOO_LARGE: "A file is larger than the host's per-file upload cap.";
+    readonly FILE_TYPE_NOT_ACCEPTED: "A file's declared type is not one the ask's accept list allows.";
+    readonly INVALID_DATE: "A form date, time, or datetime value or default is not a real ISO 8601 value in the field's format.";
+    readonly INVALID_ENUM: "A value is not one of the allowed values.";
+    readonly INVALID_FORMAT: "A string does not match its required format.";
+    readonly INVALID_TYPE: "A value has the wrong type.";
+    readonly MIME_MISMATCH: "A file's bytes, or its data URL's media type, do not match the type the answer declares.";
+    readonly MISSING_REQUIRED: "A required field is missing.";
+    readonly OPTION_NOT_OFFERED: "The answer selects an option id that the ask did not offer.";
+    readonly OTHER_NOT_ALLOWED: "An ask or an answer uses Other where the ask does not allow it.";
+    readonly OUT_OF_RANGE: "A form number value or default is below the field's min or above its max.";
+    readonly RANGE_INVALID: "A count or length bound is out of range: below its minimum, above what the ask offers, or a minimum above its maximum.";
+    readonly REQUIRED_FIELD: "A form answer leaves a required field missing or blank.";
+    readonly SELECTION_COUNT: "A default or an answer selects the wrong number of options.";
+    readonly TOO_FEW: "A list has fewer items than allowed.";
+    readonly TOO_LONG: "A string is longer than allowed.";
+    readonly TOO_MANY: "A list has more items than allowed.";
+    readonly TOO_SHORT: "A string is empty, only whitespace, or shorter than its minimum.";
+    readonly UNKNOWN_BUTTON: "The pressed button is not on the pending ask's simple card.";
+    readonly UNKNOWN_KEY: "An object has a field that its schema does not define.";
+};
+export type AskErrorCode = keyof typeof ASK_ERROR_CODES;
+export interface AskValidationError {
+    /** A key of `ASK_ERROR_CODES`. */
+    code: AskErrorCode;
+    /** One instruction that fixes the error. */
+    fix: string;
+    /** What is wrong, in one sentence. */
+    message: string;
+    /** Where the error is, such as `options[2].id`. The root is an empty string. */
+    path: string;
+}
+/** An error before sorting; `segments` keeps array indexes numeric so they sort correctly. */
+export interface AskErrorDraft {
+    code: AskErrorCode;
+    fix: string;
+    message: string;
+    segments: readonly PropertyKey[];
+}
+export declare const formatAskPath: (segments: readonly PropertyKey[]) => string;
+/** A Zod custom issue that carries an ask error code and its fix. */
+export declare const askIssue: ({ code, fix, message, segments, }: AskErrorDraft) => {
+    code: "custom";
+    message: string;
+    params: {
+        askCode: AskErrorCode;
+        fix: string;
+    };
+    path: PropertyKey[];
+};
+export declare const quoteValue: (value: unknown) => string;
+/**
+ * Maps Zod issues to ask errors. `root` is the value that was parsed; it tells a missing key apart
+ * from a key with the wrong type. `prefix` is prepended to every path.
+ */
+export declare const issuesToAskErrors: ({ issues, prefix, root, }: {
+    issues: readonly z.core.$ZodIssue[];
+    prefix?: readonly PropertyKey[];
+    root: unknown;
+}) => AskErrorDraft[];
+/** Sorts drafts by path (array indexes in numeric order), then by code, and drops duplicates. */
+export declare const finalizeAskErrors: (drafts: readonly AskErrorDraft[]) => AskValidationError[];

package/dist/asks/errors.js

@@ -0,0 +1,364 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.finalizeAskErrors = exports.issuesToAskErrors = exports.quoteValue = exports.askIssue = exports.formatAskPath = exports.ASK_ERROR_CODES = void 0;
+const limits_1 = require("./limits");
+/**
+ * Every ask error code, with its meaning. `validateAskInput` and `validateAskResponse` return all
+ * of them except `UNKNOWN_BUTTON`, which the headless `turn` endpoint returns, and
+ * `FILE_NOT_OWNED`, which the server returns when it loads an uploaded file.
+ */
+exports.ASK_ERROR_CODES = {
+    CHANGED_MISMATCH: "A markdown answer's changed flag does not match whether its text differs from the draft.",
+    DECLINE_NOT_ALLOWED: "The answer skips an ask that does not allow skipping.",
+    DEFAULT_NOT_IN_OPTIONS: "A default names an option id that the ask does not offer.",
+    DUPLICATE_ID: "An id appears twice where ids must be unique: options, default, accept, or an answer.",
+    DUPLICATE_LABEL: "Two buttons would share a label: options of a compact ask, or a confirm's approve and deny.",
+    FIELD_TYPE_MISMATCH: "A form value or default does not fit its field's type: the wrong JSON type, not a whole number, or not a valid email, URL, or phone number.",
+    FILE_COUNT: "A files answer has fewer files than minFiles or more than maxFiles.",
+    FILE_NOT_OWNED: "A files answer names a fileId that is not an upload of the caller, or the host has no file storage.",
+    FILE_TOO_LARGE: "A file is larger than the host's per-file upload cap.",
+    FILE_TYPE_NOT_ACCEPTED: "A file's declared type is not one the ask's accept list allows.",
+    INVALID_DATE: "A form date, time, or datetime value or default is not a real ISO 8601 value in the field's format.",
+    INVALID_ENUM: "A value is not one of the allowed values.",
+    INVALID_FORMAT: "A string does not match its required format.",
+    INVALID_TYPE: "A value has the wrong type.",
+    MIME_MISMATCH: "A file's bytes, or its data URL's media type, do not match the type the answer declares.",
+    MISSING_REQUIRED: "A required field is missing.",
+    OPTION_NOT_OFFERED: "The answer selects an option id that the ask did not offer.",
+    OTHER_NOT_ALLOWED: "An ask or an answer uses Other where the ask does not allow it.",
+    OUT_OF_RANGE: "A form number value or default is below the field's min or above its max.",
+    RANGE_INVALID: "A count or length bound is out of range: below its minimum, above what the ask offers, or a minimum above its maximum.",
+    REQUIRED_FIELD: "A form answer leaves a required field missing or blank.",
+    SELECTION_COUNT: "A default or an answer selects the wrong number of options.",
+    TOO_FEW: "A list has fewer items than allowed.",
+    TOO_LONG: "A string is longer than allowed.",
+    TOO_MANY: "A list has more items than allowed.",
+    TOO_SHORT: "A string is empty, only whitespace, or shorter than its minimum.",
+    UNKNOWN_BUTTON: "The pressed button is not on the pending ask's simple card.",
+    UNKNOWN_KEY: "An object has a field that its schema does not define.",
+};
+const MAX_QUOTED_LENGTH = 40;
+const isAskErrorCode = (value) => typeof value === "string" && Object.hasOwn(exports.ASK_ERROR_CODES, value);
+const formatAskPath = (segments) => segments.reduce((path, segment) => {
+    if (typeof segment === "number") {
+        return `${path}[${segment}]`;
+    }
+    const key = String(segment);
+    return path === "" ? key : `${path}.${key}`;
+}, "");
+exports.formatAskPath = formatAskPath;
+/** A Zod custom issue that carries an ask error code and its fix. */
+const askIssue = ({ code, fix, message, segments, }) => ({ code: "custom", message, params: { askCode: code, fix }, path: [...segments] });
+exports.askIssue = askIssue;
+const quoteValue = (value) => {
+    if (typeof value !== "string") {
+        return String(value);
+    }
+    const shortened = value.length > MAX_QUOTED_LENGTH ? `${value.slice(0, MAX_QUOTED_LENGTH - 1)}…` : value;
+    return JSON.stringify(shortened);
+};
+exports.quoteValue = quoteValue;
+const sentenceSubject = (path) => (path === "" ? "The value" : path);
+const inlineSubject = (path) => (path === "" ? "the value" : path);
+const describeExpected = (expected) => {
+    switch (expected) {
+        case "array":
+        case "tuple":
+            return "a list";
+        case "boolean":
+            return "true or false";
+        case "int":
+            return "a whole number";
+        case "number":
+            return "a number";
+        case "map":
+        case "object":
+        case "record":
+            return "an object";
+        case "string":
+            return "a string";
+        default:
+            return expected;
+    }
+};
+const describeReceived = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "a list";
+    }
+    switch (typeof value) {
+        case "boolean":
+            return "a boolean";
+        case "number":
+            return "a number";
+        case "object":
+            return "an object";
+        case "string":
+            return "a string";
+        default:
+            return typeof value;
+    }
+};
+const isPrimitive = (value) => value === null || ["boolean", "number", "string"].includes(typeof value);
+const lookup = (root, segments) => {
+    let current = root;
+    for (const segment of segments) {
+        if (current === null || typeof current !== "object" || !(segment in current)) {
+            return { found: false, value: undefined };
+        }
+        current = current[segment];
+    }
+    return { found: current !== undefined, value: current };
+};
+const missingRequired = (segments) => {
+    const path = (0, exports.formatAskPath)(segments);
+    const lastSegment = segments.at(-1);
+    if (typeof lastSegment !== "string") {
+        return {
+            code: "MISSING_REQUIRED",
+            fix: `Send ${inlineSubject(path)}.`,
+            message: `${sentenceSubject(path)} is required.`,
+            segments,
+        };
+    }
+    const parentPath = (0, exports.formatAskPath)(segments.slice(0, -1));
+    return {
+        code: "MISSING_REQUIRED",
+        fix: parentPath === "" ? `Add "${lastSegment}".` : `Add "${lastSegment}" to ${parentPath}.`,
+        message: `${path} is required.`,
+        segments,
+    };
+};
+const invalidEnum = (segments, allowed, received) => {
+    const path = (0, exports.formatAskPath)(segments);
+    const allowedText = allowed.length === 1
+        ? (0, exports.quoteValue)(allowed[0])
+        : `one of ${allowed.map((value) => (0, exports.quoteValue)(value)).join(", ")}`;
+    const receivedText = isPrimitive(received) ? `, not ${(0, exports.quoteValue)(received)}` : "";
+    return {
+        code: "INVALID_ENUM",
+        fix: `Use ${allowedText}.`,
+        message: `${sentenceSubject(path)} must be ${allowedText}${receivedText}.`,
+        segments,
+    };
+};
+const tooShort = (segments) => {
+    const path = (0, exports.formatAskPath)(segments);
+    return {
+        code: "TOO_SHORT",
+        fix: `Write at least one visible character in ${inlineSubject(path)}.`,
+        message: `${sentenceSubject(path)} must contain visible text.`,
+        segments,
+    };
+};
+const numberOutOfRange = (segments, bound) => {
+    const path = (0, exports.formatAskPath)(segments);
+    return {
+        code: "RANGE_INVALID",
+        fix: `Make ${inlineSubject(path)} ${bound}.`,
+        message: `${sentenceSubject(path)} must be ${bound}.`,
+        segments,
+    };
+};
+const unionOptions = (issue) => "options" in issue && Array.isArray(issue.options) ? issue.options : [];
+const describeIssue = (issue, root, prefix) => {
+    const segments = [...prefix, ...issue.path];
+    const path = (0, exports.formatAskPath)(segments);
+    const target = lookup(root, issue.path);
+    switch (issue.code) {
+        case "unrecognized_keys":
+            return issue.keys.map((key) => ({
+                code: "UNKNOWN_KEY",
+                fix: `Remove "${key}".`,
+                message: `"${key}" is not a field of ${path === "" ? "this object" : path}.`,
+                segments: [...segments, key],
+            }));
+        case "invalid_type": {
+            if (!target.found) {
+                return [missingRequired(segments)];
+            }
+            const expected = describeExpected(issue.expected);
+            const received = issue.expected === "int" && typeof target.value === "number"
+                ? String(target.value)
+                : describeReceived(target.value);
+            return [
+                {
+                    code: "INVALID_TYPE",
+                    fix: `Make ${inlineSubject(path)} ${expected}.`,
+                    message: `${sentenceSubject(path)} must be ${expected}, not ${received}.`,
+                    segments,
+                },
+            ];
+        }
+        case "invalid_value":
+            if (!target.found) {
+                return [missingRequired(segments)];
+            }
+            return [invalidEnum(segments, issue.values, target.value)];
+        case "invalid_union": {
+            if (!target.found) {
+                return [missingRequired(segments)];
+            }
+            const allowed = unionOptions(issue);
+            if (allowed.length === 0) {
+                return [
+                    {
+                        code: "INVALID_TYPE",
+                        fix: `Check ${inlineSubject(path)}.`,
+                        message: issue.message,
+                        segments,
+                    },
+                ];
+            }
+            return [invalidEnum(segments, allowed, target.value)];
+        }
+        case "too_big": {
+            const maximum = String(issue.maximum);
+            if (issue.origin === "number") {
+                return [numberOutOfRange(segments, `at most ${maximum}`)];
+            }
+            if (issue.origin === "array" || issue.origin === "set") {
+                return [
+                    {
+                        code: "TOO_MANY",
+                        fix: `Remove items from ${inlineSubject(path)} until it has ${maximum} or fewer.`,
+                        message: `${sentenceSubject(path)} has more than ${maximum} items.`,
+                        segments,
+                    },
+                ];
+            }
+            return [
+                {
+                    code: "TOO_LONG",
+                    fix: `Shorten ${inlineSubject(path)} to ${maximum} characters or fewer.`,
+                    message: `${sentenceSubject(path)} is longer than ${maximum} characters.`,
+                    segments,
+                },
+            ];
+        }
+        case "too_small": {
+            if (issue.origin === "number") {
+                return [numberOutOfRange(segments, `at least ${String(issue.minimum)}`)];
+            }
+            if (issue.origin === "array" || issue.origin === "set") {
+                const minimum = String(issue.minimum);
+                return [
+                    {
+                        code: "TOO_FEW",
+                        fix: `Add items to ${inlineSubject(path)} until it has at least ${minimum}.`,
+                        message: `${sentenceSubject(path)} has fewer than ${minimum} items.`,
+                        segments,
+                    },
+                ];
+            }
+            return [tooShort(segments)];
+        }
+        case "invalid_format":
+            if (issue.pattern === String(limits_1.ASK_LIMITS.choice.optionIdPattern)) {
+                const idKind = issue.path.length === 3 && issue.path[0] === "fields" ? "field" : "option";
+                return [
+                    {
+                        code: "INVALID_FORMAT",
+                        fix: `Use 1-${limits_1.ASK_LIMITS.choice.optionIdMaxLength} lowercase letters, digits, "_", or "-", starting with a letter or digit.`,
+                        message: `${sentenceSubject(path)} ${(0, exports.quoteValue)(target.value)} is not a valid ${idKind} id.`,
+                        segments,
+                    },
+                ];
+            }
+            return [
+                {
+                    code: "INVALID_FORMAT",
+                    fix: `Change ${inlineSubject(path)} to match the ${issue.format} format.`,
+                    message: `${sentenceSubject(path)} does not match the ${issue.format} format.`,
+                    segments,
+                },
+            ];
+        case "custom": {
+            const askCode = issue.params?.askCode;
+            const fix = issue.params?.fix;
+            if (askCode === "TOO_SHORT") {
+                return [tooShort(segments)];
+            }
+            if (isAskErrorCode(askCode) && typeof fix === "string") {
+                return [{ code: askCode, fix, message: issue.message, segments }];
+            }
+            return [
+                {
+                    code: "INVALID_FORMAT",
+                    fix: `Check ${inlineSubject(path)}.`,
+                    message: issue.message,
+                    segments,
+                },
+            ];
+        }
+        default:
+            return [
+                {
+                    code: "INVALID_TYPE",
+                    fix: `Check ${inlineSubject(path)}.`,
+                    message: issue.message,
+                    segments,
+                },
+            ];
+    }
+};
+/**
+ * Maps Zod issues to ask errors. `root` is the value that was parsed; it tells a missing key apart
+ * from a key with the wrong type. `prefix` is prepended to every path.
+ */
+const issuesToAskErrors = ({ issues, prefix = [], root, }) => {
+    const typeIssuePaths = new Set(issues
+        .filter((issue) => issue.code === "invalid_type")
+        .map((issue) => (0, exports.formatAskPath)(issue.path)));
+    return issues.flatMap((issue) => {
+        if (issue.code !== "invalid_type" && typeIssuePaths.has((0, exports.formatAskPath)(issue.path))) {
+            return [];
+        }
+        return describeIssue(issue, root, prefix);
+    });
+};
+exports.issuesToAskErrors = issuesToAskErrors;
+const compareStrings = (left, right) => {
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+};
+const compareSegments = (left, right) => {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const a = left[index];
+        const b = right[index];
+        if (a === b) {
+            continue;
+        }
+        if (typeof a === "number" && typeof b === "number") {
+            return a - b;
+        }
+        if (typeof a === "number") {
+            return -1;
+        }
+        if (typeof b === "number") {
+            return 1;
+        }
+        return compareStrings(String(a), String(b));
+    }
+    return left.length - right.length;
+};
+/** Sorts drafts by path (array indexes in numeric order), then by code, and drops duplicates. */
+const finalizeAskErrors = (drafts) => {
+    const sorted = [...drafts].sort((left, right) => compareSegments(left.segments, right.segments) || compareStrings(left.code, right.code));
+    const seen = new Set();
+    return sorted.flatMap((draft) => {
+        const path = (0, exports.formatAskPath)(draft.segments);
+        const key = `${path}\u0000${draft.code}`;
+        if (seen.has(key)) {
+            return [];
+        }
+        seen.add(key);
+        return [{ code: draft.code, fix: draft.fix, message: draft.message, path }];
+    });
+};
+exports.finalizeAskErrors = finalizeAskErrors;

package/dist/asks/files.d.ts

@@ -0,0 +1,53 @@
+import { type AskErrorDraft, type AskValidationError } from "./errors";
+/** What a `files` ask may accept, and the MIME types each value allows. */
+export declare const ASK_FILE_ACCEPT_MIME_TYPES: {
+    readonly csv: readonly ["text/csv"];
+    readonly image: readonly ["image/jpeg", "image/png", "image/gif", "image/webp"];
+    readonly json: readonly ["application/json"];
+    readonly pdf: readonly ["application/pdf"];
+    readonly text: readonly ["text/plain"];
+};
+/** The values of a `files` ask's `accept` list, in the order the docs and prompt list them. */
+export declare const ASK_FILE_ACCEPT: readonly ["image", "pdf", "text", "csv", "json"];
+export type AskFileAccept = (typeof ASK_FILE_ACCEPT)[number];
+export type AskFileMimeType = (typeof ASK_FILE_ACCEPT_MIME_TYPES)[AskFileAccept][number];
+/** The MIME types an `accept` list allows, each listed once, in `accept` order. */
+export declare const acceptedFileMimeTypes: (accept: readonly AskFileAccept[]) => AskFileMimeType[];
+/** Whether a file of this type reaches the model as text rather than as bytes. */
+export declare const isTextFileMimeType: (mimeType: string) => boolean;
+/**
+ * Splits a base64 `data:` URL into its media type (lowercase, without parameters) and payload.
+ * Returns undefined for anything else, including URL-encoded data URLs and remote URLs.
+ */
+export declare const parseAskDataUrl: (url: string) => {
+    base64: string;
+    mediaType: string;
+} | undefined;
+/** The number of bytes a base64 payload decodes to. */
+export declare const base64ByteLength: (base64: string) => number;
+/** What the bytes of a file are: one of the accepted binary types, UTF-8 text, or unknown. */
+export type SniffedFileType = "application/pdf" | "image/gif" | "image/jpeg" | "image/png" | "image/webp" | "text" | "unknown";
+/**
+ * Reads a file's type from its first bytes. Images and PDFs are matched by their signatures;
+ * anything else that is valid UTF-8 with no NUL character is text.
+ */
+export declare const sniffFileBytes: (bytes: Uint8Array) => SniffedFileType;
+export declare const fileTooLargeDraft: ({ maxFileSizeBytes, segments, size, }: {
+    maxFileSizeBytes: number;
+    segments: readonly PropertyKey[];
+    size: number;
+}) => AskErrorDraft;
+/**
+ * Checks the bytes of the file at `content.files[index]` on the server: they must fit the per-file
+ * cap and match the declared MIME type (a JSON file must also parse).
+ */
+export declare const checkAskFileBytes: ({ bytes, index, maxFileSizeBytes, mimeType, }: {
+    bytes: Uint8Array;
+    index: number;
+    maxFileSizeBytes: number;
+    mimeType: string;
+}) => AskValidationError[];
+/** The error for a `fileId` that the caller did not upload, or that the host cannot load. */
+export declare const fileNotOwnedError: ({ index }: {
+    index: number;
+}) => AskValidationError;