@m6d/cortex-cli 0.1.0

package/src/contracts/runtime/triggers.ts

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import { datasetIdentifierSchema } from "./datasets";
+import {
+    agentSlugSchema,
+    localizedTextSchema,
+    mentionedToolSchema,
+    sha256HexSchema,
+    slugSchema,
+} from "./grammar";
+
+/*
+ * 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 an external caller over
+ * `POST /agents/:agentSlug/triggers/:name` on the server with the trigger's
+ * own secret. Two directions live here: what cc publishes to the server
+ * (declarations, secret checks) and what the server answers a caller.
+ */
+
+export const MESSAGE_TRIGGER_NAME = "message";
+
+/**
+ * The first characters of a fire bearer say what it is: the secret callers
+ * hold, or a one-shot test token the console minted. A test token is a JWT
+ * the Control Center signed, so a server verifies it against the Control
+ * Center's JWKS before saying a word to it, and the Control Center then
+ * consumes it so it fires once.
+ */
+export const TRIGGER_SECRET_PREFIXES = { live: "tr_live_", test: "tr_test_" } as const;
+export const TRIGGER_TEST_TOKEN_AUDIENCE = "cortex:trigger-test";
+
+/** The claims a test token carries beside the standard ones; the server checks them against the route it arrived on. */
+export const triggerTestTokenClaimsSchema = z.object({
+    agent: agentSlugSchema,
+    trigger: slugSchema,
+});
+
+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",
+    "disabled",
+] as const;
+export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
+
+/** Why a firing was dropped: the thread was busy, or the daily budget was spent. */
+export const TRIGGER_DROP_REASONS = ["busy", "budget"] as const;
+export type TriggerDropReason = (typeof TRIGGER_DROP_REASONS)[number];
+
+export const TRIGGER_SOURCES = ["code", "cc"] as const;
+export type TriggerSource = (typeof TRIGGER_SOURCES)[number];
+
+/**
+ * Which thread a firing lands in. `single`: one thread for the trigger.
+ * `per-firing`: a fresh thread every time. `ephemeral`: a fresh thread that
+ * is deleted once the run completes, for one-shot calls: the answer reaches
+ * the caller as the firing's output or through the live stream, and nothing
+ * else outlives the run; a failed run keeps its thread for inspection. `keyed`:
+ * one thread per distinct value at a JSON pointer into the payload (e.g.
+ * `/pull_request/number`).
+ */
+export const triggerThreadPolicySchema = z.discriminatedUnion("policy", [
+    z.object({ policy: z.literal("single") }),
+    z.object({ policy: z.literal("per-firing") }),
+    z.object({ policy: z.literal("ephemeral") }),
+    z.object({ policy: z.literal("keyed"), key: z.string().regex(/^\//).max(256) }),
+]);
+export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
+
+/* cc publishes to the server. */
+
+/**
+ * A tool a trigger's instructions mention. Most are sandbox bindings; one
+ * that parks for approval is declared to the model as a function call
+ * instead, so it carries what that takes, as a /resolve signature does: a run
+ * started by a trigger has no other way to learn it.
+ */
+const triggerMentionedToolSchema = z.discriminatedUnion("requiresApproval", [
+    mentionedToolSchema.extend({ requiresApproval: z.literal(false) }),
+    mentionedToolSchema.extend({
+        requiresApproval: z.literal(true),
+        signature: z.string(),
+        inputSchema: z.record(z.string(), z.unknown()),
+        approvalMessage: localizedTextSchema.optional(),
+    }),
+]);
+
+/** A trigger as both sides describe it. Secrets and credentials never cross this contract. */
+export const triggerDeclarationSchema = z.object({
+    name: slugSchema,
+    description: z.string().max(500),
+    /** JSON Schema for the payload; cc triggers are validated from it on the server. */
+    input: z.record(z.string(), z.unknown()),
+    /**
+     * JSON Schema the run's answer must match, or null for a free-text run.
+     * The server asks the model for that shape, validates what comes back,
+     * and stores it as the firing's `output`; a run whose answer does not
+     * parse fails with reason `invalid_output`.
+     */
+    output: z.record(z.string(), z.unknown()).nullable(),
+    /**
+     * The prompt the run starts from, mentions already rendered to names by
+     * the console; `{{variables}}` and `{{/json/pointer}}` payload fields
+     * are the server's to fill per firing.
+     */
+    instructions: z.string().max(20_000),
+    /** Tools the instructions mention: sandbox bindings for the run, or declared to the model when they park for approval. */
+    mentionedTools: z.array(triggerMentionedToolSchema),
+    /** Datasets the instructions mention, listed in the run's context whatever the question. */
+    mentionedDatasets: z.array(datasetIdentifierSchema),
+    threadPolicy: triggerThreadPolicySchema,
+    budgetPerDay: z.number().int().positive().nullable(),
+    /** Consecutive failed or rejected firings before the trigger disables itself. */
+    disableAfterFailures: z.number().int().positive(),
+    hasCredential: z.boolean(),
+    /**
+     * sha256 of the fire secret, so a server checks a presented bearer in
+     * process; the Control Center hears only about console test secrets,
+     * which it alone can consume.
+     */
+    secretHash: sha256HexSchema,
+});
+export type TriggerDeclaration = z.infer<typeof triggerDeclarationSchema>;
+
+/**
+ * `POST /api/runtime/agents/:agentSlug/triggers/:name/auth`: a server holding a
+ * bearer for a cc trigger asks cc whether it is the trigger's secret. Only the
+ * hash travels; a positive answer carries the trigger's credential, if any.
+ */
+export const triggerAuthRequestSchema = z.object({
+    secretHash: sha256HexSchema,
+});
+export type TriggerAuthRequest = z.infer<typeof triggerAuthRequestSchema>;
+
+export const triggerAuthResponseSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        credential: z.string().nullable(),
+        /** The bearer was a single-use test secret, now spent: the server must not cache this verdict. */
+        oneShot: z.boolean(),
+    }),
+    z.object({ ok: z.literal(false) }),
+]);
+export type TriggerAuthResponse = z.infer<typeof triggerAuthResponseSchema>;
+
+/* The server answers a caller firing `POST /agents/:agentSlug/triggers/:name`. */
+
+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(
+            z.object({ toolCallId: z.string(), toolName: z.string(), input: z.unknown() }),
+        ),
+    }),
+    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 null. */
+        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("disabled") }),
+    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. */
+export const triggerFiringAnswerSchema = z.object({
+    toolCallId: z.string().min(1).max(256),
+    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(),
+    /** Set once a run with an output schema completed; null otherwise. */
+    output: z.unknown(),
+    createdAt: z.iso.datetime(),
+    finishedAt: z.iso.datetime().nullable(),
+});
+export type TriggerFiringRecord = z.infer<typeof triggerFiringRecordSchema>;
+
+export const triggerFiringListResponseSchema = z.object({
+    firings: z.array(triggerFiringRecordSchema),
+});
+export type TriggerFiringListResponse = z.infer<typeof triggerFiringListResponseSchema>;

