@m6d/cortex-cli 0.16.0 → 0.18.0

package/README.md

@@ -135,7 +135,7 @@ after; without it the command says so and names the command. Fields the API
 marks live (`x-live-fields`) take effect without a publish, from agents'
 next turn, and the command names them: a trigger's
 `credentialName`, `fireCredentialName` and model, say, or a dataset host's
-`url`, `credentials` and `timeoutMs`. `cortex datasetHosts sync <id>` reads a host's manifest, and a
+`url`, `headers` and `timeoutMs`. `cortex datasetHosts sync <id>` reads a host's manifest, and a
 draft host publishes only after `datasetHosts test` reached it once.
 
 A procedure the API marks destructive (`x-destructive`: delete, publish, rotate, toggle and the
@@ -200,7 +200,7 @@ openapi: [
     {
         name: "shop",
         url: "https://shop.example.com/openapi.json",
-        credentials: [{ header: "Authorization", prefix: "Bearer ", credential: null }],
+        headers: [{ header: "Authorization", prefix: "Bearer ", from: { kind: "runToken" } }],
         // For an API that wraps every answer: where each one keeps its result.
         // resultPath: "/data",
         pinned: ["findOrder"],
@@ -211,10 +211,11 @@ openapi: [
 ],
 ```
 
-Every apply reads the document first, without the source's credentials. An
+Every apply reads the document first, without the source's headers. An
 operation it adds is created, a changed one updated, and a dropped one
-deleted. A source with credentials is read only over https, or from a host
-the deployment allows, since the document says where they go. A source needs the `tools` write permission even when nothing
+deleted. A source whose headers carry a credential or the run token is read
+only over https, or from a host the deployment allows, since the document
+says where they go. A source needs the `tools` write permission even when nothing
 changes. Each tool is named after its `operationId`, made an identifier of at
 most 64 characters; an operation Cortex cannot import is left
 out. Two operations that come out with one name are told apart by a number
@@ -224,6 +225,39 @@ or any name such a collision decided (`ambiguous_tool`), since a path the
 document adds or drops could move it to another endpoint. It also fails when an
 operation's name is already a listed tool's or another source's.
 
+A collection lists its documents. Each is inline `text`, a file `path`
+relative to the manifest file, or a `url` Cortex reads on every apply, with no
+credentials:
+
+```ts
+collections: [
+    {
+        name: "Policies",
+        audience: { agents: ["support"] },
+        documents: [
+            { name: "faq.md", text: "# FAQ\n\nReturns take 30 days." },
+            { path: "./docs/returns.pdf" },
+            { url: "https://shop.example.com/policies/shipping.html" },
+        ],
+        // overridable: ["documents"],
+    },
+],
+```
+
+A document's name sets its type: `.md`, `.txt`, `.html`, `.htm`, `.pdf` or
+`.docx`. A path or URL document is named after its file unless `name` says
+otherwise. Each is at most 10 MB. `cortex apply` reads paths and sends their
+bytes, so a request carries every inline and path document again; Cortex
+stores only what changed. A document with new bytes replaces the old one,
+which keeps answering until the new one is processed, and one the manifest
+drops is retired.
+
+Listing `documents` makes the manifest own them: an apply retires a document
+uploaded in the console, the first apply after upgrading included, unless
+the collection offers `documents` in `overridable`. Offered, a document
+uploaded or removed in Cortex stays so until the manifest changes that same
+document, which `cortex apply` then asks about.
+
 The manifest is checked against the contract before anything is sent, then
 sent as written, so Cortex fills its own defaults. It goes to the
 management API (`manifests/sync`, or `manifests/preview` with `--dry-run`,
@@ -240,7 +274,7 @@ question, and is required with no terminal to ask on. `--dry-run` never asks.
 References between entries (mentions, service scopes, which role a
 credential or secret plays) are judged on the state the apply leaves, so
 the order the manifest lists them in does not matter. A dataset host's
-credentials are the exception: its catalog is read with them before the
+headers are the exception: its catalog is read with them before the
 apply, so they are judged on the deployment as it stands. A credential a
 trigger fires with cannot go to a host in the same apply that drops
 it; drop it first, then apply again.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.16.0",
+    "version": "0.18.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",

package/src/commands/apply.ts

@@ -202,9 +202,14 @@ async function sendManifest(options: {
     }
 }
 
+/** The field both sides changed, and its part when the field is judged part by part. */
+function conflictField({ field, key }: Conflict) {
+    return key === undefined ? field : `${field} (${key})`;
+}
+
 /** How a conflict reads: its entry and the field both sides changed. */
-function conflictLabel({ kind, name, field }: Conflict) {
-    return `${kind} ${name}: ${field} changed in both places`;
+function conflictLabel(conflict: Conflict) {
+    return `${conflict.kind} ${conflict.name}: ${conflictField(conflict)} changed in both places`;
 }
 
 /** Ends a run that does not ask, naming every conflict and how to run `command` again to answer them. */
@@ -250,8 +255,9 @@ export function findManifest(path: string, command?: string) {
 
 /**
  * The file's default export, checked against the manifest contract here so
- * a mistake is named before anything is sent, then sent as written: Cortex
- * fills its own defaults, which may be newer than this CLI's.
+ * a mistake is named before anything is sent, then sent as written, each
+ * document `path` read from beside the file: Cortex fills its own defaults,
+ * which may be newer than this CLI's.
  */
 export async function loadManifest(path: string, verbose: boolean) {
     const { written, parsed } = await loadManifestFile(path).catch((error: unknown) =>
@@ -288,8 +294,12 @@ function printChanges(
             rows.set(kind, [...(rows.get(kind) ?? []), ...marked]);
         }
     }
-    for (const { kind, name, field } of conflicts) {
-        rows.set(kind, [...(rows.get(kind) ?? []), `! ${name}  ${field} changed in both places`]);
+    for (const conflict of conflicts) {
+        const { kind, name } = conflict;
+        rows.set(kind, [
+            ...(rows.get(kind) ?? []),
+            `! ${name}  ${conflictField(conflict)} changed in both places`,
+        ]);
     }
     for (const [kind, lines] of rows) {
         for (const [index, line] of lines.entries()) {

package/src/commands/setup.ts

@@ -12,7 +12,7 @@ import {
     normalizeHost,
     scrubCredentialStrings,
 } from "@cortex/contracts/egress-policy";
-import { MODEL_PROVIDER_LIMITS, NAME_MAX_LENGTH } from "@cortex/contracts/manifest";
+import { MODEL_PROVIDER_LIMITS, NAME_MAX_LENGTH, SETTING_BOUNDS } from "@cortex/contracts/manifest";
 import { z } from "zod";
 
 import {
@@ -91,6 +91,8 @@ const serverSchema = namedSchema.extend({
     modelProvider: z.string().nullable(),
     modelName: z.string().nullable(),
     modelEffort: z.string().nullable(),
+    signInChecksPerMinute: z.number(),
+    triggerChecksPerMinute: z.number(),
 });
 const chatSchema = z.object({ choices: z.array(z.object({ message: z.object({}) })).min(1) });
 const embeddingsSchema = z.object({
@@ -388,6 +390,8 @@ async function ensureServer(
                 url,
                 keySecretName,
                 ...model,
+                signInChecksPerMinute: SETTING_BOUNDS.server.signInChecksPerMinute.default,
+                triggerChecksPerMinute: SETTING_BOUNDS.server.triggerChecksPerMinute.default,
             }),
         );
         report.input("Server", `${name} · created`);
@@ -413,6 +417,8 @@ async function ensureServer(
                       modelName: server.modelName,
                       modelEffort: server.modelEffort,
                   }),
+            signInChecksPerMinute: server.signInChecksPerMinute,
+            triggerChecksPerMinute: server.triggerChecksPerMinute,
         }),
     );
     report.input("Server", `${name} · updated`);

package/src/contracts/datasets/dataset-sql.ts

@@ -57,8 +57,13 @@ type ParsedDatasetSql = {
 /** A refusal the model can act on. */
 export class DatasetSqlError extends Error {}
 
+/**
+ * `upper` is a word's keyword spelling. A quoted identifier and a word after a
+ * dot (`plans.from`) have none (`""`), so no keyword check matches them and
+ * they always read as names.
+ */
 type Token =
-    | { kind: "word"; value: string; upper: string; quoted?: true }
+    | { kind: "word"; value: string; upper: string }
     | { kind: "string"; value: string }
     | { kind: "number"; value: number }
     | { kind: "punct"; value: string }
@@ -84,6 +89,14 @@ function stringLiteral(sql: string, start: number) {
     }
 }
 
+/** Whether `previous` ends a value, so a minus after it subtracts; after a keyword or an operator it signs the number. */
+function endsValue(previous: Token | undefined) {
+    if (previous === undefined) return false;
+    if (previous.kind === "punct") return previous.value === ")";
+    if (previous.kind !== "word") return true;
+    return ["END", "NULL", "TRUE", "FALSE"].includes(previous.upper) || isName(previous);
+}
+
 /** Reads the token at `i`: a quoted identifier, a number (negative only where a value is expected), a word or punctuation. */
 function lexeme(sql: string, i: number, previous: Token | undefined) {
     const char = sql[i]!;
@@ -92,27 +105,13 @@ function lexeme(sql: string, i: number, previous: Token | undefined) {
         if (close === -1) throw new DatasetSqlError("A quoted identifier is not closed.");
         const value = sql.slice(i + 1, close);
         return {
-            token: {
-                kind: "word",
-                value,
-                upper: value.toUpperCase(),
-                quoted: true,
-            } satisfies Token,
+            token: { kind: "word", value, upper: "" } satisfies Token,
             next: close + 1,
         };
     }
     const rest = sql.slice(i);
     const number = /^-?\d+(\.\d+)?/.exec(rest);
-    // After a value or a closing parenthesis a minus subtracts; after a keyword or an operator it signs the number.
-    const afterValue =
-        previous !== undefined &&
-        (previous.kind === "punct"
-            ? previous.value === ")"
-            : previous.kind === "word"
-              ? ["END", "NULL", "TRUE", "FALSE"].includes(previous.upper) || isName(previous)
-              : true);
-    const signIsOperator = char === "-" && afterValue;
-    if (number && !signIsOperator) {
+    if (number && !(char === "-" && endsValue(previous))) {
         return {
             token: { kind: "number", value: Number(number[0]) } satisfies Token,
             next: i + number[0].length,
@@ -120,8 +119,13 @@ function lexeme(sql: string, i: number, previous: Token | undefined) {
     }
     const word = /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest);
     if (word) {
+        const qualified = previous?.kind === "punct" && previous.value === ".";
         return {
-            token: { kind: "word", value: word[0], upper: word[0].toUpperCase() } satisfies Token,
+            token: {
+                kind: "word",
+                value: word[0],
+                upper: qualified ? "" : word[0].toUpperCase(),
+            } satisfies Token,
             next: i + word[0].length,
         };
     }
@@ -338,12 +342,35 @@ const RESERVED = [
     "END",
 ];
 
+/** Whether a bare word reads as a keyword rather than a name. */
+function isKeyword(upper: string) {
+    return RESERVED.includes(upper) || upper in REFUSED_CLAUSES;
+}
+
 function isName(token: Token): token is Token & { kind: "word" } {
-    if (token.kind !== "word") return false;
-    return (
-        token.quoted === true ||
-        (!RESERVED.includes(token.upper) && !(token.upper in REFUSED_CLAUSES))
-    );
+    return token.kind === "word" && !isKeyword(token.upper);
+}
+
+/** Words that bare read as a value rather than a column. */
+const VALUE_WORDS = ["TRUE", "FALSE", "CURRENT_DATE", "CURRENT_TIMESTAMP"];
+
+/**
+ * A column name as a query writes it: double quoted when bare it would read
+ * as a keyword or a value (`"from"`), so what the model is shown is what it
+ * can send.
+ */
+export function sqlColumnName(name: string) {
+    const upper = name.toUpperCase();
+    return isKeyword(upper) || VALUE_WORDS.includes(upper) ? `"${name}"` : name;
+}
+
+/** `message`, and for a keyword where a column belongs, how to write a column spelled like it. */
+function keywordError(token: Token, message: string) {
+    const hint =
+        token.kind === "word" && isKeyword(token.upper)
+            ? ` ${token.value} is a SQL keyword: write a column of that name as "${token.value}" or dataset.${token.value}.`
+            : "";
+    return new DatasetSqlError(`${message}${hint}`);
 }
 
 /** A unit written as `'month'`, `month` or `MONTH`. */
@@ -971,11 +998,21 @@ class Parser {
             );
         }
         const op = (operator.value === "<>" ? "!=" : operator.value) as DatasetFilterOp;
+        const message = `"${shown} ${operator.value}" needs a value on the right.`;
         if (this.startsTerm()) {
-            return { kind: "cond", left, op, value: { term: this.term("") } } satisfies Predicate;
+            return {
+                kind: "cond",
+                left,
+                op,
+                value: { term: this.term(message) },
+            } satisfies Predicate;
+        }
+        // A keyword here may be a column spelled like one (`x > from`); NULL keeps its own refusal.
+        const next = this.peek();
+        if (next.kind === "word" && next.upper !== "NULL" && isKeyword(next.upper)) {
+            throw keywordError(next, message);
         }
-        const value = this.literal(`"${shown} ${operator.value}" needs a value on the right.`);
-        return { kind: "cond", left, op, value } satisfies Predicate;
+        return { kind: "cond", left, op, value: this.literal(message) } satisfies Predicate;
     }
 
     /** Whether the next tokens are a value expression rather than a literal: a name, `(`, CASE, or a number followed by an operator. */
@@ -1174,10 +1211,10 @@ class Parser {
         return count.value;
     }
 
-    /** `a.b` as one reference; a bare keyword in reference position gets the caller's message. */
+    /** `a.b` as one reference; a bare keyword in reference position gets the caller's message (`keywordError`). */
     private reference(message: string) {
         const token = this.peek();
-        if (!isName(token)) throw new DatasetSqlError(message);
+        if (!isName(token)) throw keywordError(token, message);
         this.take();
         let ref = token.value;
         while (this.optionalPunct(".")) {

package/src/contracts/manifest/index.ts

@@ -70,13 +70,6 @@ export const SETTING_BOUNDS = {
     tool: {
         timeoutMs: { min: 100, max: 120_000, default: 30_000 },
         maxResponseBytes: { min: 1_024, max: 1_048_576, default: 262_144 },
-        rateLimitRequests: { min: 1, max: 10_000, default: 60 },
-        rateLimitWindowSeconds: { min: 1, max: 86_400, default: 60 },
-    },
-    agent: {
-        rateLimitRequests: { min: 1, max: 10_000, default: 60 },
-        rateLimitWindowSeconds: { min: 1, max: 86_400, default: 60 },
-        dailyExecutionQuota: { min: 1, max: 1_000_000, default: 10_000 },
     },
     /** How much of the conversation the agent's model sees. */
     agentContext: {
@@ -95,6 +88,18 @@ export const SETTING_BOUNDS = {
     trigger: { disableAfterFailures: { min: 1, max: 1_000, default: 5 } },
     datasetHost: { timeoutMs: { min: 100, max: 120_000, default: 30_000 } },
     webhook: { timeoutMs: { min: 1_000, max: 30_000, default: 10_000 } },
+    /** The score, a fraction, a new visitor of an anonymous agent needs to get an id. */
+    recaptcha: { minScore: { min: 0.1, max: 0.9, default: 0.5 } },
+    /**
+     * How often Cortex checks a caller for the server, per minute: a sign-in
+     * (a new end-user token it asks the server to verify, or a visitor one
+     * of its anonymous agents gives an id), or a trigger's secret. Anyone
+     * can try either, so each bounds what strangers cost it.
+     */
+    server: {
+        signInChecksPerMinute: { min: 1, max: 100_000, default: 600 },
+        triggerChecksPerMinute: { min: 1, max: 10_000, default: 60 },
+    },
 } as const satisfies Record<string, Record<string, Bounds>>;
 
 /** An integer within `bounds`, their default when left out. */
@@ -112,14 +117,68 @@ export function settingDefaults<TBounds extends Record<string, Bounds>>(bounds:
     ) as SettingValues<TBounds>;
 }
 
+type RateLimitBounds = { max: number; allUsers: number | null; perUser: number | null };
+
+/**
+ * Every rate limit an author sets, in the console and in a manifest alike,
+ * per minute except an agent's tokens, per UTC day. Each holds for all of an
+ * entry's users together and for each user alone, from 1 to `max`, or not
+ * at all (null); a manifest that leaves one out gets the default.
+ */
+export const RATE_LIMITS = {
+    agent: {
+        messagesPerMinute: { max: 10_000, allUsers: 600, perUser: 20 },
+        tokensPerDay: { max: 1_000_000_000_000, allUsers: null, perUser: 1_000_000 },
+    },
+    tool: { callsPerMinute: { max: 10_000, allUsers: 60, perUser: 20 } },
+    datasetHost: { queriesPerMinute: { max: 10_000, allUsers: 60, perUser: 20 } },
+} as const satisfies Record<string, Record<string, RateLimitBounds>>;
+
+/** Whom a rate limit holds for: all of an entry's users together, or each user alone. */
+export const RATE_LIMIT_USERS = ["allUsers", "perUser"] as const;
+export type RateLimitUsers = (typeof RATE_LIMIT_USERS)[number];
+
+/** A group of `RATE_LIMITS`, one value per limit for all users and for each user. */
+export function mapRateLimits<TBounds extends Record<string, RateLimitBounds>, TValue>(
+    bounds: TBounds,
+    value: (bound: RateLimitBounds, users: RateLimitUsers) => TValue,
+) {
+    return Object.fromEntries(
+        RATE_LIMIT_USERS.map((users) => [
+            users,
+            Object.fromEntries(
+                Object.entries(bounds).map(([name, bound]) => [name, value(bound, users)]),
+            ),
+        ]),
+    ) as Record<RateLimitUsers, { [Name in keyof TBounds]: TValue }>;
+}
+
+/** An entry's rate limits as its row holds them; null lifts one. */
+export type RateLimits<TBounds> = Record<
+    RateLimitUsers,
+    { [Name in keyof TBounds]: number | null }
+>;
+
+/** Every limit of a group at its default, as a row that sets none stores them. */
+export function rateLimitDefaults<TBounds extends Record<string, RateLimitBounds>>(
+    bounds: TBounds,
+) {
+    return mapRateLimits(bounds, (bound, users) => bound[users]) satisfies RateLimits<TBounds>;
+}
+
+/** One rate limit as a manifest writes it: null lifts it, and left out it takes its default. */
+function rateLimit(bound: RateLimitBounds, users: RateLimitUsers) {
+    return z.number().int().min(1).max(bound.max).nullable().default(bound[users]);
+}
+
 /**
  * The fields of an entry users may change in Cortex after an apply, each
  * once, from the ones `fields` allows; none when left out. Every other field
  * is the manifest's alone. An apply keeps a live change to a listed field
  * unless the manifest changed that field too (a conflict, see
  * `manifestApplyInputSchema`). Identity, what is fixed at creation, the
- * audience, credentials, and whatever an apply checks against the
- * manifest's own value are never offered.
+ * audience, and whatever an apply checks against the manifest's own value
+ * are never offered.
  */
 function overridable<const TField extends string>(fields: readonly [TField, ...TField[]]) {
     return z
@@ -359,19 +418,25 @@ export function confinesEndpointParams(url: string) {
 const upstreamUrlSchema = z.url({ protocol: /^https?$/ });
 
 /**
- * What a call presents: a header name and the prefix before the value in
- * characters, and how many headers at most (a real upstream wants one or
- * two). The console caps its credential rows at the same.
+ * The headers a call carries: a header name and the prefix before the value
+ * in characters, and how many headers at most. The console caps its header
+ * rows at the same.
  */
-export const CREDENTIAL_LIMITS = { headerLength: 120, prefixLength: 40, presentations: 8 } as const;
+export const HEADER_LIMITS = { headerLength: 120, prefixLength: 40, headers: 8 } as const;
 
 /** An HTTP header field name (RFC 9110 token). */
 export const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+/**
+ * A header value fetch sends: visible ASCII, tab, space and obs-text.
+ * Control characters, and any character past one byte, make fetch throw.
+ */
+export const HEADER_VALUE_PATTERN = /^[\t\x20-\x7e\x80-\xff]*$/;
 const headerNameSchema = z
     .string()
     .trim()
     .min(1)
-    .max(CREDENTIAL_LIMITS.headerLength)
+    .max(HEADER_LIMITS.headerLength)
     .regex(HEADER_NAME_PATTERN);
 
 /** Headers Cortex or fetch fills on every request. Lower-cased. */
@@ -388,20 +453,20 @@ export const transportForbiddenHeaders = [
     "proxy-authorization",
 ] as const;
 
-/** Headers the MCP transport sets on its own requests: no MCP server's credential travels under one. Lower-cased. */
+/** Headers the MCP transport sets on its own requests: no header an MCP server's entry declares travels under one. Lower-cased. */
 export const mcpTransportHeaders = new Set<string>([
     "mcp-session-id",
     "mcp-protocol-version",
     "last-event-id",
 ]);
 
-/** Headers no credential or field may travel under; test lower-cased names. */
+/** Headers no declared header or field may travel under; test lower-cased names. */
 export const transportOwnedHeaders = new Set<string>([
     ...transportSetHeaders,
     ...transportForbiddenHeaders,
 ]);
 
-/** The index of each entry presenting a header an earlier entry already presents, compared case-insensitively. */
+/** The index of each entry declaring a header an earlier entry already declares, compared case-insensitively. */
 function repeatedHeaders(entries: ReadonlyArray<{ header: string }>) {
     const seen = new Set<string>();
     return entries.flatMap((entry, index) => {
@@ -423,18 +488,18 @@ const presentedHeaderSchema = headerNameSchema.refine(
 );
 
 /**
- * What every call carries: each entry a header, what precedes the value in
- * it (`"Bearer "`, say), and the credential by name, as `entry` validates
- * it, at most `CREDENTIAL_LIMITS.presentations` of them. A header is
- * presented once; `repeated` words the refusal of a later one.
+ * The headers every call carries: each entry a header, what precedes the
+ * value in it (`"Bearer "`, say), and where the value comes from, as `entry`
+ * validates it, at most `HEADER_LIMITS.headers` of them. A header is
+ * declared once; `repeated` words the refusal of a later one.
  */
-export function presentationsSchema<TEntry extends z.ZodType<{ header: string }>>(
+export function headerListSchema<TEntry extends z.ZodType<{ header: string }>>(
     entry: TEntry,
     repeated: () => string,
 ) {
     return z
         .array(entry)
-        .max(CREDENTIAL_LIMITS.presentations)
+        .max(HEADER_LIMITS.headers)
         .superRefine((entries, context) => {
             for (const index of repeatedHeaders(entries)) {
                 context.addIssue({
@@ -446,23 +511,71 @@ export function presentationsSchema<TEntry extends z.ZodType<{ header: string }>
         });
 }
 
-/** The presentations a manifest entry declares: no unknown key, an omitted prefix or list empty. */
-function declaredPresentationsSchema<TCredential extends string | null>(
+/** A variable by name: one the agent's server declares, or a built-in (`timezone`, `locale`, `utcTime`). */
+const variableSourceSchema = z.object({
+    kind: z.literal("variable"),
+    name: z.string().trim().min(1).max(64),
+});
+
+/** A credential Cortex holds or acquires, by name. */
+const credentialSourceSchema = z.object({ kind: z.literal("credential"), name: nameSchema });
+
+/** A value written as is. */
+const constantHeaderSourceSchema = z.object({
+    kind: z.literal("constant"),
+    value: z.string().max(4_000),
+});
+
+/**
+ * Where a header's value comes from: a credential, the run's own token (the
+ * end user's in a chat, the trigger's in a firing), a variable, or a
+ * constant. A run token or a variable needs a run; a call without one (a
+ * webhook delivery, a catalog read) presents only credentials and constants.
+ */
+export const headerSourceSchema = z.discriminatedUnion("kind", [
+    credentialSourceSchema,
+    z.object({ kind: z.literal("runToken") }),
+    variableSourceSchema,
+    constantHeaderSourceSchema,
+]);
+export type HeaderSource = z.infer<typeof headerSourceSchema>;
+
+/** The sources a call without a run can present. */
+export const runlessHeaderSourceSchema = z.discriminatedUnion("kind", [
+    credentialSourceSchema,
+    constantHeaderSourceSchema,
+]);
+
+/**
+ * The headers a manifest entry declares: no unknown key, an omitted prefix
+ * or list empty, and a prefix or constant only of what a header can carry
+ * (`HEADER_VALUE_PATTERN`).
+ */
+function declaredHeadersSchema<TSource extends HeaderSource>(
     header: z.ZodString,
-    credential: z.ZodType<TCredential, TCredential>,
+    from: z.ZodType<TSource, TSource>,
 ) {
-    return presentationsSchema(
-        z.strictObject({
-            header,
-            prefix: z.string().max(CREDENTIAL_LIMITS.prefixLength).default(""),
-            credential,
-        }),
-        () => "a header presented twice",
+    return headerListSchema(
+        z
+            .strictObject({
+                header,
+                prefix: z
+                    .string()
+                    .max(HEADER_LIMITS.prefixLength)
+                    .regex(HEADER_VALUE_PATTERN, "a prefix a header cannot carry")
+                    .default(""),
+                from,
+            })
+            .refine(
+                (entry) =>
+                    entry.from.kind !== "constant" || HEADER_VALUE_PATTERN.test(entry.from.value),
+                { path: ["from", "value"], message: "a value a header cannot carry" },
+            ),
+        () => "a header declared twice",
     ).default([]);
 }
 
-/** A credential, or `null` for the run's own token (the end user's in a chat, the trigger's in a firing). */
-const credentialsSchema = declaredPresentationsSchema(presentedHeaderSchema, nameSchema.nullable());
+const headersSchema = declaredHeadersSchema(presentedHeaderSchema, headerSourceSchema);
 
 /**
  * Where Cortex fills a top-level scalar input field from, out of the model's
@@ -470,7 +583,7 @@ const credentialsSchema = declaredPresentationsSchema(presentedHeaderSchema, nam
  * a constant, or the end user's bearer.
  */
 export const fieldSourceSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("variable"), name: z.string().trim().min(1).max(64) }),
+    variableSourceSchema,
     z.object({ kind: z.literal("secret"), name: nameSchema }),
     z.object({
         kind: z.literal("constant"),
@@ -806,6 +919,7 @@ const localizedTextSchema = z.record(
 );
 
 const { tool: toolBounds } = SETTING_BOUNDS;
+const { tool: toolRateLimits, datasetHost: datasetHostRateLimits } = RATE_LIMITS;
 
 /** A `type` tool's input schema, its fields bound only as `TOOL_TYPES` lets the type: filled from a source, placed in the request. */
 function toolInputSchemaOf(type: (typeof TOOL_TYPE_NAMES)[number]) {
@@ -816,30 +930,47 @@ function toolInputSchemaOf(type: (typeof TOOL_TYPE_NAMES)[number]) {
     ]).default(EMPTY_OBJECT);
 }
 
-/** Shared by every tool type; a tool that calls nothing (`client`) has no endpoint, credentials, approval or bound fields. */
+/** What a live write may change on a manifest's tool, and keep through the next apply. */
+const TOOL_OVERRIDABLES = [
+    "description",
+    "timeoutMs",
+    "maxResponseBytes",
+    "rateLimits",
+    "pinned",
+    "tags",
+] as const;
+
+/** The same for a tool that calls an endpoint, whose headers are its own. */
+const CALLED_TOOL_OVERRIDABLES = [...TOOL_OVERRIDABLES, "headers"] as const;
+
+/** Shared by every tool type; a tool that calls nothing (`client`) has no endpoint, headers, approval or bound fields. */
 const toolBaseSchema = z.strictObject({
     ...serverToolSchema.pick({ name: true, description: true }).shape,
     inputSchema: toolInputSchemaOf("client"),
     outputSchema: objectSchema.default(EMPTY_OBJECT),
     timeoutMs: setting(toolBounds.timeoutMs),
     maxResponseBytes: setting(toolBounds.maxResponseBytes),
-    rateLimitRequests: setting(toolBounds.rateLimitRequests),
-    rateLimitWindowSeconds: setting(toolBounds.rateLimitWindowSeconds),
+    rateLimits: z
+        .strictObject({
+            allUsers: z
+                .strictObject({
+                    callsPerMinute: rateLimit(toolRateLimits.callsPerMinute, "allUsers"),
+                })
+                .prefault({}),
+            perUser: z
+                .strictObject({
+                    callsPerMinute: rateLimit(toolRateLimits.callsPerMinute, "perUser"),
+                })
+                .prefault({}),
+        })
+        .prefault({}),
     /** Trims the upstream's answer to what the output schema declares. */
     projectOutput: z.boolean().default(false),
     /** Listed in every turn of every agent the tool reaches, whatever the question. */
     pinned: z.boolean().default(false),
     tags: toolTagsSchema.default([]),
     audience: audienceSchema,
-    overridable: overridable([
-        "description",
-        "timeoutMs",
-        "maxResponseBytes",
-        "rateLimitRequests",
-        "rateLimitWindowSeconds",
-        "pinned",
-        "tags",
-    ]),
+    overridable: overridable(TOOL_OVERRIDABLES),
 });
 
 /** A tool that calls an endpoint; with `requiresApproval`, every call waits for the end user to approve it. */
@@ -848,8 +979,9 @@ const calledToolSchema = toolBaseSchema.extend({
         confinesEndpointParams,
         "a {parameter} outside the path or query",
     ),
-    credentials: credentialsSchema,
+    headers: headersSchema,
     requiresApproval: z.boolean().default(false),
+    overridable: overridable(CALLED_TOOL_OVERRIDABLES),
 });
 
 const manifestToolSchema = z
@@ -891,16 +1023,16 @@ const toolNamesSchema = z.array(serverToolSchema.shape.name).max(500).default([]
  * An OpenAPI document whose operations become HTTP tools this manifest owns.
  * Each apply reads it, imports every operation Cortex supports, keeps those
  * tools in step with the document and deletes the ones it no longer has.
- * Every tool presents `credentials`. A GET call runs at once; any other
+ * Every tool carries the source's `headers`. A GET call runs at once; any other
  * method waits for the end user's approval, unless `approval` names the
  * tool the other way.
  */
 const manifestOpenApiSchema = z.strictObject({
     /** Names the source in what an apply reports. */
     name: nameSchema,
-    /** Where the document is read, with no credentials: OpenAPI 3 or Swagger 2, JSON or YAML. */
+    /** Where the document is read, with no headers: OpenAPI 3 or Swagger 2, JSON or YAML. */
     url: upstreamUrlSchema,
-    credentials: credentialsSchema,
+    headers: headersSchema,
     /** Where every operation's successful response keeps its result, when the API wraps each answer. */
     resultPath: jsonPointerSchema.optional(),
     /** Tools listed in every turn of every agent they reach, whatever the question. */
@@ -913,6 +1045,8 @@ const manifestOpenApiSchema = z.strictObject({
             "a tool both never and always needs approval",
         ),
     audience: audienceSchema,
+    /** What a live write may change on each of the source's tools, and keep through the next apply. */
+    overridable: overridable(CALLED_TOOL_OVERRIDABLES),
 });
 export type ManifestOpenApi = z.input<typeof manifestOpenApiSchema>;
 
@@ -1014,14 +1148,34 @@ const manifestDatasetHostSchema = z
     .strictObject({
         name: datasetIdentifierSchema,
         url: upstreamUrlSchema,
-        credentials: credentialsSchema,
+        headers: headersSchema,
         timeoutMs: setting(SETTING_BOUNDS.datasetHost.timeoutMs),
+        rateLimits: z
+            .strictObject({
+                allUsers: z
+                    .strictObject({
+                        queriesPerMinute: rateLimit(
+                            datasetHostRateLimits.queriesPerMinute,
+                            "allUsers",
+                        ),
+                    })
+                    .prefault({}),
+                perUser: z
+                    .strictObject({
+                        queriesPerMinute: rateLimit(
+                            datasetHostRateLimits.queriesPerMinute,
+                            "perUser",
+                        ),
+                    })
+                    .prefault({}),
+            })
+            .prefault({}),
         /** The datasets the host serves that agents may query. */
         expose: z.array(datasetIdentifierSchema).min(1).max(500),
         /** Among those, the ones listed in every turn, whatever the question. */
         pinned: z.array(datasetIdentifierSchema).max(50).default([]),
         audience: audienceSchema,
-        overridable: overridable(["timeoutMs"]),
+        overridable: overridable(["timeoutMs", "rateLimits", "headers"]),
     })
     .superRefine((host, context) => {
         const unexposed = unexposedPins(host);
@@ -1051,60 +1205,201 @@ const manifestMcpServerSchema = z.strictObject({
     /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
     name: identifierSchema,
     url: upstreamUrlSchema,
-    credentials: declaredPresentationsSchema(
+    headers: declaredHeadersSchema(
         presentedHeaderSchema.refine(
             (name) => !mcpTransportHeaders.has(name.toLowerCase()),
             "a header the MCP transport sets",
         ),
-        nameSchema.nullable(),
+        headerSourceSchema,
     ),
     /** The server's own tool names to offer; empty offers every tool. */
     include: mcpToolNamesSchema.default([]),
     exclude: mcpToolNamesSchema.default([]),
     audience: audienceSchema,
-    overridable: overridable(["include", "exclude"]),
+    overridable: overridable(["include", "exclude", "headers"]),
 });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
 /**
  * Delivers its event to a receiver while it is declared. A delivery carries
- * no run, so every credential it presents is named, and none under the
- * header that names the event.
+ * no run, so its headers come from credentials and constants, and none
+ * travels under the header that names the event.
  */
 const manifestWebhookSchema = z.strictObject({
     name: slugSchema,
     description: z.string().trim().max(500).default(""),
     event: z.enum(SERVER_EVENTS),
     url: upstreamUrlSchema,
-    credentials: declaredPresentationsSchema(
+    headers: declaredHeadersSchema(
         presentedHeaderSchema.refine(
             (name) => name.toLowerCase() !== EVENT_HEADER.toLowerCase(),
             "the header that names the event",
         ),
-        nameSchema,
+        runlessHeaderSourceSchema,
     ),
     timeoutMs: setting(SETTING_BOUNDS.webhook.timeoutMs),
     audience: audienceSchema,
-    overridable: overridable(["description", "timeoutMs"]),
+    overridable: overridable(["description", "timeoutMs", "headers"]),
 });
 export type ManifestWebhook = z.input<typeof manifestWebhookSchema>;
 
-/** A collection's name and description in characters. The console caps its editor at the same. */
-export const COLLECTION_LIMITS = { nameLength: 80, descriptionLength: 2_000 } as const;
+/**
+ * A collection's name and description in characters, and how many documents
+ * a manifest lists in one. The console caps its editor at the same.
+ */
+export const COLLECTION_LIMITS = {
+    nameLength: 80,
+    descriptionLength: 2_000,
+    documents: 100,
+} as const;
+
+/** A knowledge document's name in characters and its size in bytes, however it arrives. */
+export const DOCUMENT_LIMITS = { nameLength: 255, bytes: 10 * 1024 * 1024 } as const;
+
+export const DOCX_MIME_TYPE =
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+/** The content types Cortex parses a knowledge document as. */
+export const DOCUMENT_MIME_TYPES = [
+    "application/pdf",
+    DOCX_MIME_TYPE,
+    "text/markdown",
+    "text/plain",
+    "text/html",
+] as const;
+export type DocumentMimeType = (typeof DOCUMENT_MIME_TYPES)[number];
+
+const mimeTypeByExtension = new Map<string, DocumentMimeType>([
+    ["md", "text/markdown"],
+    ["txt", "text/plain"],
+    ["html", "text/html"],
+    ["htm", "text/html"],
+    ["pdf", "application/pdf"],
+    ["docx", DOCX_MIME_TYPE],
+]);
 
-/** Holds documents, which are uploaded to it apart from the manifest. */
-const manifestCollectionSchema = z.strictObject({
-    name: z.string().trim().min(1).max(COLLECTION_LIMITS.nameLength),
-    description: z.string().trim().max(COLLECTION_LIMITS.descriptionLength).default(""),
-    /** The key of the service every document in the collection belongs to. */
-    service: slugSchema.optional(),
-    /** Whether answers may name its documents; false keeps their names, sections and pages from the model. */
-    citable: z.boolean().default(true),
-    audience: audienceSchema,
-    overridable: overridable(["description"]),
+/** The content type a document is parsed as, from the extension its name ends in; none for any other name. */
+export function documentType(name: string) {
+    const dot = name.lastIndexOf(".");
+    return dot === -1 ? undefined : mimeTypeByExtension.get(name.slice(dot + 1).toLowerCase());
+}
+
+/** How many bytes a base64 string decodes to. */
+function base64Bytes(data: string) {
+    const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+    return (data.length / 4) * 3 - padding;
+}
+
+const documentNameSchema = z.string().trim().min(1).max(DOCUMENT_LIMITS.nameLength);
+
+/** A document written in the manifest itself; its name's extension says how it is parsed. */
+const textDocumentSchema = z.strictObject({
+    name: documentNameSchema,
+    text: z
+        .string()
+        .min(1)
+        .refine(
+            (text) => new TextEncoder().encode(text).byteLength <= DOCUMENT_LIMITS.bytes,
+            `larger than ${DOCUMENT_LIMITS.bytes} bytes`,
+        ),
+});
+
+/** A file `cortex apply` reads, its path relative to the manifest file; named after the file unless `name` says otherwise. */
+const pathDocumentSchema = z.strictObject({
+    path: z.string().trim().min(1),
+    name: documentNameSchema.optional(),
+});
+
+/** A file Cortex reads on every apply, with no credentials; named after the URL's last segment unless `name` says otherwise. */
+const urlDocumentSchema = z.strictObject({
+    url: upstreamUrlSchema,
+    name: documentNameSchema.optional(),
 });
+
+/** A file's bytes in base64, as `cortex apply` sends a `path`. */
+const dataDocumentSchema = z.strictObject({
+    name: documentNameSchema,
+    data: z
+        .base64()
+        .refine(
+            (data) => base64Bytes(data) <= DOCUMENT_LIMITS.bytes,
+            `larger than ${DOCUMENT_LIMITS.bytes} bytes`,
+        ),
+});
+
+/** The name a document goes by: its own, else its file's or its URL's last segment. */
+export function documentName(document: { name?: string; path?: string; url?: string }) {
+    if (document.name !== undefined) return document.name;
+    if (document.path !== undefined) return document.path.split(/[/\\]/).pop() ?? "";
+    const segment = new URL(document.url ?? "", "https://x").pathname.split("/").pop() ?? "";
+    try {
+        return decodeURIComponent(segment);
+    } catch {
+        return segment;
+    }
+}
+
+/** A collection's documents: each name once, and each a name whose extension Cortex parses. */
+function documentsSchema<TDocument extends z.ZodType<Parameters<typeof documentName>[0]>>(
+    document: TDocument,
+) {
+    return z
+        .array(document)
+        .max(COLLECTION_LIMITS.documents)
+        .superRefine((documents, ctx) => {
+            const names = documents.map(documentName);
+            names.forEach((name, index) => {
+                if (documentType(name) === undefined) {
+                    ctx.addIssue({
+                        code: "custom",
+                        path: [index, "name"],
+                        message: "a document's name ends in .md, .txt, .html, .htm, .pdf or .docx",
+                    });
+                } else if (names.indexOf(name) !== index) {
+                    ctx.addIssue({
+                        code: "custom",
+                        path: [index, "name"],
+                        message: "a name repeats",
+                    });
+                }
+            });
+        })
+        .default([]);
+}
+
+/**
+ * Holds documents. Its `documents` are the manifest's: an apply stores what
+ * is new or changed and retires what it no longer lists, unless
+ * `overridable` offers them, and then a document added or removed in
+ * Cortex stays so until the manifest changes that document too.
+ */
+function collectionSchema<TDocument extends z.ZodType<Parameters<typeof documentName>[0]>>(
+    document: TDocument,
+) {
+    return z.strictObject({
+        name: z.string().trim().min(1).max(COLLECTION_LIMITS.nameLength),
+        description: z.string().trim().max(COLLECTION_LIMITS.descriptionLength).default(""),
+        /** The key of the service every document in the collection belongs to. */
+        service: slugSchema.optional(),
+        /** Whether answers may name its documents; false keeps their names, sections and pages from the model. */
+        citable: z.boolean().default(true),
+        documents: documentsSchema(document),
+        audience: audienceSchema,
+        overridable: overridable(["description", "documents"]),
+    });
+}
+
+const manifestDocumentSchema = z.union([textDocumentSchema, pathDocumentSchema, urlDocumentSchema]);
+export type ManifestDocument = z.input<typeof manifestDocumentSchema>;
+
+const manifestCollectionSchema = collectionSchema(manifestDocumentSchema);
 export type ManifestCollection = z.input<typeof manifestCollectionSchema>;
 
+/** A collection as Cortex receives it: each `path` read into `data`. */
+const resolvedCollectionSchema = collectionSchema(
+    z.union([textDocumentSchema, dataDocumentSchema, urlDocumentSchema]),
+);
+
 export const AUTH_JWT_SECRET_ALGORITHMS = ["HS256", "HS384", "HS512"] as const;
 
 const issuerSchema = z.string().trim().min(1).max(2048);
@@ -1131,11 +1426,32 @@ export const agentAuthSchema = z.discriminatedUnion("kind", [
         issuer: issuerSchema,
         audience: tokenAudienceSchema,
     }),
-    z.strictObject({ kind: z.literal("anonymous") }),
+    /**
+     * Each visitor gets an id of their own from Cortex, kept in their
+     * browser. With `recaptcha`, reCAPTCHA Enterprise scores each new
+     * visitor first, and one below `minScore` gets none.
+     */
+    z.strictObject({
+        kind: z.literal("anonymous"),
+        recaptcha: z
+            .strictObject({
+                siteKey: z.string().trim().min(1).max(200),
+                projectId: z.string().trim().min(1).max(200),
+                /** The secret holding a Google Cloud API key allowed to create assessments. */
+                secret: nameSchema,
+                minScore: z
+                    .number()
+                    .min(SETTING_BOUNDS.recaptcha.minScore.min)
+                    .max(SETTING_BOUNDS.recaptcha.minScore.max)
+                    .default(SETTING_BOUNDS.recaptcha.minScore.default),
+            })
+            .optional(),
+    }),
     z.strictObject({ kind: z.literal("server") }),
 ]);
 
-const { agent: agentBounds, agentContext, agentLimits } = SETTING_BOUNDS;
+const { agentContext, agentLimits } = SETTING_BOUNDS;
+const { agent: agentRateLimits } = RATE_LIMITS;
 
 /**
  * How the agent runs; every setting left out keeps its default. The
@@ -1160,9 +1476,22 @@ export const agentSettingsSchema = z.strictObject({
     /** Off, end users cannot message the agent: only its triggers reach it. */
     messageTrigger: z.boolean().default(true),
     defaultLocale: localeSchema.default(BASE_LOCALE),
-    rateLimitRequests: setting(agentBounds.rateLimitRequests),
-    rateLimitWindowSeconds: setting(agentBounds.rateLimitWindowSeconds),
-    dailyExecutionQuota: setting(agentBounds.dailyExecutionQuota),
+    rateLimits: z
+        .strictObject({
+            allUsers: z
+                .strictObject({
+                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
+                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
+                })
+                .prefault({}),
+            perUser: z
+                .strictObject({
+                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
+                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
+                })
+                .prefault({}),
+        })
+        .prefault({}),
     context: z
         .strictObject({
             maxContextTokens: setting(agentContext.maxContextTokens),
@@ -1289,6 +1618,15 @@ export const manifestSchema = z.strictObject({
 /** A manifest as written: every field with a default may be left out. */
 export type Manifest = z.input<typeof manifestSchema>;
 
+/**
+ * A manifest as Cortex receives it: the one written, each document `path`
+ * read into `data` by `cortex apply`, since Cortex cannot read the files
+ * beside it.
+ */
+export const resolvedManifestSchema = manifestSchema.extend({
+    collections: listOf(MANIFEST_NAME_FIELDS.collections, resolvedCollectionSchema),
+});
+
 const manifestKindSchema = z.enum(MANIFEST_KINDS);
 
 /**
@@ -1304,11 +1642,17 @@ export const manifestChangesSchema = z.object({
     delete: namesByKindSchema,
 });
 
-/** A field of one entry that both the manifest and a live write changed since the last apply. */
+/**
+ * A field of one entry that both the manifest and a live write changed since
+ * the last apply. A field holding named parts (an agent's settings, its
+ * greeting and suggestions by locale, a collection's documents by name) is
+ * judged part by part, and `key` names the part.
+ */
 const manifestConflictSchema = z.strictObject({
     kind: manifestKindSchema,
     name: z.string(),
     field: z.string(),
+    key: z.string().optional(),
 });
 
 /** Which value a conflict keeps: the one changed live in Cortex, or the manifest's. */
@@ -1318,9 +1662,10 @@ const conflictSideSchema = z.enum(["live", "manifest"]);
  * What preview and sync take: the manifest, and how its conflicts resolve.
  * A conflict takes its own entry in `resolutions`, else `prefer`; a sync
  * left with one neither answers is refused as `unresolved_conflicts`,
- * naming them. A resolution for a field that no longer conflicts is ignored.
+ * naming them. A resolution answers the conflict with its kind, name, field
+ * and key; one for a field that no longer conflicts is ignored.
  */
-export const manifestApplyInputSchema = manifestSchema.extend({
+export const manifestApplyInputSchema = resolvedManifestSchema.extend({
     prefer: conflictSideSchema.optional(),
     resolutions: z.array(manifestConflictSchema.extend({ keep: conflictSideSchema })).default([]),
 });

package/src/contracts/manifest-file/index.ts

@@ -1,16 +1,68 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { manifestSchema } from "../manifest/index";
+import { isRecord } from "../json/index";
+import { DOCUMENT_LIMITS, documentName, manifestSchema } from "../manifest/index";
 
 /**
  * Imports a manifest file, TypeScript or JSON (Bun imports both), and checks
- * its default export against the contract: `written` is the export as
- * written, for a caller that lets Cortex fill its own defaults, and
- * `parsed` the check. Throws when the file does not import or exports
- * nothing. Kept out of the contract's module, which the browser imports too.
+ * its default export against the contract: `parsed` is the check, and
+ * `written` the export as written, for a caller that lets Cortex fill its
+ * own defaults, with each document `path` read, relative to the file, into
+ * the `data` Cortex takes (`resolvedManifestSchema`). Throws when the file
+ * does not import, exports nothing, or names a document file it cannot
+ * read, that is empty, or that is too large. Kept out of the contract's
+ * module, which the browser imports too.
  */
 export async function loadManifestFile(path: string) {
     const module = (await import(pathToFileURL(path).href)) as { default?: unknown };
     if (module.default === undefined) throw new Error("The module has no default export.");
-    return { written: module.default, parsed: manifestSchema.safeParse(module.default) };
+    const parsed = manifestSchema.safeParse(module.default);
+    return {
+        written: parsed.success
+            ? await readDocuments(module.default, dirname(path))
+            : module.default,
+        parsed,
+    };
+}
+
+/** `written` with every document `path` read from `directory` into `data`. */
+async function readDocuments(written: unknown, directory: string) {
+    if (!isRecord(written) || !Array.isArray(written.collections)) return written;
+    const collections = await Promise.all(
+        written.collections.map(async (collection: unknown) => {
+            if (!isRecord(collection) || !Array.isArray(collection.documents)) return collection;
+            const documents = await Promise.all(
+                collection.documents.map((document: unknown) =>
+                    isRecord(document) && typeof document.path === "string"
+                        ? readDocument(
+                              String(collection.name),
+                              document.path,
+                              document.name,
+                              directory,
+                          )
+                        : document,
+                ),
+            );
+            return { ...collection, documents };
+        }),
+    );
+    return { ...written, collections };
+}
+
+/** One document file as `{ name, data }`, named after the file unless `name` says otherwise. */
+async function readDocument(collection: string, path: string, name: unknown, directory: string) {
+    const where = `Collection ${collection}: ${path}`;
+    const bytes = await readFile(resolve(directory, path)).catch((cause: unknown) => {
+        throw new Error(`${where} could not be read.`, { cause });
+    });
+    if (bytes.byteLength === 0) throw new Error(`${where} is empty.`);
+    if (bytes.byteLength > DOCUMENT_LIMITS.bytes) {
+        throw new Error(`${where} is larger than ${DOCUMENT_LIMITS.bytes} bytes.`);
+    }
+    return {
+        name: documentName({ name: typeof name === "string" ? name : undefined, path }),
+        data: bytes.toString("base64"),
+    };
 }

package/src/contracts/wire/index.ts

@@ -85,8 +85,31 @@ export type AttachmentSummary = {
     description: string | null;
 };
 
-/** The user id every caller shares on an agent that verifies no end user. */
-export const ANONYMOUS_USER_ID = "00000000-0000-0000-0000-000000000000";
+/**
+ * How an anonymous agent's visitors' user ids begin: Cortex issues each
+ * visitor an id of its own, which their browser keeps. No issuer ever mints
+ * a subject shaped like this.
+ */
+export const VISITOR_USER_PREFIX = "visitor:";
+
+/** The reCAPTCHA action a visitor's sign-in runs, which Cortex checks the token was made for. */
+export const VISITOR_RECAPTCHA_ACTION = "cortex_visitor";
+
+/** `POST /visitors`: a visitor's sign-in to an anonymous agent, with a reCAPTCHA token when the agent checks visitors. */
+export type VisitorRequest = { recaptcha?: string };
+
+/** A visitor's token, the bearer of every request after the sign-in. */
+export type VisitorToken = { token: string };
+
+/**
+ * Why a sign-in got no token: the agent checks visitors with reCAPTCHA and
+ * the request carried no token, or one that failed. `siteKey` is the key the
+ * widget runs reCAPTCHA with.
+ */
+export type VisitorRefusal = {
+    error: "recaptcha_required" | "recaptcha_failed";
+    siteKey: string;
+};
 
 export type ThreadSummary = {
     id: string;
@@ -139,8 +162,6 @@ export type ClientToolBinding = {
     toolId: string;
     surface: ToolSurface;
     embedOrigin: string;
-    /** Variables the initiate call's input reads. */
-    variables: string[];
 };
 
 /**

package/src/scaffold/files.ts

@@ -29,7 +29,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.16.0";
+const CORTEX_VERSION = "0.17.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -150,7 +150,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.4.0",
+                "@m6d/cortex": "~0.5.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",
@@ -198,7 +198,7 @@ if (!server) throw new Error("Apply from this project: its .env names the server
         {
             name: "store",
             url: \`\${serverUrl}/datasets\`,
-            credentials: [],
+            headers: [],
             expose: ["orders"],
             pinned: ["orders"],
             audience: { server },
@@ -223,7 +223,7 @@ export default defineManifest({
             name: "Helper",
             server,
             prompt: "You are a helpful assistant. Address the user as {{userName}}.",
-            // No identity provider yet: every caller is one shared identity.
+            // No identity provider yet: each browser is a visitor of its own.
             auth: { kind: "anonymous" },
         },
     ],${datasets ? datasetHosts : ""}