@m6d/cortex-cli 0.12.1 → 0.14.0

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

@@ -0,0 +1,16 @@
+import { pathToFileURL } from "node:url";
+
+import { 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.
+ */
+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) };
+}

package/src/contracts/markdown/index.ts

@@ -1,6 +1,6 @@
 /*
  * CommonMark fence tracking shared by the prompt rich-text pipeline, the
- * widget's streamed-message segmenter, and the server's report stand-ins.
+ * widget's streamed-message segmenter, and Cortex's report stand-ins.
  */
 
 /** A fence delimiter of three or more backticks or tildes, indented at most three spaces, and the rest of its line. */

package/src/contracts/pattern/index.ts

@@ -0,0 +1,276 @@
+// cspell:ignore fefe fff
+import { RE2JS } from "re2js";
+
+/*
+ * A tool input schema's `pattern`: a regular expression JavaScript reads with
+ * no flags, which Cortex matches on RE2 so a value is checked in time linear
+ * in its length. A pattern RE2 cannot match as JavaScript reads it is refused
+ * by Cortex and left out of what the TypeScript SDK exports.
+ *
+ * RE2 matches code points where JavaScript matches UTF-16 units, so the
+ * pattern and every input lift each surrogate unit into a private-use plane,
+ * where it is one code point: RE2 then reads the units JavaScript reads.
+ * Nothing collides there, since a real character in that plane is astral,
+ * arrives as two surrogate units and is lifted in turn.
+ */
+
+/**
+ * What one escape or character in a class stands for, spelled as the inside
+ * of an RE2 class: a single character carries its UTF-16 unit, and an
+ * unescaped `-` is marked as one that may make a range.
+ */
+type Atom = { body: string; char?: number; dash?: boolean };
+
+/** JavaScript's `\s`, its WhiteSpace and LineTerminator characters, as the inside of an RE2 class. */
+const SPACE =
+    "\\x{9}-\\x{d}\\x{20}\\x{a0}\\x{1680}\\x{2000}-\\x{200a}\\x{2028}\\x{2029}\\x{202f}\\x{205f}\\x{3000}\\x{feff}";
+/** Every character `SPACE` leaves out: JavaScript's `\S`. */
+const NON_SPACE =
+    "\\x{0}-\\x{8}\\x{e}-\\x{1f}\\x{21}-\\x{9f}\\x{a1}-\\x{167f}\\x{1681}-\\x{1fff}\\x{200b}-\\x{2027}" +
+    "\\x{202a}-\\x{202e}\\x{2030}-\\x{205e}\\x{2060}-\\x{2fff}\\x{3001}-\\x{fefe}\\x{ff00}-\\x{10ffff}";
+/** The set escapes as JavaScript reads them; RE2's own `\d` and `\w` match, its `\s` holds only ASCII. */
+const SET_ESCAPES = new Map([
+    ["d", "\\d"],
+    ["D", "\\D"],
+    ["w", "\\w"],
+    ["W", "\\W"],
+    ["s", SPACE],
+    ["S", NON_SPACE],
+]);
+/** JavaScript's `.`: every character but a line terminator, where RE2's leaves out only `\n`. */
+const DOT = "[^\\x{a}\\x{d}\\x{2028}\\x{2029}]";
+const CONTROL_ESCAPES = new Map([
+    ["f", 0x0c],
+    ["n", 0x0a],
+    ["r", 0x0d],
+    ["t", 0x09],
+    ["v", 0x0b],
+]);
+const QUANTIFIER = /\{\d+(?:,\d*)?\}/y;
+const SURROGATE = /[\uD800-\uDFFF]/g;
+/** Where surrogate unit `0xd800 + n` is lifted: code point `0xf0000 + n`. */
+const LIFTED_SURROGATES = 0xf0000;
+const HEX = /[0-9A-Fa-f]+/y;
+/** What JavaScript's `[^]` and `[]` hold: every character, and none. */
+const ANY = "[\\x{0}-\\x{10ffff}]";
+const NONE = "[^\\x{0}-\\x{10ffff}]";
+
+/** A thrown error: the pattern holds what RE2 cannot match as JavaScript reads it. */
+function unsupported(what: string): never {
+    throw new Error(`a pattern with ${what}`);
+}
+
+/** A UTF-16 unit as the one code point RE2 reads: a surrogate lifted, any other unit itself. */
+function lifted(unit: number) {
+    return unit >= 0xd800 && unit <= 0xdfff ? LIFTED_SURROGATES + unit - 0xd800 : unit;
+}
+
+/** `input` with every surrogate unit lifted, one code point per UTF-16 unit. */
+function liftedText(input: string) {
+    return input.replace(SURROGATE, (unit) => String.fromCodePoint(lifted(unit.charCodeAt(0))));
+}
+
+/** One UTF-16 unit as RE2 reads it literally, inside a class or out. */
+function literal(unit: number) {
+    const char = lifted(unit);
+    const spelled = String.fromCodePoint(char);
+    return /^[A-Za-z0-9]$/.test(spelled) ? spelled : `\\x{${char.toString(16)}}`;
+}
+
+/**
+ * The units from `from` to `to` as the inside of an RE2 class: the part
+ * among the surrogates, lifted, apart from the parts below and above it.
+ */
+function unitRange(from: number, to: number) {
+    return (
+        [
+            [from, Math.min(to, 0xd7ff)],
+            [Math.max(from, 0xd800), Math.min(to, 0xdfff)],
+            [Math.max(from, 0xe000), to],
+        ] satisfies Array<[number, number]>
+    )
+        .filter(([low, high]) => low <= high)
+        .map(([low, high]) => `${literal(low)}-${literal(high)}`)
+        .join("");
+}
+
+function character(char: number, dash = false) {
+    return { body: literal(char), char, dash };
+}
+
+/**
+ * A class's atoms as the inside of an RE2 class: an unescaped dash between
+ * two characters makes a range, and beside a set escape it is a character,
+ * as JavaScript reads them.
+ */
+function classBody(atoms: Atom[]) {
+    let body = "";
+    for (let index = 0; index < atoms.length; index += 1) {
+        const [from, dash, to] = atoms.slice(index, index + 3);
+        if (!from) break;
+        if (!dash?.dash || !to) {
+            body += from.body;
+            continue;
+        }
+        body +=
+            from.char !== undefined && to.char !== undefined
+                ? unitRange(from.char, to.char)
+                : `${from.body}${dash.body}${to.body}`;
+        index += 2;
+    }
+    return body;
+}
+
+/**
+ * A pattern read left to right as JavaScript reads it with no flags (Annex B
+ * included), written in RE2's syntax; throws on a lookaround, a
+ * backreference, a legacy octal escape, a group modifier or a `\c` without
+ * its letter. It reads UTF-16 units, as JavaScript does. Groups do not
+ * capture: nothing reads them.
+ */
+class Translation {
+    private at = 0;
+
+    public constructor(private readonly pattern: string) {}
+
+    public spell() {
+        let re2 = "";
+        while (this.at < this.pattern.length) re2 += this.term();
+        return re2;
+    }
+
+    private term() {
+        const char = this.pattern[this.at] ?? "";
+        if (char === "\\") return this.escapeOutsideClass();
+        if (char === "[") return this.characterClass();
+        if (char === "(") return this.group();
+        if (char === "{") return this.brace();
+        if (!"|)^$*+?.".includes(char)) return literal(this.unit());
+        this.at += 1;
+        return char === "." ? DOT : char;
+    }
+
+    private escapeOutsideClass() {
+        this.at += 1;
+        const assertion = this.pattern[this.at];
+        if (assertion === "b" || assertion === "B") {
+            this.at += 1;
+            return `\\${assertion}`;
+        }
+        const atom = this.escape(false);
+        return "char" in atom ? atom.body : `[${atom.body}]`;
+    }
+
+    /** The escape after a backslash, which `at` is past; in a class `\b` is a backspace. */
+    private escape(insideClass: boolean) {
+        const next = this.pattern[this.at] ?? unsupported("a trailing backslash");
+        this.at += 1;
+        const set = SET_ESCAPES.get(next);
+        if (set) return { body: set };
+        const control = insideClass && next === "b" ? 0x08 : CONTROL_ESCAPES.get(next);
+        if (control !== undefined) return character(control);
+        if (next === "c") return character(this.controlLetter(insideClass));
+        if (next === "x" || next === "u") {
+            return character(this.hex(next === "x" ? 2 : 4) ?? next.charCodeAt(0));
+        }
+        if (next === "0" && !/^\d$/.test(this.pattern[this.at] ?? "")) return character(0);
+        if (/^[\dk]$/.test(next)) unsupported("a backreference or an octal escape");
+        this.at -= 1;
+        return character(this.unit());
+    }
+
+    /** The control character a `\c` names: a letter, or in a class also a digit or `_`. */
+    private controlLetter(insideClass: boolean) {
+        const letter = this.pattern[this.at] ?? "";
+        if (!(insideClass ? /^\w$/ : /^[A-Za-z]$/).test(letter)) {
+            unsupported("a \\c without its letter");
+        }
+        this.at += 1;
+        return letter.charCodeAt(0) % 32;
+    }
+
+    /** `length` hex digits at `at` as a UTF-16 unit, consumed; undefined when fewer follow. */
+    private hex(length: number) {
+        HEX.lastIndex = this.at;
+        const digits = HEX.exec(this.pattern)?.[0] ?? "";
+        if (digits.length < length) return undefined;
+        this.at += length;
+        return Number.parseInt(digits.slice(0, length), 16);
+    }
+
+    private unit() {
+        const unit = this.pattern.charCodeAt(this.at);
+        if (Number.isNaN(unit)) unsupported("a pattern cut short");
+        this.at += 1;
+        return unit;
+    }
+
+    /**
+     * A class, `at` on its `[`. In JavaScript a `]` always closes one, so
+     * `[]` holds nothing and `[^]` everything.
+     */
+    private characterClass() {
+        this.at += 1;
+        const negated = this.pattern[this.at] === "^";
+        if (negated) this.at += 1;
+        const atoms: Atom[] = [];
+        while (this.pattern[this.at] !== "]") {
+            if (this.at >= this.pattern.length) unsupported("an unclosed class");
+            atoms.push(this.classAtom());
+        }
+        this.at += 1;
+        const body = classBody(atoms);
+        if (!body) return negated ? ANY : NONE;
+        return `[${negated ? "^" : ""}${body}]`;
+    }
+
+    private classAtom() {
+        const char = this.pattern[this.at];
+        this.at += 1;
+        if (char === "\\") return this.escape(true);
+        if (char === "-") return character(0x2d, true);
+        this.at -= 1;
+        return character(this.unit());
+    }
+
+    /** A group's opening as RE2 reads it: every group, named or not, without a capture. */
+    private group() {
+        const opening = this.pattern.slice(this.at, this.at + 4);
+        if (/^\(\?<[^=!]/.test(opening)) {
+            const name = this.pattern.indexOf(">", this.at);
+            if (name < 0) unsupported("an unclosed group name");
+            this.at = name + 1;
+        } else if (opening.startsWith("(?")) {
+            if (!opening.startsWith("(?:")) unsupported("a lookaround or a group modifier");
+            this.at += 3;
+        } else {
+            this.at += 1;
+        }
+        return "(?:";
+    }
+
+    /** A quantifier, or a brace JavaScript reads as a character because it opens none. */
+    private brace() {
+        QUANTIFIER.lastIndex = this.at;
+        const quantifier = QUANTIFIER.exec(this.pattern)?.[0];
+        this.at += quantifier?.length ?? 1;
+        return quantifier ?? literal(0x7b);
+    }
+}
+
+/**
+ * A matcher for a pattern JavaScript compiles, meaning what the pattern
+ * means to JavaScript with no flags, UTF-16 unit for unit; undefined when
+ * RE2 cannot match it so, as for a lookaround, a backreference or a
+ * repetition past 1000. Its `test` runs on RE2, in time linear in the input.
+ * It never calls `new RegExp`, so it works while a caller has replaced that
+ * global.
+ */
+export function linearPattern(pattern: string) {
+    try {
+        const re2 = RE2JS.compile(new Translation(pattern).spell());
+        return { test: (input: string) => re2.test(liftedText(input)) };
+    } catch {
+        return undefined;
+    }
+}

package/src/contracts/server/index.ts

@@ -0,0 +1,349 @@
+import { z } from "zod";
+import { REQUEST_LOCATION_TOOL } from "../client-tools/index";
+import { backendErrorSchema } from "../errors/index";
+import { pendingApprovalSchema, TRIGGER_ANSWER_TOOL_NAME } from "../triggers/index";
+import { isRecord, unescapePointerToken } from "../json/index";
+import { APPROVAL_TITLE_FIELD, LOCALES } from "../wire/index";
+
+/*
+ * The server protocol: what Cortex calls on a customer's backend. `GET /`
+ * answers the manifest (the variables it fills, the native tools it runs,
+ * whether it verifies end-user tokens, the events it hears); the other
+ * routes are the calls behind them. Every request carries the server key as
+ * its bearer, and a run-scoped one also the run's token in
+ * `END_USER_TOKEN_HEADER` when the run has one. A refusal on any route
+ * answers in the backend error envelope.
+ */
+
+/** The run's end-user token, which Cortex forwards verbatim to a tool's backend, a dataset host or the agent's server. */
+export const END_USER_TOKEN_HEADER = "X-End-User-Token";
+
+/** The agent slug Cortex's routes name an agent by. */
+export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
+
+/** An end user's id, as wide as Cortex stores one. */
+export const userIdSchema = z.string().max(255);
+
+/**
+ * An ASCII JavaScript identifier: what a tool name (a `tools.<name>()`
+ * sandbox binding) and a variable name must be, and what a rendered
+ * signature prints bare rather than quoted.
+ */
+export const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+export const localeSchema = z.enum(LOCALES);
+
+/** The value one thread's variable holds: what its server fills, or an operator sets on a test thread. */
+const variableValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+/** One thread's variable values, by name. */
+export const variableValuesSchema = z.record(z.string(), variableValueSchema);
+
+/**
+ * A variable an agent's text and tool inputs may read: one its server
+ * declares, or one Cortex computes. The console offers exactly these, in
+ * prompts and as tool input sources alike.
+ */
+export const variableDeclarationSchema = z.object({
+    name: z.string().regex(IDENTIFIER_PATTERN).max(64),
+    description: z.string().max(500),
+    example: z.string().max(200),
+    /** The type its value takes. */
+    type: z.enum(["string", "number", "boolean"]),
+    /** Computed by Cortex for every thread; no server can set it. */
+    computed: z.boolean(),
+});
+export type VariableDeclaration = z.infer<typeof variableDeclarationSchema>;
+
+/**
+ * The variables Cortex computes for every thread, listed first among a
+ * server's variables so the console offers them like any declared one.
+ */
+export const BUILT_IN_VARIABLES = [
+    {
+        name: "utcTime",
+        description: "Current time in UTC (ISO 8601)",
+        example: "2026-09-12T08:30:00Z",
+        type: "string",
+        computed: true,
+    },
+    {
+        name: "locale",
+        description: "Resolved locale of the session",
+        example: "ar",
+        type: "string",
+        computed: true,
+    },
+    {
+        name: "timezone",
+        description: "The user's IANA time zone, as the widget reports it",
+        example: "Asia/Riyadh",
+        type: "string",
+        computed: true,
+    },
+] as const satisfies ReadonlyArray<VariableDeclaration>;
+
+/**
+ * The names of Cortex's built-in tools. No other tool may take one: the
+ * model would see two tools under one name. The .NET SDK holds its own copy,
+ * checked against `reserved-names.fixtures.json`.
+ */
+export const BUILT_IN_TOOL_NAMES = [
+    "describeDataset",
+    "executeCode",
+    "fetchImage",
+    "loadSkill",
+    "queryDataset",
+    "readAttachment",
+    "readReport",
+    "searchKnowledge",
+    "searchServices",
+    "searchThreadHistory",
+    "searchTools",
+    REQUEST_LOCATION_TOOL,
+    TRIGGER_ANSWER_TOOL_NAME,
+] as const;
+
+export function isBuiltInToolName(name: string) {
+    return BUILT_IN_TOOL_NAMES.some((builtIn) => builtIn === name);
+}
+
+/** The longest name a tool takes, a server's or one defined in Cortex. */
+export const TOOL_NAME_MAX_LENGTH = 64;
+
+/** A tool name, a server's or one defined in Cortex: an identifier no built-in tool holds. */
+const declaredToolNameSchema = z
+    .string()
+    .regex(IDENTIFIER_PATTERN)
+    .max(TOOL_NAME_MAX_LENGTH)
+    .refine((name) => !isBuiltInToolName(name), "the name of a built-in tool");
+
+const jsonSchemaSchema = z.record(z.string(), z.unknown());
+
+/** A variable the server fills for its agents' threads; the built-in ones are Cortex's. */
+const serverVariableSchema = z.object({
+    name: z
+        .string()
+        .regex(IDENTIFIER_PATTERN)
+        .max(64)
+        .refine(
+            (name) => !BUILT_IN_VARIABLES.some((builtIn) => builtIn.name === name),
+            "the name of a built-in variable",
+        ),
+    description: z.string().max(500),
+    example: z.string().max(200),
+    type: variableDeclarationSchema.shape.type,
+});
+export type ServerVariable = z.infer<typeof serverVariableSchema>;
+
+/**
+ * A tool the server runs. Its input is an object, the `input` its calls
+ * carry. `requiresApproval` parks every call for the end user's approval;
+ * such a tool's input cannot declare `APPROVAL_TITLE_FIELD`, which the
+ * model fills for the approval card.
+ */
+export const serverToolSchema = z.object({
+    name: declaredToolNameSchema,
+    description: z.string().trim().min(1).max(500),
+    inputSchema: jsonSchemaSchema.refine(
+        (schema) => schema.type === "object",
+        "a tool's input is an object",
+    ),
+    outputSchema: jsonSchemaSchema.optional(),
+    readOnly: z.boolean(),
+    requiresApproval: z.boolean().optional(),
+});
+export type ServerTool = z.infer<typeof serverToolSchema>;
+
+/** The events a server hears at `POST /events/:event`, and a webhook delivers. */
+export const SERVER_EVENTS = ["approval_requested"] as const;
+
+/** The header a webhook delivery names its event in, so a receiver tells events apart without parsing the body. */
+export const EVENT_HEADER = "X-Cortex-Event";
+
+/**
+ * A run parked on server tools that need the end user's approval, as every
+ * receiver hears of it: a webhook's body and the agent's server's event are
+ * this one object. `firingId` and `triggerName` are set when a trigger
+ * started the run, which is what a receiver answering through the firing
+ * route needs. Every parked call is named; one whose input would carry the
+ * event past `SERVER_REQUEST_MAX_BYTES` comes without its input.
+ */
+export const approvalRequestedEventSchema = z.object({
+    event: z.literal("approval_requested"),
+    agentSlug: agentSlugSchema,
+    agentId: z.uuid(),
+    threadId: z.string(),
+    runId: z.string(),
+    userId: z.string(),
+    firingId: z.uuid().optional(),
+    triggerName: z.string().optional(),
+    approvals: z.array(pendingApprovalSchema.partial({ input: true })),
+    occurredAt: z.iso.datetime(),
+});
+export type ApprovalRequestedEvent = z.infer<typeof approvalRequestedEventSchema>;
+
+/** A JSON Pointer token as a key: percent-decoded, then unescaped; undefined when its encoding is broken. */
+function pointerKey(token: string) {
+    try {
+        return unescapePointerToken(decodeURIComponent(token));
+    } catch {
+        return undefined;
+    }
+}
+
+/** What a local `$ref` (`#/$defs/order`) points at in `root`, read as the input compiler reads it; undefined for any other. */
+function pointedAt(root: unknown, ref: string) {
+    if (!ref.startsWith("#")) return undefined;
+    let node = root;
+    for (const token of ref.slice(1).split("/").slice(1)) {
+        const key = pointerKey(token);
+        node =
+            key !== undefined && (isRecord(node) || Array.isArray(node))
+                ? new Map<string, unknown>(Object.entries(node)).get(key)
+                : undefined;
+    }
+    return node;
+}
+
+/** Whether one schema node names `APPROVAL_TITLE_FIELD` as a property or a required field. */
+function namesApprovalTitle(node: Record<string, unknown>) {
+    const required: unknown = node.required;
+    return (
+        (isRecord(node.properties) && Object.hasOwn(node.properties, APPROVAL_TITLE_FIELD)) ||
+        (Array.isArray(required) && required.includes(APPROVAL_TITLE_FIELD))
+    );
+}
+
+/** What describes the same object as `node`: its `allOf`, `anyOf` and `oneOf` members, and what its local `$ref` points at in `root`. */
+function sameObjectSchemas(node: Record<string, unknown>, root: unknown) {
+    const schemas: unknown[] = typeof node.$ref === "string" ? [pointedAt(root, node.$ref)] : [];
+    for (const keyword of ["allOf", "anyOf", "oneOf"]) {
+        const members: unknown = node[keyword];
+        if (!Array.isArray(members)) continue;
+        const listed: unknown[] = members;
+        schemas.push(...listed);
+    }
+    return schemas;
+}
+
+/**
+ * Every node that describes the same object as an input schema's root: the
+ * root, and what `sameObjectSchemas` reaches from it at any depth, each once.
+ */
+function sameObjectNodes(inputSchema: unknown) {
+    const nodes = new Array<Record<string, unknown>>();
+    const pending = [inputSchema];
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (!isRecord(node) || nodes.includes(node)) continue;
+        nodes.push(node);
+        pending.push(...sameObjectSchemas(node, inputSchema));
+    }
+    return nodes;
+}
+
+/** Whether one schema node is closed to properties it does not declare. */
+function closed(node: Record<string, unknown>) {
+    return node.additionalProperties === false || node.unevaluatedProperties === false;
+}
+
+/**
+ * Whether an input schema leaves no room for `APPROVAL_TITLE_FIELD`, which
+ * Cortex adds to the root of a tool that needs approval: a node describing
+ * the input names it, or one besides the root is closed to it, so a strict
+ * reading of the schema could not take the title.
+ */
+export function blocksApprovalTitle(inputSchema: unknown) {
+    return sameObjectNodes(inputSchema).some(
+        (node) => namesApprovalTitle(node) || (node !== inputSchema && closed(node)),
+    );
+}
+
+/** Refuses, under `path`, a tool that needs approval whose input `blocksApprovalTitle`. */
+export function refuseBlockedApprovalTitle(
+    tool: { requiresApproval?: boolean; inputSchema: unknown },
+    context: z.RefinementCtx,
+    path: Array<string | number>,
+) {
+    if (!tool.requiresApproval || !blocksApprovalTitle(tool.inputSchema)) return;
+    context.addIssue({
+        code: "custom",
+        path: [...path, "inputSchema"],
+        message: `a tool that needs approval cannot take an input named ${APPROVAL_TITLE_FIELD}, nor one a closed sub-schema describes: Cortex adds the approval card's title to it`,
+    });
+}
+
+function uniqueNames(entries: ReadonlyArray<{ name: string }>) {
+    return new Set(entries.map((entry) => entry.name)).size === entries.length;
+}
+
+/** `GET /`: everything the server offers, keyed by `version`, which changes whenever anything else does. */
+export const serverManifestSchema = z.object({
+    version: z.string().min(1).max(128),
+    variables: z.array(serverVariableSchema).max(100).refine(uniqueNames, "variable names repeat"),
+    tools: z
+        .array(serverToolSchema)
+        .max(500)
+        .refine(uniqueNames, "tool names repeat")
+        .superRefine((tools, context) => {
+            tools.forEach((tool, index) => refuseBlockedApprovalTitle(tool, context, [index]));
+        }),
+    verify: z.boolean(),
+    events: z.array(z.enum(SERVER_EVENTS)),
+});
+export type ServerManifest = z.infer<typeof serverManifestSchema>;
+
+/** The agent a call is for. */
+const agentSchema = z.object({ id: z.uuid(), slug: agentSlugSchema });
+
+/** The end user a run acts for, as their token was verified; null for a trigger's run. */
+const serverUserSchema = z
+    .object({ id: userIdSchema, claims: z.record(z.string(), z.unknown()) })
+    .nullable();
+
+/** `POST /variables`: the values one thread runs with, asked once per thread. */
+export const variablesRequestSchema = z.object({
+    agent: agentSchema,
+    thread: z.object({ id: z.string() }),
+    user: serverUserSchema,
+    trigger: z.object({ name: z.string() }).optional(),
+});
+export type VariablesRequest = z.infer<typeof variablesRequestSchema>;
+
+export const variablesResponseSchema = z.object({ values: variableValuesSchema });
+export type VariablesResponse = z.infer<typeof variablesResponseSchema>;
+
+/** `POST /tools/:name`: one call, with the variables it runs with. */
+export const toolRequestSchema = z.object({
+    input: z.record(z.string(), z.unknown()),
+    context: variablesRequestSchema.pick({ agent: true, thread: true, user: true }).extend({
+        variables: z.record(z.string(), z.unknown()),
+    }),
+});
+export type ToolRequest = z.infer<typeof toolRequestSchema>;
+
+/**
+ * The largest request body a server takes, and so the largest one Cortex
+ * sends: room for a tool call's input of up to 256 KiB with the variables
+ * and claims it carries.
+ */
+export const SERVER_REQUEST_MAX_BYTES = 4 * 1024 * 1024;
+
+/** What a tool call answers: its output, or a refusal in the backend error envelope. */
+export const toolResponseSchema = z.union([backendErrorSchema, z.object({ output: z.json() })]);
+
+/** `POST /verify`: whose end-user token this is; `sub: null` refuses it. */
+export const verifyRequestSchema = z.object({ token: z.string().min(1) });
+export type VerifyRequest = z.infer<typeof verifyRequestSchema>;
+export const verifyResponseSchema = z.union([
+    z.object({ sub: userIdSchema.min(1), claims: z.record(z.string(), z.unknown()) }),
+    z.object({ sub: z.null() }),
+]);
+export type VerifyResponse = z.infer<typeof verifyResponseSchema>;
+
+/** `POST /events/:event`: the body of each event a manifest subscribes to. */
+export const serverEventSchemas = {
+    approval_requested: approvalRequestedEventSchema,
+} as const satisfies Record<(typeof SERVER_EVENTS)[number], z.ZodType>;

package/src/contracts/server/reserved-names.fixtures.json

@@ -0,0 +1,18 @@
+{
+    "tools": [
+        "describeDataset",
+        "executeCode",
+        "fetchImage",
+        "loadSkill",
+        "queryDataset",
+        "readAttachment",
+        "readReport",
+        "searchKnowledge",
+        "searchServices",
+        "searchThreadHistory",
+        "searchTools",
+        "requestLocation",
+        "submitAnswer"
+    ],
+    "variables": ["utcTime", "locale", "timezone"]
+}