package/src/contracts/wire/index.ts

@@ -0,0 +1,264 @@
+/**
+ * The wire contract — every shape that crosses the HTTP/WebSocket boundary
+ * between `@m6d/cortex-server` and the client SDKs (`@m6d/cortex-angular`,
+ * `@m6d/cortex-react`).
+ *
+ * Nothing here has a runtime dependency, and nothing here may grow one: this
+ * file is compiled into an Angular library, a React library and a Bun server
+ * alike.
+ */
+
+/** The UI locales every localized value is keyed by. */
+export const LOCALES = ["en", "ar"] as const;
+export type Locale = (typeof LOCALES)[number];
+
+/** 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];
+
+/** `trigger` rows hold a firing's rendered instructions; the model sees them as `user` turns. */
+export const MESSAGE_ROLES = ["system", "user", "assistant", "trigger"] as const;
+export type MessageRole = (typeof MESSAGE_ROLES)[number];
+
+export const ATTACHMENT_MIME_TYPES = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "application/pdf",
+] as const;
+
+export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+
+export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+
+export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
+
+/** Who put the file in the thread: the user through the composer, or a tool mid-turn. */
+export const ATTACHMENT_ORIGINS = ["upload", "tool"] as const;
+
+export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
+    if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
+    if (sizeBytes > ATTACHMENT_MAX_BYTES) return "size";
+    return "ok";
+}
+
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
+
+export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
+
+export type AttachmentSummary = {
+    id: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    status: AttachmentStatus;
+    origin: AttachmentOrigin;
+    description: string | null;
+};
+
+export type ThreadSummary = {
+    id: string;
+    title: string | null;
+    createdAt: string;
+    updatedAt: string;
+    isRunning: boolean;
+    /** Present on a headless thread a trigger owns. Widgets never list these. */
+    trigger?: { name: string };
+};
+
+/**
+ * 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
+ * present the turn as aborted and should read the settled state back instead.
+ */
+export type AbortRunResult = {
+    aborted: boolean;
+};
+
+export type TokenUsage = {
+    input: {
+        noCache: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    output: {
+        reasoning: number;
+        text: number;
+        total: number;
+    };
+    total: number;
+};
+
+/**
+ * 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.
+ */
+export type ClientToolBinding = {
+    toolId: string;
+    surface: ToolSurface;
+    embedOrigin: string;
+    /** Variables the initiate call's input reads. */
+    variables: string[];
+};
+
+/**
+ * What the server offers this agent's clients, fetched once at widget startup.
+ * The widget hides UI for anything absent; enforcement stays server-side.
+ */
+export type AgentCapabilities = {
+    attachments: boolean;
+    /** False when the agent's `message` trigger is off: the widget hides its composer. */
+    messages: boolean;
+    /** Prompt chips on the blank-chat landing per locale; clicking one sends its `prompt` as the first message. */
+    suggestions: Suggestions;
+    /** Headline of the blank-chat landing per locale; "" falls back to the widget's built-in copy. */
+    greeting: Greeting;
+};
+
+export type MessageMetadata = {
+    /** ISO time the server 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;
+};
+
+/**
+ * One landing-page chip: the widget shows `title` and sends `prompt` as the
+ * first message when clicked. The two may be the same text.
+ */
+export type Suggestion = { title: string; prompt: string };
+
+/** The runtime contract's `suggestionsSchema` and `greetingSchema` are built from these. */
+export type Suggestions = Record<Locale, Suggestion[]>;
+export type Greeting = Record<Locale, string>;
+
+/** Author-written copy the widget shows verbatim, one string per locale. */
+export type LocalizedText = Record<Locale, string>;
+
+/**
+ * What cortex stamps on a tool-call part's `metadata.cortex`: the sentence
+ * the widget asks with when the call needs the user's approval, in the
+ * author's words rather than the function's name.
+ */
+export type ToolCallMetadata = {
+    approval?: LocalizedText;
+};
+
+export type TriggerFiringSummary = {
+    name: string;
+    firingId: string;
+    firedAt: string;
+    payload: unknown;
+};
+
+/**
+ * A stored message as it is persisted and served. TanStack AI's `UIMessage`
+ * has no metadata field, so cortex owns the envelope: the SDK's parts plus the
+ * server-derived metadata the UI renders on settled messages.
+ *
+ * `TPart` stays generic so this file keeps its zero dependencies — both
+ * sides substitute the SDK's `MessagePart`.
+ */
+export type CortexMessage<TPart = unknown> = {
+    id: string;
+    /** `trigger` rows carry a firing's instructions; the UIs render them as an event, not a bubble. */
+    role: MessageRole;
+    parts: TPart[];
+    metadata?: MessageMetadata;
+};
+
+/**
+ * Key under the AG-UI request's `forwardedProps` carrying the answers to
+ * parked client tool calls on a continuation request. The server 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 duplicated the stored
+ * message.
+ */
+export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
+
+/**
+ * One answered call, applied to the stored transcript server-side: a client
+ * tool's output (`complete` / `error`), or the user's decision on a server
+ * tool that asked for approval (`approved` / `denied`, output null).
+ */
+export type ClientToolAnswer = {
+    toolCallId: string;
+    output: unknown;
+    state: "complete" | "error" | "approved" | "denied";
+};
+
+/**
+ * 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.
+ */
+export type ClientToolInitiateResult =
+    | { embed: false }
+    | {
+          embed: true;
+          embedUrl: string;
+          surface: ToolSurface;
+          embedOrigin: string;
+      };
+
+export type ThreadCreatedEvent = {
+    type: "thread:created";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadDeletedEvent = {
+    type: "thread:deleted";
+    payload: { threadId: string };
+};
+
+export type ThreadTitleUpdatedEvent = {
+    type: "thread:title-updated";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadRunStartedEvent = {
+    type: "thread:run-started";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadRunFinishedEvent = {
+    type: "thread:run-finished";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadMessagesUpdatedEvent = {
+    type: "thread:messages-updated";
+    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;
+
+/** 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";