@m6d/cortex-cli 0.13.0 → 0.15.0

package/src/contracts/manifest/index.ts

@@ -7,6 +7,7 @@ import {
     IDENTIFIER_PATTERN,
     localeSchema,
     SERVER_EVENTS,
+    refuseBlockedApprovalTitle,
     serverToolSchema,
 } from "../server/index";
 import { MESSAGE_TRIGGER_NAME } from "../triggers/index";
@@ -45,8 +46,16 @@ export const TOOL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
  */
 export const RESPONSE_WRAPS = ["items", "value"] as const;
 
+/** How OpenAPI serializes a query parameter: `form` (the default), `spaceDelimited`, `pipeDelimited` or `deepObject`. */
+export const QUERY_STYLES = ["form", "spaceDelimited", "pipeDelimited", "deepObject"] as const;
+/** How OpenAPI serializes a path parameter: `simple` (the default), `label` or `matrix`. */
+export const PATH_STYLES = ["simple", "label", "matrix"] as const;
+
 export const SOAP_VERSIONS = ["1.1", "1.2"] as const;
 
+/** An RFC 6901 pointer into a JSON document, naming a member: `/extra`, `/data/items`. */
+const jsonPointerSchema = z.string().regex(/^\//).max(256);
+
 type Bounds = { min: number; max: number; default: number };
 
 /**
@@ -90,6 +99,25 @@ function setting({ min, max, default: fallback }: Bounds) {
     return z.number().int().min(min).max(max).default(fallback);
 }
 
+/**
+ * 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.
+ */
+function overridable<const TField extends string>(fields: readonly [TField, ...TField[]]) {
+    return z
+        .array(z.enum(fields))
+        .refine(
+            uniqueBy((field: TField) => field),
+            "a field repeats",
+        )
+        .default([]);
+}
+
 /** 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);
@@ -174,6 +202,16 @@ 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 media types a request body may be sent in besides JSON, the default.
+ * Each body field is written as its target says.
+ */
+export const FORM_MEDIA_TYPES = [
+    "application/x-www-form-urlencoded",
+    "multipart/form-data",
+] as const;
+export type FormMediaType = (typeof FORM_MEDIA_TYPES)[number];
+
 /**
  * The per-type payload a tool stores and publishes. Soap: the envelope
  * template is the full request XML with `{{field}}` placeholders bound to
@@ -181,7 +219,12 @@ const envelopeTemplateSchema = z.string().refine((template) => template.trim().l
  * acquires once per request.
  */
 export const toolConfigByType = {
-    http: z.object({ responseWrap: z.enum(RESPONSE_WRAPS).optional() }),
+    http: z.object({
+        responseWrap: z.enum(RESPONSE_WRAPS).optional(),
+        requestMediaType: z.enum(FORM_MEDIA_TYPES).optional(),
+        /** Where a successful response keeps the result, for an API that wraps every answer (`{ success, extra }`); read before `responseWrap`. */
+        resultPath: jsonPointerSchema.optional(),
+    }),
     embedded: z.object({ embedOrigin: embedOriginSchema, surface: z.enum(TOOL_SURFACES) }),
     soap: z.object({
         soapVersion: z.enum(SOAP_VERSIONS),
@@ -342,17 +385,44 @@ export function sourceFits(
 }
 
 /**
- * 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.
+ * Where a top-level 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,
+ * and is the name `matrix` style writes into a path.
+ * `style` and `explode` write an array or object value as an OpenAPI
+ * parameter declares; left out, OpenAPI's defaults hold (`form` exploded for
+ * a query, `simple` unexploded for a path and a header). A cookie joins items
+ * with commas. In a form body (the tool's `requestMediaType`), a JSON
+ * `contentType` sends the value as JSON text, and `style` and `explode`
+ * write it as in a query; a multipart body repeats an array's items as
+ * parts, typing an object JSON unless `contentType` says text. A JSON body
+ * reads none of them.
  */
 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() }),
+    z.strictObject({
+        kind: z.literal("body"),
+        contentType: z.enum(["application/json", "text/plain"]).optional(),
+        style: z.enum(QUERY_STYLES).optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("query"),
+        name: z.string().trim().min(1).max(120).optional(),
+        style: z.enum(QUERY_STYLES).optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("path"),
+        name: z.string().trim().min(1).max(120).optional(),
+        style: z.enum(PATH_STYLES).optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("header"),
+        name: headerNameSchema.optional(),
+        explode: z.boolean().optional(),
+    }),
+    z.strictObject({ kind: z.literal("cookie"), name: headerNameSchema.optional() }),
 ]);
 export type FieldTarget = z.infer<typeof fieldTargetSchema>;
 
