@m6d/cortex-cli 0.12.0 → 0.13.0

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,27 @@ 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.
+ * 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 = {
+    /** The action the approval card names, in the author's words rather than the function's name. */
     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 +202,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 +228,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 +237,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 +257,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 +282,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 },
@@ -227,8 +228,17 @@ export async function callManagement(
     });
     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 +261,13 @@ function queryString(input: Record<string, unknown>) {
     return encoded === "" ? "" : `?${encoded}`;
 }
 
+/** 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,13 +87,13 @@ export function removeProfile(name: string) {
 }
 
 /**
- * The profile a `cc` command runs against: `CORTEX_CC_URL` + `CORTEX_CC_KEY`
+ * The profile a management command runs against: `CORTEX_URL` + `CORTEX_KEY`
  * when both are set (CI, containers), else the named or current entry from
  * the file. `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"];
+    const url = process.env["CORTEX_URL"];
+    const key = process.env["CORTEX_KEY"];
     if (url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
     const store = readStore();
     const chosen = name ?? store.current;