@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/contracts/triggers/index.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+
+/*
+ * 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
+ * bearer. These are the shapes Cortex answers that caller with.
+ */
+
+export const MESSAGE_TRIGGER_NAME = "message";
+
+/** The tool a trigger run with an output schema answers through; no other tool may take its name. */
+export const TRIGGER_ANSWER_TOOL_NAME = "submitAnswer";
+
+export const TRIGGER_OUTCOMES = [
+    "started",
+    /** The run parked on a tool that needs approval; `POST .../firings/:id/answer` resumes it. */
+    "awaiting_approval",
+    "completed",
+    "failed",
+    "rejected",
+    "dropped",
+] as const;
+export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
+
+/**
+ * Why a firing was dropped: the thread was busy with another run, a call on
+ * it waits for a decision (answered 409: decide that firing first), the
+ * daily budget was spent, or the agent's request bucket was.
+ */
+const TRIGGER_DROP_REASONS = ["busy", "approval_pending", "budget", "rate_limited"] as const;
+export type TriggerDropReason = (typeof TRIGGER_DROP_REASONS)[number];
+
+/** One server tool call a parked run waits on; `POST .../firings/:id/answer` decides it. */
+export const pendingApprovalSchema = z.object({
+    toolCallId: z.string(),
+    toolName: z.string(),
+    input: z.unknown(),
+});
+
+export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("started"),
+        threadId: z.uuid(),
+        runId: z.string(),
+    }),
+    /* The shapes a caller that waited (`?wait=`) gets instead of `started`: the run ended, or it parked for a decision. */
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("awaiting_approval"),
+        threadId: z.uuid(),
+        runId: z.string(),
+        approvals: z.array(pendingApprovalSchema),
+    }),
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("completed"),
+        threadId: z.uuid(),
+        runId: z.string(),
+        /** The validated answer when the trigger declares an output schema, else the run's last text (null when it wrote none), cut past 1 MiB with a trailing `…[truncated]`. */
+        output: z.unknown(),
+    }),
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("failed"),
+        threadId: z.uuid(),
+        runId: z.string(),
+        reason: z.string().nullable(),
+    }),
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("dropped"),
+        reason: z.enum(TRIGGER_DROP_REASONS),
+        threadId: z.uuid().nullable(),
+    }),
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("rejected"),
+        issues: z.array(z.object({ path: z.string(), message: z.string() })),
+    }),
+]);
+export type TriggerFiringResponse = z.infer<typeof triggerFiringResponseSchema>;
+
+/**
+ * `POST /agents/:agentSlug/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.
+ */
+export const triggerFiringAnswerSchema = z.object({
+    toolCallId: z.string().min(1),
+    approved: z.boolean(),
+});
+export type TriggerFiringAnswer = z.infer<typeof triggerFiringAnswerSchema>;
+
+/** One row of `GET /agents/:agentSlug/triggers/:name/firings`, and the answer of `.../firings/:id`. */
+export const triggerFiringRecordSchema = z.object({
+    id: z.uuid(),
+    triggerName: z.string(),
+    threadId: z.uuid().nullable(),
+    runId: z.string().nullable(),
+    outcome: z.enum(TRIGGER_OUTCOMES),
+    reason: z.string().nullable(),
+    /** What a completed run answered with, as a fire's `completed` answer carries it; null otherwise. */
+    output: z.unknown(),
+    /** The calls an `awaiting_approval` firing waits on; filled by the single-firing read, empty in the list and for every other outcome. */
+    approvals: z.array(pendingApprovalSchema),
+    createdAt: z.iso.datetime(),
+    finishedAt: z.iso.datetime().nullable(),
+});
+export type TriggerFiringRecord = z.infer<typeof triggerFiringRecordSchema>;

package/src/contracts/wire/index.ts

@@ -1,6 +1,6 @@
 /**
  * The wire contract — every shape that crosses the HTTP/WebSocket boundary
- * between `@m6d/cortex-server` and the client SDKs (`@m6d/cortex-angular`,
+ * between Cortex and the client SDKs (`@m6d/cortex-angular`,
  * `@m6d/cortex-react`).
  *
  * Nothing here has a runtime dependency, and nothing here may grow one: this
@@ -40,6 +40,9 @@ export const ATTACHMENT_MIME_TYPES = [
 
 export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
 
+/** The longest name an attachment takes, uploaded or produced by a tool. */
+export const ATTACHMENT_FILENAME_MAX_LENGTH = 255;
+
 export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
 
 export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
@@ -49,9 +52,11 @@ export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
 export const ATTACHMENT_ORIGINS = ["upload", "tool"] as const;
 export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
 