@@ -380,8 +450,8 @@ const itemsSchema = z.strictObject({
  * 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).
+ * (redacted from logs), `x-source` (top-level scalar fields of a tool's
+ * input only) and `x-target` (top-level fields of a tool's input only).
  */
 const schemaPropertySchema = z.strictObject({
     type: z.union([schemaTypeSchema, z.tuple([schemaTypeSchema, z.literal("null")])]),
@@ -452,9 +522,9 @@ function enumIssueOf(property: SchemaProperty, type: string | undefined) {
 /**
  * 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.
+ * `items` off an array or an array without them; `x-source` off a scalar
+ * of a `bindable` node, or a source that does not fit the field; and
+ * `x-target` off a `bindable` node.
  */
 function propertyIssues(property: SchemaProperty, bindable: boolean) {
     const issues = new Array<RowIssue>();
@@ -468,13 +538,17 @@ function propertyIssues(property: SchemaProperty, bindable: boolean) {
         });
     }
     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",
-            });
-        }
+    if (property["x-source"] !== undefined && !binds) {
+        issues.push({
+            at: ["x-source"],
+            message: "only a top-level scalar field of a tool's input has it",
+        });
+    }
+    if (property["x-target"] !== undefined && !bindable) {
+        issues.push({
+            at: ["x-target"],
+            message: "only a top-level field of a tool's input has it",
+        });
     }
     const source = property["x-source"];
     if (binds && source && !sourceFits(source, { type, enum: property.enum })) {
@@ -486,8 +560,8 @@ function propertyIssues(property: SchemaProperty, bindable: boolean) {
 /**
  * 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`.
+ * silence (`nodeIssues`, `propertyIssues`); `x-source` only on a scalar,
+ * and `x-target` only on a field, directly under a node where `bindable`.
  */
 function heldByRows(
     node: {
@@ -515,8 +589,8 @@ function heldByRows(
 
 /**
  * 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.
+ * output. `bindable` admits `x-source` on its top-level scalar fields and
+ * `x-target` on its top-level fields, as a tool's input has them.
  */
 function objectSchemaOf(bindable: boolean) {
     return z
@@ -571,9 +645,18 @@ const toolBaseSchema = z.strictObject({
     pinned: z.boolean().default(false),
     tags: toolTagsSchema.default([]),
     audience: audienceSchema,
+    overridable: overridable([
+        "description",
+        "timeoutMs",
+        "maxResponseBytes",
+        "rateLimitRequests",
+        "rateLimitWindowSeconds",
+        "pinned",
+        "tags",
+    ]),
 });
 
-/** A tool that calls an endpoint; `approval` set, every call waits for the end user to approve it. */
+/** 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(
@@ -581,33 +664,68 @@ const calledToolSchema = toolBaseSchema.extend({
         "a {parameter} outside the path or query",
     ),
     credentials: credentialsSchema,
-    approval: serverToolSchema.shape.approval,
+    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") }),
-]);
+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,
+    /** 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. */
+    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. */
@@ -616,6 +734,7 @@ const manifestServiceSchema = z.strictObject({
     /** Rich text: it may mention tools and skills. */
     description: localizedTextSchema,
     audience: audienceSchema,
+    overridable: overridable(["description"]),
 });
 export type ManifestService = z.input<typeof manifestServiceSchema>;
 
@@ -627,6 +746,7 @@ const manifestSkillSchema = z.strictObject({
     /** The key of the service the skill renders inside; fixed once created. */
     service: slugSchema.optional(),
     audience: audienceSchema,
+    overridable: overridable(["description", "body"]),
 });
 export type ManifestSkill = z.input<typeof manifestSkillSchema>;
 
@@ -643,7 +763,7 @@ 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) }),
+    z.object({ policy: z.literal("keyed"), key: jsonPointerSchema }),
 ]);
 export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
 
@@ -674,6 +794,14 @@ const manifestTriggerSchema = z.strictObject({
     /** The model its runs talk to, over each agent's. */
     model: modelSchema.optional(),
     audience: audienceSchema,
+    overridable: overridable([
+        "description",
+        "instructions",
+        "threadPolicy",
+        "budgetPerDay",
+        "disableAfterFailures",
+        "model",
+    ]),
 });
 export type ManifestTrigger = z.input<typeof manifestTriggerSchema>;
 
@@ -697,6 +825,7 @@ const manifestDatasetHostSchema = z
         /** Among those, the ones listed in every turn, whatever the question. */
         pinned: z.array(datasetIdentifierSchema).max(50).default([]),
         audience: audienceSchema,
+        overridable: overridable(["timeoutMs"]),
     })
     .superRefine((host, context) => {
         const unexposed = unexposedPins(host);
@@ -737,6 +866,7 @@ const manifestMcpServerSchema = z.strictObject({
     include: mcpToolNamesSchema.default([]),
     exclude: mcpToolNamesSchema.default([]),
     audience: audienceSchema,
+    overridable: overridable(["include", "exclude"]),
 });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
@@ -759,6 +889,7 @@ const manifestWebhookSchema = z.strictObject({
     ),
     timeoutMs: setting(SETTING_BOUNDS.webhook.timeoutMs),
     audience: audienceSchema,
+    overridable: overridable(["description", "timeoutMs"]),
 });
 export type ManifestWebhook = z.input<typeof manifestWebhookSchema>;
 
@@ -768,7 +899,10 @@ const manifestCollectionSchema = z.strictObject({
     description: z.string().trim().max(2_000).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"]),
 });
 export type ManifestCollection = z.input<typeof manifestCollectionSchema>;
 
@@ -806,10 +940,11 @@ 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. */
+    /** Lets `searchRegistries` search the knowledge in the collections the agent sees. */
     ragEnabled: z.boolean().default(false),
-    /** Offers `searchTools` over the tools the agent sees, beyond the pinned and mentioned ones. */
+    /** Lets `searchRegistries` search the tools the agent sees, beyond the pinned and mentioned ones. */
     toolRegistryEnabled: z.boolean().default(false),
+    /** Lets `searchRegistries` search the services the agent sees. */
     serviceRegistryEnabled: z.boolean().default(false),
     attachmentsEnabled: z.boolean().default(true),
     /** Hosts the built-in `fetchImage` tool may pull images from; none, no such tool. */
@@ -869,6 +1004,7 @@ const manifestAgentSchema = z.strictObject({
     settings: agentSettingsSchema.prefault({}),
     suggestions: suggestionsSchema.default({ en: [], ar: [] }),
     greeting: greetingSchema.default({ en: "", ar: "" }),
+    overridable: overridable(["name", "prompt", "models", "settings", "suggestions", "greeting"]),
 });
 export type ManifestAgent = z.input<typeof manifestAgentSchema>;
 
@@ -889,13 +1025,16 @@ 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.
+ * longer lists, touching nothing it did not create. What an entry lists as
+ * `overridable` may then change in Cortex too, and an apply keeps that
+ * change unless the manifest changed the same field.
  */
 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),
