@m6d/cortex-cli 0.15.0 → 0.17.0

package/src/contracts/server/index.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { REQUEST_LOCATION_TOOL } from "../client-tools/index";
 import { backendErrorSchema } from "../errors/index";
 import { pendingApprovalSchema, TRIGGER_ANSWER_TOOL_NAME } from "../triggers/index";
-import { isRecord, unescapePointerToken } from "../json/index";
+import { isRecord, readJsonPointer } from "../json/index";
 import { APPROVAL_TITLE_FIELD, LOCALES } from "../wire/index";
 
 /*
@@ -22,8 +22,11 @@ export const END_USER_TOKEN_HEADER = "X-End-User-Token";
 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;
+
 /** An end user's id, as wide as Cortex stores one. */
-export const userIdSchema = z.string().max(255);
+export const userIdSchema = z.string().max(USER_ID_MAX_LENGTH);
 
 /**
  * An ASCII JavaScript identifier: what a tool name (a `tools.<name>()`
@@ -32,8 +35,22 @@ export const userIdSchema = z.string().max(255);
  */
 export const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 
+/** The longest identifier Cortex stores, for tool, variable and MCP server names alike. */
+export const IDENTIFIER_MAX_LENGTH = 64;
+
+export const identifierSchema = z.string().regex(IDENTIFIER_PATTERN).max(IDENTIFIER_MAX_LENGTH);
+
+/** A localized value's key. */
 export const localeSchema = z.enum(LOCALES);
 
+/** 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,
+    tools: 500,
+    description: 500,
+    example: 200,
+} as const;
+
 /** The value one thread's variable holds: what its server fills, or an operator sets on a test thread. */
 const variableValueSchema = z.union([z.string(), z.number(), z.boolean()]);
 