-export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
-    if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
-    if (sizeBytes > ATTACHMENT_MAX_BYTES) return "size";
+/** Whether an upload fits the attachment policy, judged by the widget before it sends one and by Cortex as it takes one. */
+export function checkAttachmentPolicy(file: { type: string; size: number; name: string }) {
+    if (!ATTACHMENT_MIME_TYPES.some((type) => type === file.type)) return "type";
+    if (file.size > ATTACHMENT_MAX_BYTES) return "size";
+    if (file.name.length > ATTACHMENT_FILENAME_MAX_LENGTH) return "name";
     return "ok";
 }
 
@@ -75,6 +80,15 @@ export type ThreadSummary = {
     trigger?: { name: string };
 };
 
+/**
+ * Body of `POST /threads`. Only a console operator's request is read: its
+ * test thread keeps `variables` as the session the agent's server would
+ * otherwise fill per end user.
+ */
+export type CreateThreadRequest = {
+    variables?: Record<string, string | number | boolean>;
+};
+
 /**
  * Response of `POST /chat/:threadId/abort`. `aborted: false` means there was no
  * live run to abort — the turn had already committed — so the caller must not
@@ -100,9 +114,8 @@ export type TokenUsage = {
 };
 
 /**
- * How to launch one client tool: stamped by the server, per tool name, on
- * the metadata of an assistant message that may carry its pending call. Kept in
- * the message so the binding survives server restarts while a run is parked.
+ * How Cortex opens an embedded client tool's page for one call. Stored on the
+ * call, so the binding survives a restart while a run is parked.
  */
 export type ClientToolBinding = {
     toolId: string;
@@ -113,8 +126,8 @@ export type ClientToolBinding = {
 };
 
 /**
- * What the server offers this agent's clients, fetched once at widget startup.
- * The widget hides UI for anything absent; enforcement stays server-side.
+ * 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 = {
     attachments: boolean;
@@ -127,14 +140,13 @@ export type AgentCapabilities = {
 };
 
 export type MessageMetadata = {
-    /** ISO time the server stored the message; stamped from the row when a transcript is served. */
+    /** ISO time Cortex stored the message; stamped from the row when a transcript is served. */
     createdAt?: string;
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
-    clientTools?: Record<string, ClientToolBinding>;
     /** Set on `trigger` messages: the firing that wrote them. */
     trigger?: TriggerFiringSummary;
 };