@@ -907,8 +1046,11 @@ 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>;
 
+/** The kinds of row a manifest owns; an OpenAPI source's operations are `tools`. */
+const manifestKindSchema = manifestSchema.keyof().exclude(["id", "openapi"]);
+
 /** Entry names per kind: agents by slug, services by key, everything else by name. */
-const namesByKindSchema = z.record(manifestSchema.keyof().exclude(["id"]), z.array(z.string()));
+const namesByKindSchema = z.record(manifestKindSchema, 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({
@@ -917,6 +1059,32 @@ 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. */
+const manifestConflictSchema = z.strictObject({
+    kind: manifestKindSchema,
+    name: z.string(),
+    field: z.string(),
+});
+
+/** Which value a conflict keeps: the one changed live in Cortex, or the manifest's. */
+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.
+ */
+export const manifestApplyInputSchema = manifestSchema.extend({
+    prefer: conflictSideSchema.optional(),
+    resolutions: z.array(manifestConflictSchema.extend({ keep: conflictSideSchema })).default([]),
+});
+
+/** What a preview answers: the changes, and the conflicts nothing resolved. */
+export const manifestPreviewSchema = manifestChangesSchema.extend({
+    conflicts: z.array(manifestConflictSchema),
+});
+
 /**
  * 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

package/src/contracts/server/index.ts

@@ -2,7 +2,8 @@ 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 { LOCALES } from "../wire/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 /`
@@ -96,10 +97,8 @@ export const BUILT_IN_TOOL_NAMES = [
     "queryDataset",
     "readAttachment",
     "readReport",
-    "searchKnowledge",
-    "searchServices",
+    "searchRegistries",
     "searchThreadHistory",
-    "searchTools",
     REQUEST_LOCATION_TOOL,
     TRIGGER_ANSWER_TOOL_NAME,
 ] as const;
@@ -108,11 +107,14 @@ 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(64)
+    .max(TOOL_NAME_MAX_LENGTH)
     .refine((name) => !isBuiltInToolName(name), "the name of a built-in tool");
 
 const jsonSchemaSchema = z.record(z.string(), z.unknown());
@@ -135,8 +137,9 @@ export type ServerVariable = z.infer<typeof serverVariableSchema>;
 
 /**
  * A tool the server runs. Its input is an object, the `input` its calls
- * carry. An `approval` sentence per locale parks every call for the end
- * user's approval.
+ * 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,
@@ -147,7 +150,7 @@ export const serverToolSchema = z.object({
     ),
     outputSchema: jsonSchemaSchema.optional(),
     readOnly: z.boolean(),
-    approval: z.record(localeSchema, z.string().trim().min(1).max(500)).optional(),
+    requiresApproval: z.boolean().optional(),
 });
 export type ServerTool = z.infer<typeof serverToolSchema>;
 
@@ -179,6 +182,97 @@ export const approvalRequestedEventSchema = z.object({
 });
 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;
 }
@@ -187,7 +281,13 @@ function uniqueNames(entries: ReadonlyArray<{ name: string }>) {
 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"),
+    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)),
 });

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

@@ -7,10 +7,8 @@
         "queryDataset",
         "readAttachment",
         "readReport",
-        "searchKnowledge",
-        "searchServices",
+        "searchRegistries",
         "searchThreadHistory",
-        "searchTools",
         "requestLocation",
         "submitAnswer"
     ],