@m6d/cortex-cli 0.19.0 → 0.21.0

package/src/contracts/manifest/index.ts

@@ -2,10 +2,11 @@ import { z } from "zod";
 import { datasetIdentifierSchema } from "../datasets/index";
 import { canCarrySecret } from "../egress-policy/index";
 import {
-    agentSlugSchema,
+    displayNameSchema,
     EVENT_HEADER,
     identifierSchema,
     localeSchema,
+    nameSchema,
     SERVER_EVENTS,
     refuseBlockedApprovalTitle,
     serverToolSchema,
@@ -25,7 +26,7 @@ import {
  * 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
+ * provider, a service, an agent, 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
@@ -187,11 +188,6 @@ function overridable<const TField extends string>(fields: readonly [TField, ...T
         .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]+)*$/;
-export const SLUG_MAX_LENGTH = 64;
-const slugSchema = z.string().regex(SLUG_PATTERN).max(SLUG_MAX_LENGTH);
-
 /** 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])?)*$/;
@@ -477,11 +473,6 @@ function repeatedHeaders(entries: ReadonlyArray<{ header: string }>) {
     });
 }
 
-/** The longest name Cortex holds a server, model provider, credential or secret under. */
-export const NAME_MAX_LENGTH = 120;
-/** A server, model provider, credential or secret, by the name Cortex holds it under. */
-const nameSchema = z.string().trim().min(1).max(NAME_MAX_LENGTH);
-
 const presentedHeaderSchema = headerNameSchema.refine(
     (name) => !transportOwnedHeaders.has(name.toLowerCase()),
     "a header the transport sets",
@@ -518,7 +509,10 @@ const variableSourceSchema = z.object({
 });
 
 /** A credential Cortex holds or acquires, by name. */
-const credentialSourceSchema = z.object({ kind: z.literal("credential"), name: nameSchema });
+const credentialSourceSchema = z.object({
+    kind: z.literal("credential"),
+    name: nameSchema,
+});
 
 /** A value written as is. */
 const constantHeaderSourceSchema = z.object({
@@ -883,15 +877,15 @@ const objectSchema = objectJsonSchemaOf();
 
 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. */
+/** Who a component reaches: every agent, every agent on one server, or the agents listed by name. */
 const audienceSchema = z.union([
     z.literal("all"),
     z.strictObject({ server: nameSchema }),
     z.strictObject({
         agents: z
-            .array(agentSlugSchema)
+            .array(nameSchema)
             .min(1)
-            .refine((slugs) => new Set(slugs).size === slugs.length, "an agent repeats"),
+            .refine((names) => new Set(names).size === names.length, "an agent repeats"),
     }),
 ]);
 
@@ -905,14 +899,9 @@ const modelSchema = z.strictObject({
     effort: z.string().trim().min(1).max(64).optional(),
 });
 
-/** A service's name and description, in characters per locale. The console caps its editor at the same lengths. */
-export const SERVICE_LIMITS = { nameLength: 120, descriptionLength: 4_000 } as const;
+/** A service's description, in characters per locale. The console caps its editor at the same length. */
+export const SERVICE_LIMITS = { descriptionLength: 4_000 } as const;
 
-/** One line per locale, trimmed. */
-const localizedLineSchema = z.record(
-    localeSchema,
-    z.string().trim().min(1).max(SERVICE_LIMITS.nameLength),
-);
 const localizedTextSchema = z.record(
     localeSchema,
     z.string().trim().min(1).max(SERVICE_LIMITS.descriptionLength),
@@ -932,6 +921,7 @@ function toolInputSchemaOf(type: (typeof TOOL_TYPE_NAMES)[number]) {
 
 /** What a live write may change on a manifest's tool, and keep through the next apply. */
 const TOOL_OVERRIDABLES = [
+    "displayName",
     "description",
     "timeoutMs",
     "maxResponseBytes",
@@ -946,6 +936,7 @@ const CALLED_TOOL_OVERRIDABLES = [...TOOL_OVERRIDABLES, "headers"] as const;
 /** Shared by every tool type; a tool that calls nothing (`client`) has no endpoint, headers, approval or bound fields. */
 const toolBaseSchema = z.strictObject({
     ...serverToolSchema.pick({ name: true, description: true }).shape,
+    displayName: displayNameSchema.default({}),
     inputSchema: toolInputSchemaOf("client"),
     outputSchema: objectSchema.default(EMPTY_OBJECT),
     timeoutMs: setting(toolBounds.timeoutMs),
@@ -1050,15 +1041,15 @@ const manifestOpenApiSchema = z.strictObject({
 });
 export type ManifestOpenApi = z.input<typeof manifestOpenApiSchema>;
 
-/** Identified by its `key`, which skills and collections scope themselves by; `name` is its label. */
+/** Skills and collections scope themselves by a service's `name`. */
 const manifestServiceSchema = z.strictObject({
-    /** What consumers parameterize their tools with; fixed once published. */
-    key: slugSchema,
-    name: localizedLineSchema,
+    /** What consumers parameterize their tools with. */
+    name: nameSchema,
+    displayName: displayNameSchema.default({}),
     /** Rich text: it may mention tools and skills. */
     description: localizedTextSchema,
     audience: audienceSchema,
-    overridable: overridable(["description"]),
+    overridable: overridable(["displayName", "description"]),
 });
 export type ManifestService = z.input<typeof manifestServiceSchema>;
 
@@ -1066,14 +1057,15 @@ export type ManifestService = z.input<typeof manifestServiceSchema>;
 export const SKILL_LIMITS = { descriptionLength: 500 } as const;
 
 const manifestSkillSchema = z.strictObject({
-    name: slugSchema,
+    name: nameSchema,
+    displayName: displayNameSchema.default({}),
     description: z.string().trim().min(1).max(SKILL_LIMITS.descriptionLength),
     /** 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(),
+    /** The name of the service the skill renders inside; fixed once created. */
+    service: nameSchema.optional(),
     audience: audienceSchema,
-    overridable: overridable(["description", "body"]),
+    overridable: overridable(["displayName", "description", "body"]),
 });
 export type ManifestSkill = z.input<typeof manifestSkillSchema>;
 
@@ -1100,7 +1092,8 @@ export const TRIGGER_LIMITS = { descriptionLength: 500, instructionsLength: 20_0
 /** 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"),
+    name: nameSchema.refine((name) => name !== MESSAGE_TRIGGER_NAME, "the built-in trigger's name"),
+    displayName: displayNameSchema.default({}),
     description: z.string().trim().min(1).max(TRIGGER_LIMITS.descriptionLength),
     inputSchema: objectSchema.default(EMPTY_OBJECT),
     /** The shape the run answers in; absent, the run answers in free text. */
@@ -1125,6 +1118,7 @@ const manifestTriggerSchema = z.strictObject({
     model: modelSchema.optional(),
     audience: audienceSchema,
     overridable: overridable([
+        "displayName",
         "description",
         "instructions",
         "threadPolicy",
@@ -1147,6 +1141,7 @@ export function unexposedPins(host: {
 const manifestDatasetHostSchema = z
     .strictObject({
         name: datasetIdentifierSchema,
+        displayName: displayNameSchema.default({}),
         url: upstreamUrlSchema,
         headers: headersSchema,
         timeoutMs: setting(SETTING_BOUNDS.datasetHost.timeoutMs),
@@ -1175,7 +1170,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", "rateLimits", "headers"]),
+        overridable: overridable(["displayName", "timeoutMs", "rateLimits", "headers"]),
     })
     .superRefine((host, context) => {
         const unexposed = unexposedPins(host);
@@ -1204,6 +1199,7 @@ export const mcpToolNamesSchema = z
 const manifestMcpServerSchema = z.strictObject({
     /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
     name: identifierSchema,
+    displayName: displayNameSchema.default({}),
     url: upstreamUrlSchema,
     headers: declaredHeadersSchema(
         presentedHeaderSchema.refine(
@@ -1216,7 +1212,7 @@ const manifestMcpServerSchema = z.strictObject({
     include: mcpToolNamesSchema.default([]),
     exclude: mcpToolNamesSchema.default([]),
     audience: audienceSchema,
-    overridable: overridable(["include", "exclude", "headers"]),
+    overridable: overridable(["displayName", "include", "exclude", "headers"]),
 });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
@@ -1226,7 +1222,8 @@ export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
  * travels under the header that names the event.
  */
 const manifestWebhookSchema = z.strictObject({
-    name: slugSchema,
+    name: nameSchema,
+    displayName: displayNameSchema.default({}),
     description: z.string().trim().max(500).default(""),
     event: z.enum(SERVER_EVENTS),
     url: upstreamUrlSchema,
@@ -1239,19 +1236,15 @@ const manifestWebhookSchema = z.strictObject({
     ),
     timeoutMs: setting(SETTING_BOUNDS.webhook.timeoutMs),
     audience: audienceSchema,
-    overridable: overridable(["description", "timeoutMs", "headers"]),
+    overridable: overridable(["displayName", "description", "timeoutMs", "headers"]),
 });
 export type ManifestWebhook = z.input<typeof manifestWebhookSchema>;
 
 /**
- * A collection's name and description in characters, and how many documents
- * a manifest lists in one. The console caps its editor at the same.
+ * A collection's description in characters, and how many documents a
+ * manifest lists in one. The console caps its editor at the same.
  */
-export const COLLECTION_LIMITS = {
-    nameLength: 80,
-    descriptionLength: 2_000,
-    documents: 100,
-} as const;
+export const COLLECTION_LIMITS = { descriptionLength: 2_000, documents: 100 } as const;
 
 /** A knowledge document's name in characters and its size in bytes, however it arrives. */
 export const DOCUMENT_LIMITS = { nameLength: 255, bytes: 10 * 1024 * 1024 } as const;
@@ -1377,15 +1370,16 @@ function collectionSchema<TDocument extends z.ZodType<Parameters<typeof document
     document: TDocument,
 ) {
     return z.strictObject({
-        name: z.string().trim().min(1).max(COLLECTION_LIMITS.nameLength),
+        name: nameSchema,
+        displayName: displayNameSchema.default({}),
         description: z.string().trim().max(COLLECTION_LIMITS.descriptionLength).default(""),
-        /** The key of the service every document in the collection belongs to. */
-        service: slugSchema.optional(),
+        /** The name of the service every document in the collection belongs to. */
+        service: nameSchema.optional(),
         /** Whether answers may name its documents; false keeps their names, sections and pages from the model. */
         citable: z.boolean().default(true),
         documents: documentsSchema(document),
         audience: audienceSchema,
-        overridable: overridable(["description", "documents"]),
+        overridable: overridable(["displayName", "description", "documents"]),
     });
 }
 
@@ -1497,58 +1491,77 @@ export const agentSettingsSchema = z.strictObject({
         .prefault({}),
 });
 
-/** An agent's name in characters. The console caps its editor at the same. */
-export const AGENT_LIMITS = { nameLength: 120 } as const;
-
-const manifestAgentSchema = z.strictObject({
-    slug: agentSlugSchema,
-    name: z.string().trim().min(1).max(AGENT_LIMITS.nameLength),
-    /** 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({}),
-    /** Messages a minute and model tokens a UTC day, for all users together and for each; null, no limit. */
-    rateLimits: z
-        .strictObject({
-            allUsers: z
-                .strictObject({
-                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
-                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
-                })
-                .prefault({}),
-            perUser: z
-                .strictObject({
-                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
-                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
-                })
-                .prefault({}),
-        })
-        .prefault({}),
-    suggestions: suggestionsSchema.default(() => byLocale(() => [])),
-    greeting: greetingSchema.default(() => byLocale(() => "")),
-    overridable: overridable([
-        "name",
-        "prompt",
-        "models",
-        "settings",
-        "rateLimits",
-        "suggestions",
-        "greeting",
-    ]),
-});
+const manifestAgentSchema = z
+    .strictObject({
+        name: nameSchema,
+        displayName: displayNameSchema.default({}),
+        /**
+         * The server it belongs to, by name; a manifest never creates one. Left
+         * out, the agent has no server: no native tools, no server variables,
+         * no `server` auth, and no model to inherit, so it names its own `chat`.
+         */
+        server: nameSchema.optional(),
+        /** 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({}),
+        /** Messages a minute and model tokens a UTC day, for all users together and for each; null, no limit. */
+        rateLimits: z
+            .strictObject({
+                allUsers: z
+                    .strictObject({
+                        messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
+                        tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
+                    })
+                    .prefault({}),
+                perUser: z
+                    .strictObject({
+                        messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
+                        tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
+                    })
+                    .prefault({}),
+            })
+            .prefault({}),
+        suggestions: suggestionsSchema.default(() => byLocale(() => [])),
+        greeting: greetingSchema.default(() => byLocale(() => "")),
+        overridable: overridable([
+            "displayName",
+            "prompt",
+            "models",
+            "settings",
+            "rateLimits",
+            "suggestions",
+            "greeting",
+        ]),
+    })
+    .superRefine((agent, context) => {
+        if (agent.server !== undefined) return;
+        if (agent.auth.kind === "server") {
+            context.addIssue({
+                code: "custom",
+                path: ["auth"],
+                message: "server auth needs a server",
+            });
+        }
+        if (agent.models.chat === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["models", "chat"],
+                message: "an agent with no server names its own chat model",
+            });
+        }
+    });
 export type ManifestAgent = z.input<typeof manifestAgentSchema>;
 
 /**
@@ -1570,31 +1583,14 @@ export const MANIFEST_KINDS = [
 export type ManifestKind = (typeof MANIFEST_KINDS)[number];
 
 /**
- * The field each kind's entries go by, which its row's name holds: an
- * agent's slug, a service's key, any other entry's name. A list holds each
- * once, so one entry means one row.
+ * A list of entries, each going by the name its row holds, refusing a name
+ * they repeat: one entry means one row.
  */
-export const MANIFEST_NAME_FIELDS = {
-    agents: "slug",
-    tools: "name",
-    services: "key",
-    skills: "name",
-    triggers: "name",
-    datasetHosts: "name",
-    mcpServers: "name",
-    webhooks: "name",
-    collections: "name",
-} as const satisfies Record<ManifestKind, string>;
-
-/** A list of entries named by their `field`, refusing a name they repeat. */
-function listOf<TField extends string, TEntry extends z.ZodType<Record<TField, string>>>(
-    field: TField,
-    entry: TEntry,
-) {
+function listOf<TEntry extends z.ZodType<{ name: string }>>(entry: TEntry) {
     return z
         .array(entry)
         .refine(
-            (entries) => new Set(entries.map((value) => value[field])).size === entries.length,
+            (entries) => new Set(entries.map((value) => value.name)).size === entries.length,
             "a name repeats",
         )
         .default([]);
@@ -1612,17 +1608,17 @@ export const CORTEX_MANIFEST_ID = "cortex";
  */
 export const manifestSchema = z.strictObject({
     /** Fixed for the deployment it describes: the rows an apply owns carry it. */
-    id: slugSchema,
-    agents: listOf(MANIFEST_NAME_FIELDS.agents, manifestAgentSchema),
-    tools: listOf(MANIFEST_NAME_FIELDS.tools, manifestToolSchema),
-    openapi: listOf("name", manifestOpenApiSchema),
-    services: listOf(MANIFEST_NAME_FIELDS.services, manifestServiceSchema),
-    skills: listOf(MANIFEST_NAME_FIELDS.skills, manifestSkillSchema),
-    triggers: listOf(MANIFEST_NAME_FIELDS.triggers, manifestTriggerSchema),
-    datasetHosts: listOf(MANIFEST_NAME_FIELDS.datasetHosts, manifestDatasetHostSchema),
-    mcpServers: listOf(MANIFEST_NAME_FIELDS.mcpServers, manifestMcpServerSchema),
-    webhooks: listOf(MANIFEST_NAME_FIELDS.webhooks, manifestWebhookSchema),
-    collections: listOf(MANIFEST_NAME_FIELDS.collections, manifestCollectionSchema),
+    id: nameSchema,
+    agents: listOf(manifestAgentSchema),
+    tools: listOf(manifestToolSchema),
+    openapi: listOf(manifestOpenApiSchema),
+    services: listOf(manifestServiceSchema),
+    skills: listOf(manifestSkillSchema),
+    triggers: listOf(manifestTriggerSchema),
+    datasetHosts: listOf(manifestDatasetHostSchema),
+    mcpServers: listOf(manifestMcpServerSchema),
+    webhooks: listOf(manifestWebhookSchema),
+    collections: listOf(manifestCollectionSchema),
 } satisfies Record<ManifestKind | "id" | "openapi", z.ZodType>);
 /** A manifest as written: every field with a default may be left out. */
 export type Manifest = z.input<typeof manifestSchema>;
@@ -1633,15 +1629,12 @@ export type Manifest = z.input<typeof manifestSchema>;
  * beside it.
  */
 export const resolvedManifestSchema = manifestSchema.extend({
-    collections: listOf(MANIFEST_NAME_FIELDS.collections, resolvedCollectionSchema),
+    collections: listOf(resolvedCollectionSchema),
 });
 
 const manifestKindSchema = z.enum(MANIFEST_KINDS);
 
-/**
- * Entry names per kind, each by its `MANIFEST_NAME_FIELDS` field. An OpenAPI
- * source's operations are counted among `tools`.
- */
+/** Entry names per kind. An OpenAPI source's operations are counted among `tools`. */
 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. */

package/src/contracts/server/index.ts

@@ -18,10 +18,6 @@ import { APPROVAL_TITLE_FIELD, LOCALES } from "../wire/index";
 /** 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);
-
 /** The longest end-user id Cortex stores. */
 export const USER_ID_MAX_LENGTH = 255;
 
@@ -40,9 +36,35 @@ export const IDENTIFIER_MAX_LENGTH = 64;
 
 export const identifierSchema = z.string().regex(IDENTIFIER_PATTERN).max(IDENTIFIER_MAX_LENGTH);
 
+/**
+ * A kebab name: lowercase letters and digits in words joined by single
+ * hyphens. What the manifest id and every name Cortex holds must be, save a
+ * tool's, an MCP server's and a dataset host's, and what its routes name an
+ * agent by.
+ */
+export const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** The longest kebab name Cortex stores. */
+export const NAME_MAX_LENGTH = 64;
+
+export const nameSchema = z.string().regex(NAME_PATTERN).max(NAME_MAX_LENGTH);
+
 /** A localized value's key. */
 export const localeSchema = z.enum(LOCALES);
 
+/** The longest display name Cortex stores, in any locale. */
+export const DISPLAY_NAME_MAX_LENGTH = 120;
+
+/**
+ * What a console shows an entity as, per locale; a locale without one falls
+ * back as `localized` says, and an entity with none goes by its name. Each
+ * value is trimmed, and a blank one is dropped as absent.
+ */
+export const displayNameSchema = z
+    .partialRecord(localeSchema, z.string().trim().max(DISPLAY_NAME_MAX_LENGTH))
+    .transform((value) => Object.fromEntries(Object.entries(value).filter(([, text]) => text)))
+    .pipe(z.partialRecord(localeSchema, z.string()));
+
 /** How many variables and tools a server's manifest declares at most, and how long each of their texts runs. */
 export const SERVER_MANIFEST_LIMITS = {
     variables: 100,
@@ -146,12 +168,14 @@ 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.
+ * carry. `displayName` is what the console shows it as; the model only ever
+ * sees its name. `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,
+    displayName: displayNameSchema.optional(),
     description: z.string().trim().min(1).max(SERVER_MANIFEST_LIMITS.description),
     inputSchema: jsonSchemaSchema.refine(
         (schema) => schema.type === "object",
@@ -179,7 +203,7 @@ export const EVENT_HEADER = "X-Cortex-Event";
  */
 export const approvalRequestedEventSchema = z.object({
     event: z.literal("approval_requested"),
-    agentSlug: agentSlugSchema,
+    agentName: nameSchema,
     agentId: z.uuid(),
     threadId: z.string(),
     runId: z.string(),
@@ -285,7 +309,7 @@ export const serverManifestSchema = z.object({
 export type ServerManifest = z.infer<typeof serverManifestSchema>;
 
 /** The agent a call is for. */
-const agentSchema = z.object({ id: z.uuid(), slug: agentSlugSchema });
+const agentSchema = z.object({ id: z.uuid(), name: nameSchema });
 
 /** The end user a run acts for, as their token was verified; null for a trigger's run. */
 const serverUserSchema = z

package/src/contracts/triggers/index.ts

@@ -6,7 +6,7 @@ import { TRIGGER_DROP_REASONS, TRIGGER_REASONS } from "../wire/index";
  * Triggers: named entry points on an agent. A firing is one invocation with a
  * payload and starts at most one run. The end user's message is the built-in
  * `message` trigger; every other trigger is fired by a caller over
- * `POST /agents/:agentSlug/triggers/:name` with the trigger's secret as its
+ * `POST /agents/:agentName/triggers/:name` with the trigger's secret as its
  * bearer. These are the shapes Cortex answers that caller with.
  */
 
@@ -26,14 +26,14 @@ export const TRIGGER_OUTCOMES = [
 ] as const;
 export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
 
-/** The engine route of agent `agentSlug`, which the widget chats with and its triggers sit under. */
-export function agentRoute(agentSlug: string) {
-    return `/agents/${encodeURIComponent(agentSlug)}`;
+/** The engine route of agent `agentName`, which the widget chats with and its triggers sit under. */
+export function agentRoute(agentName: string) {
+    return `/agents/${encodeURIComponent(agentName)}`;
 }
 
-/** The engine route a trigger is fired at on agent `agentSlug`; its firings are read and answered under it. */
-export function triggerRoute(agentSlug: string, name: string) {
-    return `${agentRoute(agentSlug)}/triggers/${encodeURIComponent(name)}`;
+/** The engine route a trigger is fired at on agent `agentName`; its firings are read and answered under it. */
+export function triggerRoute(agentName: string, name: string) {
+    return `${agentRoute(agentName)}/triggers/${encodeURIComponent(name)}`;
 }
 
 /** One server tool call a parked run waits on; `POST .../firings/:id/answer` decides it. */
@@ -88,7 +88,7 @@ export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
 export type TriggerFiringResponse = z.infer<typeof triggerFiringResponseSchema>;
 
 /**
- * `POST /agents/:agentSlug/triggers/:name/firings/:id/answer`: the decision on one parked call.
+ * `POST /agents/:agentName/triggers/:name/firings/:id/answer`: the decision on one parked call.
  * A call id is as long as the model provider made it (some carry a signature), so only the
  * request's body limit bounds it.
  */
@@ -98,7 +98,7 @@ export const triggerFiringAnswerSchema = z.object({
 });
 export type TriggerFiringAnswer = z.infer<typeof triggerFiringAnswerSchema>;
 
-/** One row of `GET /agents/:agentSlug/triggers/:name/firings`, and the answer of `.../firings/:id`. */
+/** One row of `GET /agents/:agentName/triggers/:name/firings`, and the answer of `.../firings/:id`. */
 export const triggerFiringRecordSchema = z.object({
     id: z.uuid(),
     triggerName: z.string(),

package/src/contracts/wire/index.ts

@@ -169,6 +169,8 @@ export type ClientToolBinding = {
  * The widget hides UI for anything absent; Cortex enforces each.
  */
 export type AgentCapabilities = {
+    /** The agent's display name per locale, which titles a new chat; `{}` for an agent without one. */
+    displayName: Partial<LocalizedText>;
     attachments: boolean;
     /**
      * False when this caller may not send to the chat: the agent's `message`
@@ -214,6 +216,15 @@ export type Greeting = Record<Locale, string>;
 /** Author-written copy the widget shows verbatim, one string per locale. */
 export type LocalizedText = Record<Locale, string>;
 
+/**
+ * Resolves a per-locale value against `locale`: exact match, then English,
+ * then any entry, so a sparse map still renders something. An entity's
+ * label is `localized(entity.displayName, locale) ?? entity.name`.
+ */
+export function localized<T>(value: Partial<Record<Locale, T>>, locale: Locale) {
+    return value[locale] ?? value.en ?? Object.values(value)[0];
+}
+
 /**
  * Cortex's own tools whose input carries `status`: the model's one-line
  * statement of the call, which the widget draws in place of a generic label.

package/src/management/client.ts

@@ -166,6 +166,8 @@ export function inputSchemaOf(operation: OpenApiOperation) {
 export function managementTarget(profile: { url: string; key: string }) {
     return {
         ...profile,
+        // Every day range a command takes is this machine's days.
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
         fetch: (url: string, init: RequestInit) =>
             fetch(url, init).catch((error: unknown) => {
                 throw new UnreachableError(error);