@@ -145,7 +157,7 @@ export type MessageMetadata = {
  */
 export type Suggestion = { title: string; prompt: string };
 
-/** The runtime contract's `suggestionsSchema` and `greetingSchema` are built from these. */
+/** The manifest's suggestion and greeting schemas are built from these. */
 export type Suggestions = Record<Locale, Suggestion[]>;
 export type Greeting = Record<Locale, string>;
 
@@ -160,14 +172,32 @@ export type LocalizedText = Record<Locale, string>;
 export const STATEMENT_TOOLS = ["executeCode", "queryDataset", "describeDataset"] as const;
 
 /**
- * What cortex stamps on a tool-call part's `metadata.cortex`: the action the
- * approval card names when the call needs the user's approval, in the
- * author's words rather than the function's name.
+ * The input Cortex adds to every tool that waits for the end user's approval:
+ * the model writes what that one call will do, and the approval card shows it
+ * as its title. Cortex removes it before the call runs.
+ */
+export const APPROVAL_TITLE_FIELD = "approvalTitle";
+
+/**
+ * What Cortex stamps on a tool call's `metadata.cortex` from its first chunk,
+ * so the live part and the stored one agree.
  */
 export type ToolCallMetadata = {
-    approval?: LocalizedText;
+    /**
+     * Set on every call the client answers: a client tool's, the consumer's own, or a built-in
+     * input's. Cortex runs every other call, so only these take an output from a request.
+     */
+    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;
 };
 
+/** The `metadata.cortex` a tool call carries, when Cortex stamped one. */
+export function toolCallMetadataOf(part: { metadata?: unknown }) {
+    const metadata = part.metadata as { cortex?: ToolCallMetadata | null } | null | undefined;
+    return metadata?.cortex ?? undefined;
+}
+
 export type TriggerFiringSummary = {
     name: string;
     firingId: string;
@@ -177,7 +207,7 @@ export type TriggerFiringSummary = {
 
 /**
  * A stored message as it is persisted and served: the SDK's parts plus the
- * server-derived envelope the UIs render, carried in the SDK message's own
+ * envelope Cortex derives for the UIs, carried in the SDK message's own
  * `metadata` bag so it travels with the message over the stream and the
  * transcript alike.
  *
@@ -203,7 +233,7 @@ export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
 
 /**
  * Key under the AG-UI request's `forwardedProps` carrying the answers to
- * parked client tool calls on a continuation request. The server owns the
+ * parked client tool calls on a continuation request. Cortex owns the
  * transcript (a continuation sends `messages: []`), so the answered assistant
  * message itself never crosses the wire — the SDK's park-boundary snapshot
  * does not preserve its id, and round-tripping it would duplicate the stored
@@ -212,7 +242,7 @@ export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
 export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
 
 /**
- * One answered call, applied to the stored transcript server-side: a client
+ * One answered call, which Cortex applies to the stored transcript: a client
  * tool's output (`complete` / `error`), or the user's decision on a server
  * tool that asked for approval (`approved` / `denied`, output null).
  */
@@ -232,19 +262,15 @@ export function approvalIdOf(part: { id: string; approval?: { id: string } }) {
 }
 
 /**
- * Response of `POST /chat/:threadId/tools/:toolCallId/initiate`. `embed:
- * false` means the pending call is not a CC client tool — the widget
- * falls back to its default rendering for the call. The payload is for the
- * widget only; it never reaches the LLM.
+ * Response of `POST /chat/:threadId/tools/:toolCallId/initiate` for a pending
+ * call stamped with an embed. The payload is for the widget only; it never
+ * reaches the LLM.
  */
-export type ClientToolInitiateResult =
-    | { embed: false }
-    | {
-          embed: true;
-          embedUrl: string;
-          surface: ToolSurface;
-          embedOrigin: string;
-      };
+export type ClientToolInitiateResult = {
+    embedUrl: string;
+    surface: ToolSurface;
+    embedOrigin: string;
+};
 
 export type ThreadCreatedEvent = {
     type: "thread:created";
@@ -261,14 +287,22 @@ export type ThreadTitleUpdatedEvent = {
     payload: { thread: ThreadSummary };
 };
 
+/** Run `runId` took the thread; the `thread:run-finished` naming the same run ends it. */
 export type ThreadRunStartedEvent = {
     type: "thread:run-started";
-    payload: { thread: ThreadSummary };
+    payload: { thread: ThreadSummary; runId: string };
 };
 
+/**
+ * Run `runId` ended, committed or not, and left the thread free, so it takes
+ * a new message now; whatever turn it committed is in the transcript. Sent
+ * only for a run announced as started, and never by one whose thread another
+ * run had already taken, so a finish naming a run other than the one a
+ * client saw start last is stale.
+ */
 export type ThreadRunFinishedEvent = {
     type: "thread:run-finished";
-    payload: { thread: ThreadSummary };
+    payload: { thread: ThreadSummary; runId: string };
 };
 
 export type ThreadMessagesUpdatedEvent = {

package/src/{cc → management}/client.ts

@@ -10,7 +10,7 @@ export type OpenApiOperation = {
     operationId: string;
     summary?: string;
     tags?: string[];
-    /** The Control Center's own semantics, so nothing here is inferred from names or prose. */
+    /** Cortex's own semantics, so nothing here is inferred from names or prose. */
     "x-destructive"?: true;
     "x-publish-procedure"?: string;
     "x-live-fields"?: string[];
@@ -29,7 +29,8 @@ export type JsonSchema = {
     properties?: Record<string, JsonSchema>;
     required?: string[];
     enum?: unknown[];
-    items?: JsonSchema;
+    /** `false` on a tuple, whose positions `prefixItems` lists instead. */
+    items?: JsonSchema | boolean;
     anyOf?: JsonSchema[];
     default?: unknown;
     description?: string;
@@ -45,7 +46,7 @@ export type OpenApiDocument = {
 type Cached = { etag: string; document: OpenApiDocument };
 
 /**
- * One cache entry per Control Center base URL (scheme, host, port, path),
+ * One cache entry per Cortex base URL (scheme, host, port, path),
  * so an http and an https profile, or two deployments under one host, never
  * read each other's document. The host keeps the file recognizable; a hash
  * of the whole URL keeps two URLs from ever sharing a name.
@@ -85,7 +86,7 @@ const SCHEMA_FIELDS = {
     properties: optional(recordOf(isJsonSchema)),
     required: optional(isStrings),
     enum: optional(Array.isArray),
-    items: optional(isJsonSchema),
+    items: optional((v) => typeof v === "boolean" || isJsonSchema(v)),
     anyOf: optional(arrayOf(isJsonSchema)),
     description: optional(isString),
     format: optional(isString),
@@ -207,7 +208,7 @@ export function inputSchemaOf(operation: OpenApiOperation) {
  * string, one parameter per field, with a scalar written plainly and
  * anything else JSON-encoded, which is how the document declares it. A
  * mutation posts its input as the JSON body. A refusal throws
- * `ManagementError` with the error body's code and message.
+ * `ManagementError` with the error body's code, message and detail.
  */
 export async function callManagement(
     profile: { url: string; key: string },
@@ -224,11 +225,22 @@ export async function callManagement(
             ...(method === "post" ? { "Content-Type": "application/json" } : {}),
         },
         body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
+    }).catch((error: unknown) => {
+        throw new UnreachableError(error);
     });
     const body: unknown = await response.json().catch(() => null);
     if (!response.ok) {
-        const { code, message } = (body ?? {}) as { code?: string; message?: string };
-        throw new ManagementError(response.status, code ?? "error", message ?? response.statusText);
+        const { code, message, cause } = (body ?? {}) as {
+            code?: string;
+            message?: string;
+            cause?: unknown;
+        };
+        throw new ManagementError(
+            response.status,
+            code ?? "error",
+            message ?? response.statusText,
+            isRecord(cause) ? cause : undefined,
+        );
     }
     return body;
 }
@@ -251,11 +263,25 @@ function queryString(input: Record<string, unknown>) {
     return encoded === "" ? "" : `?${encoded}`;
 }
 
+/**
+ * Cortex did not answer at all: refused, reset, unresolvable. `fetch` rejects
+ * only for these, with whatever its runtime throws (Bun's is a plain `Error`
+ * with a `code`), so `callManagement` names them once here.
+ */
+export class UnreachableError extends Error {
+    public constructor(cause: unknown) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = "UnreachableError";
+    }
+}
+
+/** A refusal; `detail` is what the refusal names, when it names something (an entry, the row holding a name). */
 export class ManagementError extends Error {
     public constructor(
         public readonly status: number,
         public readonly code: string,
         message: string,
+        public readonly detail?: Record<string, unknown>,
     ) {
         super(message);
         this.name = "ManagementError";

package/src/{cc → management}/flags.ts

@@ -44,7 +44,8 @@ function kindOf(property: JsonSchema, document: OpenApiDocument) {
     if (type === "number" || type === "integer") return "number" as const;
     if (type === "boolean") return "boolean" as const;
     if (type === "array") {
-        const item = property.items ? resolve(property.items, document) : undefined;
+        const item =
+            typeof property.items === "object" ? resolve(property.items, document) : undefined;
         const scalar = item && ["string", "number", "integer"].includes(typeOf(item) ?? "");
         return scalar ? ("array" as const) : ("json" as const);
     }

package/src/{cc → management}/profiles.ts

@@ -7,9 +7,9 @@ import { isRecord } from "@cortex/contracts/json";
 type Profile = { url: string; key: string };
 type Store = { current: string; profiles: Record<string, Profile> };
 
-/** `~/.cortex/cc.json`; `CORTEX_HOME` relocates it (tests, CI). */
+/** `~/.cortex/profiles.json`; `CORTEX_HOME` relocates it (tests, CI). */
 export function profilesPath() {
-    return join(process.env["CORTEX_HOME"] ?? join(homedir(), ".cortex"), "cc.json");
+    return join(process.env["CORTEX_HOME"] ?? join(homedir(), ".cortex"), "profiles.json");
 }
 
 /** Thrown when the profile file exists but is not one this CLI wrote. */
@@ -87,14 +87,16 @@ export function removeProfile(name: string) {
 }
 
 /**
- * The profile a `cc` command runs against: `CORTEX_CC_URL` + `CORTEX_CC_KEY`
- * when both are set (CI, containers), else the named or current entry from
- * the file. `undefined` means nobody has logged in.
+ * The profile a management command runs against: the entry `name` picks from
+ * the file, else `CORTEX_URL` + `CORTEX_KEY` when both are set (CI, containers,
+ * a project's .env), else the current entry. A name always wins, so `-p prod`
+ * inside a project whose .env points at its own Cortex still reaches prod.
+ * `undefined` means nobody has logged in.
  */
 export function resolveProfile(name?: string) {
-    const url = process.env["CORTEX_CC_URL"];
-    const key = process.env["CORTEX_CC_KEY"];
-    if (url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
+    const url = process.env["CORTEX_URL"];
+    const key = process.env["CORTEX_KEY"];
+    if (name === undefined && url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
     const store = readStore();
     const chosen = name ?? store.current;
     const profile = lookup(store, chosen);