@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/contracts/manifest/index.ts

@@ -0,0 +1,973 @@
+import { z } from "zod";
+import { datasetIdentifierSchema } from "../datasets/index";
+import { canCarrySecret } from "../egress-policy/index";
+import {
+    agentSlugSchema,
+    EVENT_HEADER,
+    IDENTIFIER_PATTERN,
+    localeSchema,
+    SERVER_EVENTS,
+    refuseBlockedApprovalTitle,
+    serverToolSchema,
+} from "../server/index";
+import { MESSAGE_TRIGGER_NAME } from "../triggers/index";
+import {
+    DEFAULT_MEDIA_FORMS,
+    MEDIA_FORMS,
+    TOOL_SURFACES,
+    type Greeting,
+    type Suggestions,
+} from "../wire/index";
+
+/*
+ * A manifest: the agents and components a code-first deployment declares,
+ * written by hand (`cortex.manifest.ts` or JSON) and applied in one
+ * transaction. Everything it points at, it names: a server, a model
+ * provider, a service by its key, an agent by its slug, and a stored secret
+ * or credential by the noun of what it names (`secret: "signing-key"`,
+ * `credential: "petstore"`). A tool input field's `x-source` is the one
+ * exception: `inputSchema` is the JSON Schema the tool stores, verbatim, so
+ * a secret there is `{ kind: "secret", name }`. No secret value ever
+ * appears in one. Prompts, skill bodies and trigger instructions mention a
+ * tool as `@[name]` and a skill as `/[name]`. Each kind's fields mirror what
+ * the console edits, and every bound and check below is Cortex's own, so
+ * Cortex accepts what this contract accepts, short of what only the
+ * deployment can judge: the variables a server declares, the names it
+ * holds, the egress policy, and a SOAP envelope's XML.
+ */
+
+/** The HTTP methods a tool calls its endpoint with. */
+export const TOOL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+
+/**
+ * How the executor folds an upstream body that is not a JSON object into the
+ * object the output schema describes: a top-level array becomes `{ items }`,
+ * a scalar becomes `{ value }`.
+ */
+export const RESPONSE_WRAPS = ["items", "value"] as const;
+
+export const SOAP_VERSIONS = ["1.1", "1.2"] as const;
+
+type Bounds = { min: number; max: number; default: number };
+
+/**
+ * The range of every number an author sets, in the console and in a
+ * manifest alike, and the value a manifest that leaves one out gets. The
+ * console builds its form schemas, with its own messages, from these.
+ */
+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: {
+        maxContextTokens: { min: 4_000, max: 2_000_000, default: 120_000 },
+        /** A fraction of `maxContextTokens`, the one bound that is not an integer. */
+        summarizationThreshold: { min: 0.1, max: 0.95, default: 0.75 },
+        toolResultMaxTokens: { min: 500, max: 200_000, default: 10_000 },
+        recentMessagesToKeep: { min: 0, max: 100, default: 6 },
+    },
+    /** What Cortex's retrieval and tool gateway allow the agent. */
+    agentLimits: {
+        resolveTokenBudget: { min: 500, max: 64_000, default: 4_000 },
+        executeTimeoutMs: { min: 1_000, max: 300_000, default: 30_000 },
+        maxResponseBytes: { min: 1_024, max: 1_048_576, default: 262_144 },
+    },
+    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 } },
+} as const satisfies Record<string, Record<string, Bounds>>;
+
+/** An integer within `bounds`, their default when left out. */
+function setting({ min, max, default: fallback }: Bounds) {
+    return z.number().int().min(min).max(max).default(fallback);
+}
+
+/** Consumer-facing slugs: the manifest id, service keys, skill names and trigger names share it. */
+export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const slugSchema = z.string().regex(SLUG_PATTERN).max(64);
+
+/** A DNS host name in lower case, the way `URL` reports one: dot-separated labels of letters, digits and inner hyphens. */
+export const HOSTNAME_PATTERN =
+    /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+
+/** At most this many hosts an agent's `fetchImage` tool pulls images from. */
+export const FETCH_IMAGE_HOSTS_LIMIT = 20;
+
+/**
+ * The widget's landing-page prompt chips, per locale: a short title the chip
+ * shows and the prompt it sends when clicked. The console stores this exact
+ * shape too, so the widget never sees a blank or unbounded chip. Pure
+ * validation, no transforms: a value that passes is served verbatim, so each
+ * source trims before it stores.
+ */
+export const SUGGESTION_LIMITS = { perLocale: 6, titleLength: 120, promptLength: 2000 } as const;
+const trimmedText = (max: number) =>
+    z
+        .string()
+        .min(1)
+        .max(max)
+        .refine((text) => text === text.trim(), "text has surrounding whitespace");
+const suggestionsSchema = z.record(
+    localeSchema,
+    z
+        .array(
+            z.object({
+                title: trimmedText(SUGGESTION_LIMITS.titleLength),
+                prompt: trimmedText(SUGGESTION_LIMITS.promptLength),
+            }),
+        )
+        .max(SUGGESTION_LIMITS.perLocale),
+) satisfies z.ZodType<Suggestions>;
+
+export const GREETING_MAX_LENGTH = 200;
+/**
+ * The blank-chat landing's headline per locale. Empty means the widget's
+ * built-in default for that locale; like suggestions, served verbatim.
+ */
+const greetingSchema = z.record(
+    localeSchema,
+    z
+        .string()
+        .max(GREETING_MAX_LENGTH)
+        .refine((text) => text === text.trim(), "greeting has surrounding whitespace"),
+) satisfies z.ZodType<Greeting>;
+
+/**
+ * A tool's search tags. The console edits them as comma-separated entries,
+ * so no tag holds a comma.
+ */
+export const toolTagsSchema = z
+    .array(
+        z
+            .string()
+            .trim()
+            .min(1)
+            .max(60)
+            .regex(/^[^,]*$/, "a tag holds no comma"),
+    )
+    .max(20);
+
+/** https, or plain http on loopback for development. */
+const tlsUrlSchema = z.url().refine((url) => canCarrySecret(url, []));
+
+/**
+ * The origin an embedded tool's page is served from, normalized to a bare
+ * origin: it is what the widget compares postMessage events against. The
+ * browser dials it, so no host the egress policy admits counts.
+ */
+export const embedOriginSchema = tlsUrlSchema.transform((value) => new URL(value).origin);
+
+/**
+ * SOAPAction becomes a quoted HTTP header value verbatim: quotes,
+ * backslashes, and control characters would break the header syntax.
+ */
+export const soapActionSchema = z.string().regex(/^[^"\\\u0000-\u001f\u007f]*$/);
+
+/** An envelope template: XML, so never only whitespace. */
+const envelopeTemplateSchema = z.string().refine((template) => template.trim().length > 0);
+
+/**
+ * The per-type payload a tool stores and publishes. Soap: the envelope
+ * template is the full request XML with `{{field}}` placeholders bound to
+ * scalar input fields plus the reserved `{{token}}`, which `tokenCall`
+ * acquires once per request.
+ */
+export const toolConfigByType = {
+    http: z.object({ responseWrap: z.enum(RESPONSE_WRAPS).optional() }),
+    embedded: z.object({ embedOrigin: embedOriginSchema, surface: z.enum(TOOL_SURFACES) }),
+    soap: z.object({
+        soapVersion: z.enum(SOAP_VERSIONS),
+        soapAction: soapActionSchema,
+        envelopeTemplate: envelopeTemplateSchema,
+        tokenCall: z
+            .object({
+                envelopeTemplate: envelopeTemplateSchema,
+                soapAction: soapActionSchema,
+                tokenPath: z.string().trim().min(1),
+            })
+            .optional(),
+    }),
+    /** Its server's URL and key are read off the server row on every call. */
+    native: z.object({}),
+    client: z.object({}),
+};
+
+/** A `{name}` parameter in a tool's endpoint URL, filled from the input on each call. */
+export const ENDPOINT_PARAM_PATTERN = /\{([^{}]+)\}/g;
+
+/**
+ * Whether every `{name}` parameter in a tool's endpoint URL sits in its path
+ * or query. One in the scheme, user info, host, port or fragment would let
+ * the call's input choose where the request and its credentials go.
+ */
+export function confinesEndpointParams(url: string) {
+    const origin = /^[^:/?#]*:[/\\]*[^/\\?#]*/.exec(url)?.[0] ?? "";
+    const hash = url.indexOf("#", origin.length);
+    const fragment = hash < 0 ? "" : url.slice(hash);
+    return ![origin, fragment].some((part) => part.match(ENDPOINT_PARAM_PATTERN));
+}
+
+/** An upstream Cortex calls: http or https. */
+const upstreamUrlSchema = z.url({ protocol: /^https?$/ });
+
+/** An HTTP header field name (RFC 9110 token). */
+export const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const headerNameSchema = z.string().trim().min(1).max(120).regex(HEADER_NAME_PATTERN);
+
+/** Headers Cortex or fetch fills on every request. Lower-cased. */
+export const transportSetHeaders = ["accept", "content-type", "content-length", "host"] as const;
+
+/** Headers fetch refuses to send on anyone's behalf. Lower-cased. */
+export const transportForbiddenHeaders = [
+    "connection",
+    "transfer-encoding",
+    "upgrade",
+    "expect",
+    "te",
+    "trailer",
+    "proxy-authorization",
+] as const;
+
+/** Headers the MCP transport sets on its own requests: no MCP server's credential 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. */
+export const transportOwnedHeaders = new Set<string>([
+    ...transportSetHeaders,
+    ...transportForbiddenHeaders,
+]);
+
+/** At most this many headers a call presents; a real upstream wants one or two. */
+export const CREDENTIAL_PRESENTATION_LIMIT = 8;
+
+/** The index of each entry presenting a header an earlier entry already presents, compared case-insensitively. */
+export function repeatedHeaders(entries: ReadonlyArray<{ header: string }>) {
+    const seen = new Set<string>();
+    return entries.flatMap((entry, index) => {
+        const name = entry.header.toLowerCase();
+        const repeated = seen.has(name);
+        seen.add(name);
+        return repeated ? [index] : [];
+    });
+}
+
+/** A server, model provider, credential or secret, by the name Cortex holds it under. */
+const nameSchema = z.string().trim().min(1).max(120);
+
+const presentedHeaderSchema = headerNameSchema.refine(
+    (name) => !transportOwnedHeaders.has(name.toLowerCase()),
+    "a header the transport sets",
+);
+
+/**
+ * What every call carries: each entry a header, what precedes the value in
+ * it (`"Bearer "`, say), and the credential by name. A header is presented
+ * once.
+ */
+function presentationsSchema<TCredential extends string | null>(
+    header: z.ZodString,
+    credential: z.ZodType<TCredential, TCredential>,
+) {
+    return z
+        .array(z.strictObject({ header, prefix: z.string().max(40).default(""), credential }))
+        .max(CREDENTIAL_PRESENTATION_LIMIT)
+        .superRefine((entries, context) => {
+            for (const index of repeatedHeaders(entries)) {
+                context.addIssue({
+                    code: "custom",
+                    path: [index, "header"],
+                    message: "a header presented 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 = presentationsSchema(presentedHeaderSchema, nameSchema.nullable());
+
+/**
+ * Where Cortex fills a top-level scalar input field from, out of the model's
+ * hands: one of the variables the agent's server declares, a stored secret,
+ * 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) }),
+    z.object({ kind: z.literal("secret"), name: z.string().trim().min(1).max(120) }),
+    z.object({
+        kind: z.literal("constant"),
+        value: z.union([z.string().max(4_000), z.number(), z.boolean()]),
+    }),
+    z.object({ kind: z.literal("endUserToken") }),
+]);
+export type FieldSource = z.infer<typeof fieldSourceSchema>;
+
+/**
+ * Whether `source` can fill a field of `type` (and `enum`, for a string
+ * listing its values): a stored secret or the end user's token fills a
+ * string only, and a constant must be a value of the field's type. Whether a
+ * variable is declared is the agent's server's to say.
+ */
+export function sourceFits(
+    source: FieldSource,
+    field: { type: unknown; enum?: ReadonlyArray<string | null> },
+) {
+    switch (source.kind) {
+        case "variable":
+            return true;
+        case "secret":
+        case "endUserToken":
+            return field.type === "string";
+        case "constant": {
+            const { value } = source;
+            if (field.enum) return typeof value === "string" && field.enum.includes(value);
+            if (field.type === "boolean") return typeof value === "boolean";
+            if (field.type === "number") return typeof value === "number" && Number.isFinite(value);
+            if (field.type === "integer") return Number.isInteger(value);
+            return field.type === "string" && typeof value === "string";
+        }
+    }
+}
+
+/**
+ * Where a top-level scalar input field travels in the upstream request;
+ * absent, path placeholders by name, then the query string on GET and the
+ * body otherwise. `name` renames a query parameter, header or cookie on the
+ * wire.
+ */
+export const fieldTargetSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("body") }),
+    z.object({ kind: z.literal("query"), name: z.string().trim().min(1).max(120).optional() }),
+    z.object({ kind: z.literal("path") }),
+    z.object({ kind: z.literal("header"), name: headerNameSchema.optional() }),
+    z.object({ kind: z.literal("cookie"), name: headerNameSchema.optional() }),
+]);
+export type FieldTarget = z.infer<typeof fieldTargetSchema>;
+
+const SCALAR_TYPES = ["string", "number", "integer", "boolean"] as const;
+const schemaTypeSchema = z.enum([...SCALAR_TYPES, "object", "array"]);
+
+/** Untrimmed: two names that differ only in surrounding spaces would collapse into one. */
+const propertyNameSchema = z
+    .string()
+    .min(1)
+    .max(120)
+    .refine((name) => name === name.trim(), "no surrounding spaces");
+
+/** What an array holds: a scalar, or an object with properties of its own. */
+const itemsSchema = z.strictObject({
+    type: z.enum([...SCALAR_TYPES, "object"]),
+    get properties() {
+        return z.record(propertyNameSchema, schemaPropertySchema).optional();
+    },
+    required: z.array(z.string()).optional(),
+});
+
+/**
+ * A JSON Schema property, in the part of JSON Schema a field editor holds:
+ * a type (with `"null"` beside it when the value may be null), an `enum` of
+ * strings for a string, an object's `properties` and `required`, an
+ * array's `items`, a `description`, and the extensions `x-sensitive`
+ * (redacted from logs), `x-source` and `x-target` (top-level scalar fields
+ * of a tool's input only).
+ */
+const schemaPropertySchema = z.strictObject({
+    type: z.union([schemaTypeSchema, z.tuple([schemaTypeSchema, z.literal("null")])]),
+    description: z.string().trim().max(500).optional(),
+    /** A nullable enum lists `null` beside its values, as the console stores one. */
+    enum: z
+        .array(z.union([z.string().trim().min(1), z.null()]))
+        .min(1)
+        .max(51)
+        .optional(),
+    get properties() {
+        return z.record(propertyNameSchema, schemaPropertySchema).optional();
+    },
+    required: z.array(z.string()).optional(),
+    get items() {
+        return itemsSchema.optional();
+    },
+    "x-sensitive": z.boolean().optional(),
+    "x-source": fieldSourceSchema.optional(),
+    "x-target": fieldTargetSchema.optional(),
+});
+type SchemaProperty = z.infer<typeof schemaPropertySchema>;
+
+/** A node's own type, without the `"null"` beside it. */
+function typeOf(node: { type: SchemaProperty["type"] }) {
+    return [node.type].flat()[0];
+}
+
+/** A refusal below a node: where, relative to it, and why. */
+type RowIssue = { at: Array<string | number>; message: string };
+
+/** What a node's own keywords break: `properties` or `required` off an object, or `required` naming no property. */
+function nodeIssues(node: {
+    type: SchemaProperty["type"];
+    properties?: Record<string, SchemaProperty>;
+    required?: string[];
+}) {
+    const issues = new Array<RowIssue>();
+    const object = typeOf(node) === "object";
+    for (const keyword of ["properties", "required"] as const) {
+        if (!object && node[keyword] !== undefined) {
+            issues.push({ at: [keyword], message: "only an object has it" });
+        }
+    }
+    node.required?.forEach((name, index) => {
+        if (!Object.hasOwn(node.properties ?? {}, name)) {
+            issues.push({ at: ["required", index], message: "names no property" });
+        }
+    });
+    return issues;
+}
+
+/**
+ * What an `enum` breaks, if anything: it lists a string's values, 1 to 50 of
+ * them, beside `null` exactly when the type allows null, as the console
+ * stores a nullable one.
+ */
+function enumIssueOf(property: SchemaProperty, type: string | undefined) {
+    if (property.enum === undefined) return undefined;
+    if (type !== "string") return "an enum lists a string's values";
+    const values = property.enum.filter((value) => value !== null);
+    if (values.length === 0 || values.length > 50) return "an enum lists 1 to 50 values";
+    const nullable = Array.isArray(property.type);
+    if (nullable === property.enum.includes(null)) return undefined;
+    return nullable ? "a nullable enum lists null" : "only a nullable enum lists null";
+}
+
+/**
+ * What one property breaks of itself: an `enum` off a string, with no value,
+ * or listing `null` when the type does not allow it or the other way round;
+ * `items` off an array or an array without them; and `x-source` or
+ * `x-target` off a scalar of a `bindable` node, or a source that does not
+ * fit the field.
+ */
+function propertyIssues(property: SchemaProperty, bindable: boolean) {
+    const issues = new Array<RowIssue>();
+    const type = typeOf(property);
+    const enumIssue = enumIssueOf(property, type);
+    if (enumIssue) issues.push({ at: ["enum"], message: enumIssue });
+    if ((property.items === undefined) === (type === "array")) {
+        issues.push({
+            at: ["items"],
+            message: type === "array" ? "an array declares its items" : "only an array has it",
+        });
+    }
+    const binds = bindable && SCALAR_TYPES.some((scalar) => scalar === type);
+    for (const binding of ["x-source", "x-target"] as const) {
+        if (property[binding] !== undefined && !binds) {
+            issues.push({
+                at: [binding],
+                message: "only a top-level scalar field of a tool's input has it",
+            });
+        }
+    }
+    const source = property["x-source"];
+    if (binds && source && !sourceFits(source, { type, enum: property.enum })) {
+        issues.push({ at: ["x-source"], message: "the source does not fit the field's type" });
+    }
+    return issues;
+}
+
+/**
+ * Refuses, at every depth below `path`, what the console's field rows cannot
+ * hold, since it stores a schema as rows and would drop or change it in
+ * silence (`nodeIssues`, `propertyIssues`); `x-source` and `x-target` only
+ * on a scalar directly under a node where `bindable`.
+ */
+function heldByRows(
+    node: {
+        type: SchemaProperty["type"];
+        properties?: Record<string, SchemaProperty>;
+        required?: string[];
+    },
+    context: z.RefinementCtx,
+    path: Array<string | number>,
+    bindable: boolean,
+) {
+    const report = (under: Array<string | number>, issues: ReadonlyArray<RowIssue>) => {
+        for (const { at, message } of issues) {
+            context.addIssue({ code: "custom", path: [...under, ...at], message });
+        }
+    };
+    report(path, nodeIssues(node));
+    for (const [name, property] of Object.entries(node.properties ?? {})) {
+        const at = [...path, "properties", name];
+        report(at, propertyIssues(property, bindable));
+        heldByRows(property, context, at, false);
+        if (property.items) heldByRows(property.items, context, [...at, "items"], false);
+    }
+}
+
+/**
+ * An object's JSON Schema, the shape of a tool's or trigger's input and
+ * output. `bindable` admits `x-source` and `x-target` on its top-level
+ * scalar fields, as a tool's input has them.
+ */
+function objectSchemaOf(bindable: boolean) {
+    return z
+        .strictObject({
+            type: z.literal("object"),
+            properties: z.record(propertyNameSchema, schemaPropertySchema).optional(),
+            required: z.array(z.string()).optional(),
+        })
+        .superRefine((schema, context) => heldByRows(schema, context, [], bindable));
+}
+const objectSchema = objectSchemaOf(false);
+
+const EMPTY_OBJECT = { type: "object" } as const satisfies z.input<typeof objectSchema>;
+
+/** Who a component reaches: every agent, every agent on one server, or the agents listed by slug. */
+const audienceSchema = z.union([
+    z.literal("all"),
+    z.strictObject({ server: nameSchema }),
+    z.strictObject({
+        agents: z
+            .array(agentSlugSchema)
+            .min(1)
+            .refine((slugs) => new Set(slugs).size === slugs.length, "an agent repeats"),
+    }),
+]);
+
+/** A model a provider lists, and the reasoning effort sent with it. */
+const modelSchema = z.strictObject({
+    provider: nameSchema,
+    model: z.string().trim().min(1).max(200),
+    effort: z.string().trim().min(1).max(64).optional(),
+});
+
+/** One line per locale, trimmed. */
+const localizedLineSchema = z.record(localeSchema, z.string().trim().min(1).max(120));
+const localizedTextSchema = z.record(localeSchema, z.string().trim().min(1).max(4_000));
+
+const { tool: toolBounds } = SETTING_BOUNDS;
+
+/** Shared by every tool type; a tool that calls nothing (`client`) has no endpoint, credentials, approval or bound fields. */
+const toolBaseSchema = z.strictObject({
+    ...serverToolSchema.pick({ name: true, description: true }).shape,
+    inputSchema: objectSchema.default(EMPTY_OBJECT),
+    outputSchema: objectSchema.default(EMPTY_OBJECT),
+    timeoutMs: setting(toolBounds.timeoutMs),
+    maxResponseBytes: setting(toolBounds.maxResponseBytes),
+    rateLimitRequests: setting(toolBounds.rateLimitRequests),
+    rateLimitWindowSeconds: setting(toolBounds.rateLimitWindowSeconds),
+    /** 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,
+});
+
+/** A tool that calls an endpoint; with `requiresApproval`, every call waits for the end user to approve it. */
+const calledToolSchema = toolBaseSchema.extend({
+    inputSchema: objectSchemaOf(true).default(EMPTY_OBJECT),
+    url: upstreamUrlSchema.refine(
+        confinesEndpointParams,
+        "a {parameter} outside the path or query",
+    ),
+    credentials: credentialsSchema,
+    requiresApproval: z.boolean().default(false),
+});
+
+const manifestToolSchema = z
+    .discriminatedUnion("type", [
+        calledToolSchema.extend({
+            type: z.literal("http"),
+            method: z.enum(TOOL_METHODS),
+            readOnly: z.boolean(),
+            ...toolConfigByType.http.shape,
+        }),
+        /** The endpoint is the initiate call that opens the page; never read-only, so a reload rejoins it. */
+        calledToolSchema.extend({
+            type: z.literal("embedded"),
+            method: z.enum(TOOL_METHODS),
+            ...toolConfigByType.embedded.shape,
+        }),
+        /** Always POSTed. */
+        calledToolSchema.extend({
+            type: z.literal("soap"),
+            readOnly: z.boolean(),
+            ...toolConfigByType.soap.shape,
+        }),
+        /** Answered by your app: the model calls it and the widget hands the call over. */
+        toolBaseSchema.extend({ type: z.literal("client") }),
+    ])
+    .superRefine((tool, context) => {
+        if (tool.type !== "client") refuseBlockedApprovalTitle(tool, context, []);
+    });
+export type ManifestTool = z.input<typeof manifestToolSchema>;
+
+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
+ * 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. */
+    url: upstreamUrlSchema,
+    credentials: credentialsSchema,
+    /** Tools listed in every turn of every agent they reach, whatever the question. */
+    pinned: toolNamesSchema,
+    approval: z
+        .strictObject({ never: toolNamesSchema, always: toolNamesSchema })
+        .prefault({})
+        .refine(
+            ({ never, always }) => !never.some((name) => always.includes(name)),
+            "a tool both never and always needs approval",
+        ),
+    audience: audienceSchema,
+});
+export type ManifestOpenApi = z.input<typeof manifestOpenApiSchema>;
+
+/** Identified by its `key`, which skills and collections scope themselves by; `name` is its label. */
+const manifestServiceSchema = z.strictObject({
+    /** What consumers parameterize their tools with; fixed once published. */
+    key: slugSchema,
+    name: localizedLineSchema,
+    /** Rich text: it may mention tools and skills. */
+    description: localizedTextSchema,
+    audience: audienceSchema,
+});
+export type ManifestService = z.input<typeof manifestServiceSchema>;
+
+const manifestSkillSchema = z.strictObject({
+    name: slugSchema,
+    description: z.string().trim().min(1).max(500),
+    /** Rich text: it may mention tools, skills and datasets, and read `{{variables}}`. */
+    body: z.string().trim().min(1),
+    /** The key of the service the skill renders inside; fixed once created. */
+    service: slugSchema.optional(),
+    audience: audienceSchema,
+});
+export type ManifestSkill = z.input<typeof manifestSkillSchema>;
+
+/**
+ * Which thread a firing lands in. `single`: one thread for the trigger.
+ * `per-firing`: a fresh thread every time. `ephemeral`: a fresh thread that
+ * is deleted once the run completes, for one-shot calls: the answer reaches
+ * the caller as the firing's output or through the live stream, and nothing
+ * else outlives the run; a failed run keeps its thread for inspection. `keyed`:
+ * one thread per distinct value at a JSON pointer into the payload (e.g.
+ * `/pull_request/number`).
+ */
+export const triggerThreadPolicySchema = z.discriminatedUnion("policy", [
+    z.object({ policy: z.literal("single") }),
+    z.object({ policy: z.literal("per-firing") }),
+    z.object({ policy: z.literal("ephemeral") }),
+    z.object({ policy: z.literal("keyed"), key: z.string().regex(/^\//).max(256) }),
+]);
+export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
+
+/** Fired with its secret, which the apply that creates it answers once and no manifest holds. */
+const manifestTriggerSchema = z.strictObject({
+    /** `message` is the built-in trigger every agent has. */
+    name: slugSchema.refine((name) => name !== MESSAGE_TRIGGER_NAME, "the built-in trigger's name"),
+    description: z.string().trim().min(1).max(500),
+    inputSchema: objectSchema.default(EMPTY_OBJECT),
+    /** The shape the run answers in; absent, the run answers in free text. */
+    outputSchema: objectSchema
+        .refine(
+            (schema) => Object.keys(schema.properties ?? {}).length > 0,
+            "declares a property; leave it out for a free-text answer",
+        )
+        .optional(),
+    /** Rich text: it may mention tools, skills and datasets, and read `{{variables}}` and `{{/payload/pointer}}`s. */
+    instructions: z.string().trim().min(1).max(20_000),
+    threadPolicy: triggerThreadPolicySchema.default({ policy: "single" }),
+    /** Firings a day per agent; absent, no limit. */
+    budgetPerDay: z.number().int().positive().optional(),
+    /** Consecutive failed or rejected firings before the trigger disables itself; it stays off until an operator enables it. */
+    disableAfterFailures: setting(SETTING_BOUNDS.trigger.disableAfterFailures),
+    /** The credential the run acts with, presented wherever the end user's token would go. */
+    credential: nameSchema.optional(),
+    /** A static credential whose value callers fire with, in place of a minted secret. */
+    fireCredential: nameSchema.optional(),
+    /** The model its runs talk to, over each agent's. */
+    model: modelSchema.optional(),
+    audience: audienceSchema,
+});
+export type ManifestTrigger = z.input<typeof manifestTriggerSchema>;
+
+/** The datasets `pinned` lists that `expose` does not: a host pins only what it exposes. */
+export function unexposedPins(host: {
+    expose: ReadonlyArray<string>;
+    pinned: ReadonlyArray<string>;
+}) {
+    const exposed = new Set(host.expose);
+    return host.pinned.filter((name) => !exposed.has(name));
+}
+
+const manifestDatasetHostSchema = z
+    .strictObject({
+        name: datasetIdentifierSchema,
+        url: upstreamUrlSchema,
+        credentials: credentialsSchema,
+        timeoutMs: setting(SETTING_BOUNDS.datasetHost.timeoutMs),
+        /** 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,
+    })
+    .superRefine((host, context) => {
+        const unexposed = unexposedPins(host);
+        if (unexposed.length > 0) {
+            context.addIssue({
+                code: "custom",
+                path: ["pinned"],
+                message: `not exposed: ${unexposed.join(", ")}`,
+            });
+        }
+    });
+export type ManifestDatasetHost = z.input<typeof manifestDatasetHostSchema>;
+
+/** An MCP server's own tool names. The console edits the list as comma-separated entries, so no name holds a comma. */
+export const mcpToolNamesSchema = z
+    .array(
+        z
+            .string()
+            .trim()
+            .min(1)
+            .max(128)
+            .regex(/^[^,]*$/, "a tool name holds no comma"),
+    )
+    .max(200);
+
+const manifestMcpServerSchema = z.strictObject({
+    /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
+    name: z.string().regex(IDENTIFIER_PATTERN).max(64),
+    url: upstreamUrlSchema,
+    credentials: presentationsSchema(
+        presentedHeaderSchema.refine(
+            (name) => !mcpTransportHeaders.has(name.toLowerCase()),
+            "a header the MCP transport sets",
+        ),
+        nameSchema.nullable(),
+    ),
+    /** The server's own tool names to offer; empty offers every tool. */
+    include: mcpToolNamesSchema.default([]),
+    exclude: mcpToolNamesSchema.default([]),
+    audience: audienceSchema,
+});
+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.
+ */
+const manifestWebhookSchema = z.strictObject({
+    name: slugSchema,
+    description: z.string().trim().max(500).default(""),
+    event: z.enum(SERVER_EVENTS),
+    url: upstreamUrlSchema,
+    credentials: presentationsSchema(
+        presentedHeaderSchema.refine(
+            (name) => name.toLowerCase() !== EVENT_HEADER.toLowerCase(),
+            "the header that names the event",
+        ),
+        nameSchema,
+    ),
+    timeoutMs: setting(SETTING_BOUNDS.webhook.timeoutMs),
+    audience: audienceSchema,
+});
+export type ManifestWebhook = z.input<typeof manifestWebhookSchema>;
+
+/** Holds documents, which are uploaded to it apart from the manifest. */
+const manifestCollectionSchema = z.strictObject({
+    name: z.string().trim().min(1).max(80),
+    description: z.string().trim().max(2_000).default(""),
+    /** The key of the service every document in the collection belongs to. */
+    service: slugSchema.optional(),
+    audience: audienceSchema,
+});
+export type ManifestCollection = z.input<typeof manifestCollectionSchema>;
+
+export const AUTH_JWT_SECRET_ALGORITHMS = ["HS256", "HS384", "HS512"] as const;
+
+const issuerSchema = z.string().trim().min(1).max(2048);
+/** When set, the token's `aud` must contain it, so a token minted for another audience under the same issuer cannot be replayed here. */
+const tokenAudienceSchema = z.string().trim().min(1).max(2048).optional();
+
+/**
+ * How the agent verifies end-user tokens: against the keys its issuer
+ * publishes at a JWKS URI, with a shared secret named in Cortex's secret
+ * store and the one algorithm tokens are signed with, through its server's
+ * `/verify`, or not at all.
+ */
+const agentAuthSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("jwks"),
+        jwksUri: tlsUrlSchema,
+        issuer: issuerSchema,
+        audience: tokenAudienceSchema,
+    }),
+    z.strictObject({
+        kind: z.literal("jwt-secret"),
+        secret: nameSchema,
+        algorithm: z.enum(AUTH_JWT_SECRET_ALGORITHMS),
+        issuer: issuerSchema,
+        audience: tokenAudienceSchema,
+    }),
+    z.strictObject({ kind: z.literal("anonymous") }),
+    z.strictObject({ kind: z.literal("server") }),
+]);
+
+const { agent: agentBounds, agentContext, agentLimits } = SETTING_BOUNDS;
+
+/** How the agent runs; every setting left out keeps its default. */
+const agentSettingsSchema = z.strictObject({
+    /** Offers `searchKnowledge` over the collections the agent sees. */
+    ragEnabled: z.boolean().default(false),
+    /** Offers `searchTools` over the tools the agent sees, beyond the pinned and mentioned ones. */
+    toolRegistryEnabled: z.boolean().default(false),
+    serviceRegistryEnabled: z.boolean().default(false),
+    attachmentsEnabled: z.boolean().default(true),
+    /** Hosts the built-in `fetchImage` tool may pull images from; none, no such tool. */
+    fetchImageHostnames: z
+        .array(z.string().max(253).regex(HOSTNAME_PATTERN))
+        .max(FETCH_IMAGE_HOSTS_LIMIT)
+        .default([]),
+    locationPicker: z.boolean().default(false),
+    /** The fenced media forms the agent may draw, which its prompt then describes. */
+    media: z.array(z.enum(MEDIA_FORMS)).default([...DEFAULT_MEDIA_FORMS]),
+    /** Off, end users cannot message the agent: only its triggers reach it. */
+    messageTrigger: z.boolean().default(true),
+    defaultLocale: localeSchema.default("en"),
+    rateLimitRequests: setting(agentBounds.rateLimitRequests),
+    rateLimitWindowSeconds: setting(agentBounds.rateLimitWindowSeconds),
+    dailyExecutionQuota: setting(agentBounds.dailyExecutionQuota),
+    context: z
+        .strictObject({
+            maxContextTokens: setting(agentContext.maxContextTokens),
+            summarizationThreshold: z
+                .number()
+                .min(agentContext.summarizationThreshold.min)
+                .max(agentContext.summarizationThreshold.max)
+                .default(agentContext.summarizationThreshold.default),
+            toolResultMaxTokens: setting(agentContext.toolResultMaxTokens),
+            recentMessagesToKeep: setting(agentContext.recentMessagesToKeep),
+        })
+        .prefault({}),
+    limits: z
+        .strictObject({
+            resolveTokenBudget: setting(agentLimits.resolveTokenBudget),
+            executeTimeoutMs: setting(agentLimits.executeTimeoutMs),
+            maxResponseBytes: setting(agentLimits.maxResponseBytes),
+        })
+        .prefault({}),
+});
+
+const manifestAgentSchema = z.strictObject({
+    slug: agentSlugSchema,
+    name: z.string().trim().min(1).max(120),
+    /** The server it belongs to, by name; a manifest never creates one. */
+    server: nameSchema,
+    /** Rich text: it may mention tools and skills, and read `{{variables}}`. */
+    prompt: z.string().trim().min(1),
+    auth: agentAuthSchema,
+    /**
+     * `chat` left out runs on the server's pick; `vision` and
+     * `summarization` left out use none of their own.
+     */
+    models: z
+        .strictObject({
+            chat: modelSchema.optional(),
+            vision: modelSchema.omit({ effort: true }).optional(),
+            summarization: modelSchema.omit({ effort: true }).optional(),
+        })
+        .default({}),
+    settings: agentSettingsSchema.prefault({}),
+    suggestions: suggestionsSchema.default({ en: [], ar: [] }),
+    greeting: greetingSchema.default({ en: "", ar: "" }),
+});
+export type ManifestAgent = z.input<typeof manifestAgentSchema>;
+
+/** Every name in a list once, so one entry means one row. */
+function uniqueBy<TEntry>(key: (entry: TEntry) => string) {
+    return (entries: ReadonlyArray<TEntry>) => new Set(entries.map(key)).size === entries.length;
+}
+
+function listOf<TEntry extends z.ZodType>(entry: TEntry, key: (value: z.output<TEntry>) => string) {
+    return z.array(entry).refine(uniqueBy(key), "a name repeats").default([]);
+}
+
+const byName = (entry: { name: string }) => entry.name;
+
+/** The id of Cortex's own manifest, which only Cortex applies: the management API refuses any other under it. */
+export const CORTEX_MANIFEST_ID = "cortex";
+
+/**
+ * A deployment's agents and components, owned by the manifest `id`: an apply
+ * of it creates what is new, updates what changed, and deletes what it no
+ * longer lists, touching nothing it did not create.
+ */
+export const manifestSchema = z.strictObject({
+    /** Fixed for the deployment it describes: the rows an apply owns carry it. */
+    id: slugSchema,
+    agents: listOf(manifestAgentSchema, (agent) => agent.slug),
+    tools: listOf(manifestToolSchema, byName),
+    openapi: listOf(manifestOpenApiSchema, byName),
+    services: listOf(manifestServiceSchema, (service) => service.key),
+    skills: listOf(manifestSkillSchema, byName),
+    triggers: listOf(manifestTriggerSchema, byName),
+    datasetHosts: listOf(manifestDatasetHostSchema, byName),
+    mcpServers: listOf(manifestMcpServerSchema, byName),
+    webhooks: listOf(manifestWebhookSchema, byName),
+    collections: listOf(manifestCollectionSchema, byName),
+});
+/** A manifest as written: every field with a default may be left out. */
+export type Manifest = z.input<typeof manifestSchema>;
+
+/**
+ * Entry names per kind: agents by slug, services by key, everything else by
+ * name. An OpenAPI source's operations are counted among `tools`.
+ */
+const namesByKindSchema = z.record(
+    manifestSchema.keyof().exclude(["id", "openapi"]),
+    z.array(z.string()),
+);
+
+/** What an apply creates, updates and deletes, kind by kind; a preview answers the same without doing it. */
+export const manifestChangesSchema = z.object({
+    create: namesByKindSchema,
+    update: namesByKindSchema,
+    delete: namesByKindSchema,
+});
+
+/**
+ * An apply's changes, and a fire secret, shown this once, for each trigger
+ * it left with none anyone holds: one it created, or one whose
+ * `fireCredential` it dropped.
+ */
+export const appliedManifestSchema = manifestChangesSchema.extend({
+    triggerSecrets: z.record(z.string(), z.string()),
+});
+
+/** Types a manifest as it is written; `cortex apply` validates and sends it. */
+export function defineManifest(manifest: Manifest) {
+    return manifest;
+}