@m6d/cortex-cli 0.20.0 → 0.22.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);
@@ -1201,23 +1196,68 @@ export const mcpToolNamesSchema = z
     )
     .max(200);
 
-const manifestMcpServerSchema = z.strictObject({
-    /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
-    name: identifierSchema,
-    url: upstreamUrlSchema,
-    headers: declaredHeadersSchema(
-        presentedHeaderSchema.refine(
-            (name) => !mcpTransportHeaders.has(name.toLowerCase()),
-            "a header the MCP transport sets",
-        ),
-        headerSourceSchema,
-    ),
-    /** The server's own tool names to offer; empty offers every tool. */
-    include: mcpToolNamesSchema.default([]),
-    exclude: mcpToolNamesSchema.default([]),
-    audience: audienceSchema,
-    overridable: overridable(["include", "exclude", "headers"]),
+/** Who holds an MCP server's sign-in: one connection an operator makes for every agent, or one per end user of each agent. */
+export const MCP_CONNECTION_OWNERS = ["shared", "endUser"] as const;
+
+/**
+ * How Cortex signs in to an MCP server that takes OAuth: who connects, the
+ * scope it asks for (absent, what the server advertises), and, for an
+ * authorization server that takes neither a client ID document nor dynamic
+ * registration, the credential holding the app registered there beforehand:
+ * an OAuth2 client credentials one naming that server as its issuer.
+ */
+export const mcpSignInSchema = z.strictObject({
+    connects: z.enum(MCP_CONNECTION_OWNERS),
+    scope: z.string().trim().min(1).max(1_000).optional(),
+    credential: nameSchema.optional(),
 });
+export type McpSignIn = z.infer<typeof mcpSignInSchema>;
+
+/**
+ * The index of the Authorization header a server that signs in declares
+ * beside its sign-in, whose token travels under that header; -1 when it
+ * signs in without one, or declares one without signing in.
+ */
+export function authorizationBesideSignIn(server: {
+    signIn?: McpSignIn | null;
+    headers: ReadonlyArray<{ header: string }>;
+}) {
+    return server.signIn
+        ? server.headers.findIndex((entry) => entry.header.toLowerCase() === "authorization")
+        : -1;
+}
+
+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(
+                (name) => !mcpTransportHeaders.has(name.toLowerCase()),
+                "a header the MCP transport sets",
+            ),
+            headerSourceSchema,
+        ),
+        /** Absent, every request carries only its headers. */
+        signIn: mcpSignInSchema.optional(),
+        /** The server's own tool names to offer; empty offers every tool. */
+        include: mcpToolNamesSchema.default([]),
+        exclude: mcpToolNamesSchema.default([]),
+        audience: audienceSchema,
+        overridable: overridable(["displayName", "include", "exclude", "headers", "signIn"]),
+    })
+    .superRefine((server, context) => {
+        const index = authorizationBesideSignIn(server);
+        if (index >= 0) {
+            context.addIssue({
+                code: "custom",
+                path: ["headers", index, "header"],
+                message: "the sign-in's token travels under Authorization",
+            });
+        }
+    });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
 /**
@@ -1226,7 +1266,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 +1280,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 +1414,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,13 +1535,10 @@ 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),
+        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,
@@ -1545,7 +1580,7 @@ const manifestAgentSchema = z
         suggestions: suggestionsSchema.default(() => byLocale(() => [])),
         greeting: greetingSchema.default(() => byLocale(() => "")),
         overridable: overridable([
-            "name",
+            "displayName",
             "prompt",
             "models",
             "settings",
@@ -1592,31 +1627,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([]);
@@ -1634,17 +1652,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>;
@@ -1655,15 +1673,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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { REQUEST_LOCATION_TOOL } from "../client-tools/index";
+import { CONNECT_ACCOUNT_TOOL, REQUEST_LOCATION_TOOL } from "../client-tools/index";
 import { backendErrorSchema } from "../errors/index";
 import { pendingApprovalSchema, TRIGGER_ANSWER_TOOL_NAME } from "../triggers/index";
 import { isRecord, readJsonPointer } from "../json/index";
@@ -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,
@@ -117,6 +139,7 @@ export const BUILT_IN_TOOL_NAMES = [
     "searchRegistries",
     "searchThreadHistory",
     REQUEST_LOCATION_TOOL,
+    CONNECT_ACCOUNT_TOOL,
     TRIGGER_ANSWER_TOOL_NAME,
 ] as const;
 
@@ -146,12 +169,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 +204,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 +310,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

@@ -164,11 +164,54 @@ export type ClientToolBinding = {
     embedOrigin: string;
 };
 
+/**
+ * How the widget connects an end user's account for a `connectAccount`
+ * call, stamped on the call: where the engine starts a sign-in, at the URL
+ * browsers reach it, the agent it is for, and each server the call may
+ * name, by name: its display name, and the scope it still needs when the
+ * account is connected but lacks access.
+ */
+export type ConnectAccountBinding = {
+    startUrl: string;
+    agent: string;
+    servers: Record<string, { displayName: Partial<LocalizedText>; scope?: string }>;
+};
+
+/**
+ * Response of `GET /connections/:server?call=<toolCallId>`: where the
+ * caller's own account stands with the agent's MCP server of that name, for
+ * the card of that `connectAccount` call. `connected` with all a sign-in
+ * may ask for; `pending` while it is not connected, or lacks access a
+ * sign-in may still grant; `refused` once the card's own sign-in came back
+ * without it, or no sign-in may ask again.
+ */
+export type AccountConnection = {
+    status: "connected" | "pending" | "refused";
+};
+
+/**
+ * The form `POST /oauth/start` takes, posted into the window a sign-in runs
+ * in with its bearer in the body, so no link can start one: the console's
+ * operator token and the server's id for the shared connection.
+ */
+export type SharedSignInStart = { operatorToken: string; mcpServerId: string };
+
+/** An end user's own start: their token, their agent, the server's name, and the `connectAccount` call it answers. */
+export type EndUserSignInStart = {
+    token: string;
+    agent: string;
+    server: string;
+    threadId: string;
+    toolCallId: string;
+};
+
 /**
  * What Cortex offers this agent's clients, fetched once at widget startup.
  * 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 +257,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.
@@ -252,6 +304,8 @@ export type ToolCallMetadata = {
     answeredBy?: "client";
     /** Set beside `answeredBy` on a call of a client tool with an embedded page: the widget mounts the embed for it. */
     embed?: ClientToolBinding;
+    /** Set beside `answeredBy` on a `connectAccount` call: the widget starts the sign-in with it. */
+    connect?: ConnectAccountBinding;
 };
 
 /** The `metadata.cortex` a tool call carries, when Cortex stamped one. */