@@ -46,9 +63,9 @@ export const variableValuesSchema = z.record(z.string(), variableValueSchema);
  * prompts and as tool input sources alike.
  */
 export const variableDeclarationSchema = z.object({
-    name: z.string().regex(IDENTIFIER_PATTERN).max(64),
-    description: z.string().max(500),
-    example: z.string().max(200),
+    name: identifierSchema,
+    description: z.string().max(SERVER_MANIFEST_LIMITS.description),
+    example: z.string().max(SERVER_MANIFEST_LIMITS.example),
     /** The type its value takes. */
     type: z.enum(["string", "number", "boolean"]),
     /** Computed by Cortex for every thread; no server can set it. */
@@ -86,8 +103,8 @@ export const BUILT_IN_VARIABLES = [
 
 /**
  * The names of Cortex's built-in tools. No other tool may take one: the
- * model would see two tools under one name. The .NET SDK holds its own copy,
- * checked against `reserved-names.fixtures.json`.
+ * model would see two tools under one name. `constants.fixtures.json`
+ * carries them to the .NET SDK.
  */
 export const BUILT_IN_TOOL_NAMES = [
     "describeDataset",
@@ -107,30 +124,22 @@ export function isBuiltInToolName(name: string) {
     return BUILT_IN_TOOL_NAMES.some((builtIn) => builtIn === name);
 }
 
-/** The longest name a tool takes, a server's or one defined in Cortex. */
-export const TOOL_NAME_MAX_LENGTH = 64;
-
 /** A tool name, a server's or one defined in Cortex: an identifier no built-in tool holds. */
-const declaredToolNameSchema = z
-    .string()
-    .regex(IDENTIFIER_PATTERN)
-    .max(TOOL_NAME_MAX_LENGTH)
-    .refine((name) => !isBuiltInToolName(name), "the name of a built-in tool");
+const declaredToolNameSchema = identifierSchema.refine(
+    (name) => !isBuiltInToolName(name),
+    "the name of a built-in tool",
+);
 
 const jsonSchemaSchema = z.record(z.string(), z.unknown());
 
 /** A variable the server fills for its agents' threads; the built-in ones are Cortex's. */
 const serverVariableSchema = z.object({
-    name: z
-        .string()
-        .regex(IDENTIFIER_PATTERN)
-        .max(64)
-        .refine(
-            (name) => !BUILT_IN_VARIABLES.some((builtIn) => builtIn.name === name),
-            "the name of a built-in variable",
-        ),
-    description: z.string().max(500),
-    example: z.string().max(200),
+    name: identifierSchema.refine(
+        (name) => !BUILT_IN_VARIABLES.some((builtIn) => builtIn.name === name),
+        "the name of a built-in variable",
+    ),
+    description: z.string().max(SERVER_MANIFEST_LIMITS.description),
+    example: z.string().max(SERVER_MANIFEST_LIMITS.example),
     type: variableDeclarationSchema.shape.type,
 });
 export type ServerVariable = z.infer<typeof serverVariableSchema>;
@@ -143,7 +152,7 @@ export type ServerVariable = z.infer<typeof serverVariableSchema>;
  */
 export const serverToolSchema = z.object({
     name: declaredToolNameSchema,
-    description: z.string().trim().min(1).max(500),
+    description: z.string().trim().min(1).max(SERVER_MANIFEST_LIMITS.description),
     inputSchema: jsonSchemaSchema.refine(
         (schema) => schema.type === "object",
         "a tool's input is an object",
@@ -182,27 +191,9 @@ export const approvalRequestedEventSchema = z.object({
 });
 export type ApprovalRequestedEvent = z.infer<typeof approvalRequestedEventSchema>;
 
-/** A JSON Pointer token as a key: percent-decoded, then unescaped; undefined when its encoding is broken. */
-function pointerKey(token: string) {
-    try {
-        return unescapePointerToken(decodeURIComponent(token));
-    } catch {
-        return undefined;
-    }
-}
-
 /** What a local `$ref` (`#/$defs/order`) points at in `root`, read as the input compiler reads it; undefined for any other. */
 function pointedAt(root: unknown, ref: string) {
-    if (!ref.startsWith("#")) return undefined;
-    let node = root;
-    for (const token of ref.slice(1).split("/").slice(1)) {
-        const key = pointerKey(token);
-        node =
-            key !== undefined && (isRecord(node) || Array.isArray(node))
-                ? new Map<string, unknown>(Object.entries(node)).get(key)
-                : undefined;
-    }
-    return node;
+    return ref.startsWith("#") ? readJsonPointer(root, ref) : undefined;
 }
 
 /** Whether one schema node names `APPROVAL_TITLE_FIELD` as a property or a required field. */
@@ -259,18 +250,15 @@ export function blocksApprovalTitle(inputSchema: unknown) {
     );
 }
 
-/** Refuses, under `path`, a tool that needs approval whose input `blocksApprovalTitle`. */
+/** Refuses, under `path` and with `message`, a tool that needs approval whose input `blocksApprovalTitle`. */
 export function refuseBlockedApprovalTitle(
     tool: { requiresApproval?: boolean; inputSchema: unknown },
     context: z.RefinementCtx,
     path: Array<string | number>,
+    message = `a tool that needs approval cannot take an input named ${APPROVAL_TITLE_FIELD}, nor one a closed sub-schema describes: Cortex adds the approval card's title to it`,
 ) {
     if (!tool.requiresApproval || !blocksApprovalTitle(tool.inputSchema)) return;
-    context.addIssue({
-        code: "custom",
-        path: [...path, "inputSchema"],
-        message: `a tool that needs approval cannot take an input named ${APPROVAL_TITLE_FIELD}, nor one a closed sub-schema describes: Cortex adds the approval card's title to it`,
-    });
+    context.addIssue({ code: "custom", path: [...path, "inputSchema"], message });
 }
 
 function uniqueNames(entries: ReadonlyArray<{ name: string }>) {
@@ -280,10 +268,13 @@ function uniqueNames(entries: ReadonlyArray<{ name: string }>) {
 /** `GET /`: everything the server offers, keyed by `version`, which changes whenever anything else does. */
 export const serverManifestSchema = z.object({
     version: z.string().min(1).max(128),
-    variables: z.array(serverVariableSchema).max(100).refine(uniqueNames, "variable names repeat"),
+    variables: z
+        .array(serverVariableSchema)
+        .max(SERVER_MANIFEST_LIMITS.variables)
+        .refine(uniqueNames, "variable names repeat"),
     tools: z
         .array(serverToolSchema)
-        .max(500)
+        .max(SERVER_MANIFEST_LIMITS.tools)
         .refine(uniqueNames, "tool names repeat")
         .superRefine((tools, context) => {
             tools.forEach((tool, index) => refuseBlockedApprovalTitle(tool, context, [index]));

package/src/contracts/triggers/index.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+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
@@ -24,13 +26,15 @@ export const TRIGGER_OUTCOMES = [
 ] 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];
+/** 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 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)}`;
+}
 
 /** One server tool call a parked run waits on; `POST .../firings/:id/answer` decides it. */
 export const pendingApprovalSchema = z.object({
@@ -67,7 +71,7 @@ export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
         outcome: z.literal("failed"),
         threadId: z.uuid(),
         runId: z.string(),
-        reason: z.string().nullable(),
+        reason: z.enum(TRIGGER_REASONS).nullable(),
     }),
     z.object({
         firingId: z.uuid(),
@@ -101,7 +105,7 @@ export const triggerFiringRecordSchema = z.object({
     threadId: z.uuid().nullable(),
     runId: z.string().nullable(),
     outcome: z.enum(TRIGGER_OUTCOMES),
-    reason: z.string().nullable(),
+    reason: z.enum(TRIGGER_REASONS).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. */

package/src/contracts/wire/index.ts

@@ -8,10 +8,25 @@
  * alike.
  */
 
-/** The UI locales every localized value is keyed by. */
+/** The UI locales every localized value is keyed by; the console's message catalogs follow it. */
 export const LOCALES = ["en", "ar"] as const;
 export type Locale = (typeof LOCALES)[number];
 
+/** The locale a value falls back to, and the one a service is known by. */
+export const BASE_LOCALE = LOCALES[0];
+
+/** The way each locale's script runs, which the console lays its text out by. */
+export const LOCALE_DIRECTIONS = { en: "ltr", ar: "rtl" } as const satisfies Record<
+    Locale,
+    "ltr" | "rtl"
+>;
+
+/** A localized value with one entry per locale, each `valueOf` that locale. */
+export function byLocale<T>(valueOf: (locale: Locale) => T) {
+    const entries = LOCALES.map((locale) => [locale, valueOf(locale)] as const);
+    return Object.fromEntries(entries) as Record<Locale, T>;
+}
+
 /** Where an embedded client tool renders: in the message flow or in a modal. */
 export const TOOL_SURFACES = ["inline", "modal"] as const;
 export type ToolSurface = (typeof TOOL_SURFACES)[number];
@@ -70,6 +85,32 @@ export type AttachmentSummary = {
     description: string | null;
 };
 
+/**
+ * How an anonymous agent's visitors' user ids begin: Cortex issues each
+ * visitor an id of its own, which their browser keeps. No issuer ever mints
+ * a subject shaped like this.
+ */
+export const VISITOR_USER_PREFIX = "visitor:";
+
+/** The reCAPTCHA action a visitor's sign-in runs, which Cortex checks the token was made for. */
+export const VISITOR_RECAPTCHA_ACTION = "cortex_visitor";
+
+/** `POST /visitors`: a visitor's sign-in to an anonymous agent, with a reCAPTCHA token when the agent checks visitors. */
+export type VisitorRequest = { recaptcha?: string };
+
+/** A visitor's token, the bearer of every request after the sign-in. */
+export type VisitorToken = { token: string };
+
+/**
+ * Why a sign-in got no token: the agent checks visitors with reCAPTCHA and
+ * the request carried no token, or one that failed. `siteKey` is the key the
+ * widget runs reCAPTCHA with.
+ */
+export type VisitorRefusal = {
+    error: "recaptcha_required" | "recaptcha_failed";
+    siteKey: string;
+};
+
 export type ThreadSummary = {
     id: string;
     title: string | null;
@@ -121,8 +162,6 @@ export type ClientToolBinding = {
     toolId: string;
     surface: ToolSurface;
     embedOrigin: string;
-    /** Variables the initiate call's input reads. */
-    variables: string[];
 };
 
 /**
@@ -189,11 +228,16 @@ export const STATEMENT_TOOLS = ["executeCode", "queryDataset", "describeDataset"
  */
 export const APPROVAL_TITLE_FIELD = "approvalTitle";
 
+/** A line the model wrote into a call input's `field`, trimmed; undefined while it streams in or is blank. */
+export function modelLineOf(input: unknown, field: string) {
+    if (!input || typeof input !== "object") return undefined;
+    const line: unknown = Reflect.get(input, field);
+    return typeof line === "string" && line.trim() ? line.trim() : undefined;
+}
+
 /** The title the model wrote into an approval call's input, or undefined while it has none. */
 export function approvalTitleOf(input: unknown) {
-    if (!input || typeof input !== "object" || !(APPROVAL_TITLE_FIELD in input)) return undefined;
-    const title: unknown = input[APPROVAL_TITLE_FIELD];
-    return typeof title === "string" && title.trim() ? title.trim() : undefined;
+    return modelLineOf(input, APPROVAL_TITLE_FIELD);
 }
 
 /**
@@ -260,16 +304,27 @@ export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
 export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
 
 /**
- * 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).
+ * How a call was answered: a client tool's output (`complete` / `error`), or
+ * the user's decision on a server tool that asked for approval
+ * (`approved` / `denied`).
+ */
+export const CLIENT_TOOL_ANSWER_STATES = ["complete", "error", "approved", "denied"] as const;
+
+/**
+ * One answered call, which Cortex applies to the stored transcript. A
+ * decision carries a null output.
  */
 export type ClientToolAnswer = {
     toolCallId: string;
     output: unknown;
-    state: "complete" | "error" | "approved" | "denied";
+    state: (typeof CLIENT_TOOL_ANSWER_STATES)[number];
 };
 
+/** Whether the answer is the user's decision on a call that asked for approval, rather than a tool's output. */
+export function isDecision(answer: Pick<ClientToolAnswer, "state">) {
+    return answer.state === "approved" || answer.state === "denied";
+}
+
 /**
  * The id a parked tool call's decision is filed under: the one on its
  * approval record, or `approval_<toolCallId>`, which is how the SDK names
@@ -279,6 +334,11 @@ export function approvalIdOf(part: { id: string; approval?: { id: string } }) {
     return part.approval?.id ?? `approval_${part.id}`;
 }
 
+/** Whether a tool call asked the user for approval: it carries an approval record, or waits for one. */
+export function askedApproval(part: { approval?: unknown; state?: string }) {
+    return part.approval !== undefined || part.state === "approval-requested";
+}
+
 /**
  * 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
@@ -328,40 +388,102 @@ export type ThreadMessagesUpdatedEvent = {
     payload: { thread: ThreadSummary };
 };
 
-export type ToolProgressEvent = {
-    type: "thread:tool-progress";
-    payload: {
-        threadId: string;
-        toolCallId: string;
-        toolName: string;
-        status: "started" | "finished";
-    };
-};
-
 export type WsEvent =
     | ThreadCreatedEvent
     | ThreadDeletedEvent
     | ThreadTitleUpdatedEvent
     | ThreadRunStartedEvent
     | ThreadRunFinishedEvent
-    | ThreadMessagesUpdatedEvent
-    | ToolProgressEvent;
+    | ThreadMessagesUpdatedEvent;
 
 /** The header the widget sends the browser's IANA time zone in; the turn reasons in that clock. */
 export const TIMEZONE_HEADER = "X-Cortex-Timezone";
 
 /**
- * The console operator's short-lived token, sent by the playground and the
- * thread inspector on every request to an agent and by the fire and answer
- * calls Cortex makes to a trigger's route. A verified one makes the operator the caller unless the
- * request also carries an end-user token to test as, and marks the threads it
- * opens as test threads. A WebSocket upgrade carries it as `?operator=`.
+ * The header carrying a console operator's token, sent by the playground and
+ * the thread inspector on every request to an agent and by the fire and
+ * answer calls Cortex makes to a trigger's route. A verified one makes the
+ * operator the caller unless the request also carries an end-user token to
+ * test as, and marks the threads it opens as test threads. A WebSocket
+ * upgrade carries it as `?operator=`.
  */
 export const OPERATOR_HEADER = "X-Cortex-Operator";
 
 /**
  * Beside the operator token, the id of a thread the operator inspects: the
  * request then reads as that thread's owner, read-only, with the debug view.
+ * The engine refuses any request carrying it but a read (GET, HEAD, OPTIONS),
+ * on every agent route.
  * A WebSocket upgrade carries it as `?inspect=`.
  */
 export const INSPECT_HEADER = "X-Cortex-Inspect";
+
+/**
+ * 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.
+ */
+export const TRIGGER_DROP_REASONS = ["busy", "approval_pending", "budget", "rate_limited"] as const;
+export type TriggerDropReason = (typeof TRIGGER_DROP_REASONS)[number];
+
+/**
+ * Every reason a firing records beside its outcome: why it was dropped, why
+ * its payload was rejected (`invalid_payload`, `missing_thread_key`), that
+ * no turn ran for it (`no_turn`), or why a run with an output schema failed
+ * without an answer the schema accepted (`no_output`, `invalid_output`).
+ */
+export const TRIGGER_REASONS = [
+    ...TRIGGER_DROP_REASONS,
+    "invalid_payload",
+    "missing_thread_key",
+    "no_turn",
+    "no_output",
+    "invalid_output",
+] as const;
+export type TriggerReason = (typeof TRIGGER_REASONS)[number];
+
+/**
+ * Body of a `POST /chat` the thread did not take: 409 while a run holds the
+ * thread or a call on it waits for a decision, or when the answers it
+ * carried fit no open call, were already applied, or answer a call whose
+ * origin is out of reach (`no_turn`); 429 once the agent's request bucket is
+ * spent, with `Retry-After`.
+ */
+export type ChatDropped = {
+    outcome: "dropped";
+    reason: Exclude<TriggerDropReason, "budget"> | "no_turn";
+};
+
+/**
+ * The drop a widget tells its user about by name: a call on the thread waits
+ * for approval, so the message goes back to the composer. Any other drop
+ * shows as a failed turn.
+ */
+export type SendRefusal = Extract<ChatDropped["reason"], "approval_pending">;
+
+/**
+ * What became of the client tool answers a `POST /chat` carried, by the
+ * status Cortex answered it with, apart from how the run it started goes.
+ * `persisted` (2xx): Cortex took them up, and sending them again changes
+ * nothing. `refused` (4xx, a `ChatDropped` among them): it did not take
+ * them up as given, and the stored transcript says what stands. `lost`
+ * (5xx, or no answer at all): its word never came, and only the stored
+ * transcript can tell.
+ */
+export function answersReceiptOf(status: number) {
+    if (status >= 500) return "lost";
+    return status >= 400 ? "refused" : "persisted";
+}
+export type AnswersReceipt = ReturnType<typeof answersReceiptOf>;
+
+/**
+ * One model call of the turn that wrote a message, raw, in the order the
+ * turn ran them: `GET /threads/:threadId/messages/:messageId/llm-requests`
+ * answers a list, for the request inspector.
+ */
+export type LlmRequest = {
+    id: string;
+    prompt: string;
+    output: string | null;
+    tokenUsage: TokenUsage | null;
+};