@m6d/cortex-cli 0.21.0 → 0.23.0

package/src/contracts/server/index.ts

@@ -1,14 +1,22 @@
 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 { runRecordSchema, runWaitSchema } from "../runs/index";
+import { TRIGGER_ANSWER_TOOL_NAME } from "../triggers/index";
 import { isRecord, readJsonPointer } from "../json/index";
-import { APPROVAL_TITLE_FIELD, LOCALES } from "../wire/index";
+import {
+    APPROVAL_TITLE_FIELD,
+    CANCEL_TASK_TOOL,
+    DELEGATE_TASK_TOOL,
+    LOCALES,
+    SCHEDULE_WAKE_TOOL,
+} from "../wire/index";
 
 /*
  * The server protocol: what Cortex calls on a customer's backend. `GET /`
  * answers the manifest (the variables it fills, the native tools it runs,
- * whether it verifies end-user tokens, the events it hears); the other
+ * whether it verifies end-user tokens, whether Cortex may act for a user
+ * whose token is gone, the events it hears); the other
  * routes are the calls behind them. Every request carries the server key as
  * its bearer, and a run-scoped one also the run's token in
  * `END_USER_TOKEN_HEADER` when the run has one. A refusal on any route
@@ -121,6 +129,14 @@ export const BUILT_IN_VARIABLES = [
         type: "string",
         computed: true,
     },
+    {
+        name: "threadId",
+        description:
+            "The thread's id: a backend that keeps it fires a trigger back into the thread",
+        example: "3d206d66-4b28-4608-904c-3e8599e63a7b",
+        type: "string",
+        computed: true,
+    },
 ] as const satisfies ReadonlyArray<VariableDeclaration>;
 
 /**
@@ -129,6 +145,8 @@ export const BUILT_IN_VARIABLES = [
  * carries them to the .NET SDK.
  */
 export const BUILT_IN_TOOL_NAMES = [
+    CANCEL_TASK_TOOL,
+    DELEGATE_TASK_TOOL,
     "describeDataset",
     "executeCode",
     "fetchImage",
@@ -138,7 +156,9 @@ export const BUILT_IN_TOOL_NAMES = [
     "readReport",
     "searchRegistries",
     "searchThreadHistory",
+    SCHEDULE_WAKE_TOOL,
     REQUEST_LOCATION_TOOL,
+    CONNECT_ACCOUNT_TOOL,
     TRIGGER_ANSWER_TOOL_NAME,
 ] as const;
 
@@ -187,33 +207,58 @@ export const serverToolSchema = z.object({
 });
 export type ServerTool = z.infer<typeof serverToolSchema>;
 
-/** The events a server hears at `POST /events/:event`, and a webhook delivers. */
-export const SERVER_EVENTS = ["approval_requested"] as const;
+/**
+ * The events a server hears at `POST /events/:event`, and a webhook
+ * delivers: a run that waits on a decision, and a run a trigger started
+ * that ended. A chat's runs end in their widget, which follows them.
+ */
+export const SERVER_EVENTS = ["run_waiting", "run_finished"] as const;
+export type ServerEventName = (typeof SERVER_EVENTS)[number];
 
 /** The header a webhook delivery names its event in, so a receiver tells events apart without parsing the body. */
 export const EVENT_HEADER = "X-Cortex-Event";
 
-/**
- * A run parked on server tools that need the end user's approval, as every
- * receiver hears of it: a webhook's body and the agent's server's event are
- * this one object. `firingId` and `triggerName` are set when a trigger
- * started the run, which is what a receiver answering through the firing
- * route needs. Every parked call is named; one whose input would carry the
- * event past `SERVER_REQUEST_MAX_BYTES` comes without its input.
- */
-export const approvalRequestedEventSchema = z.object({
-    event: z.literal("approval_requested"),
+/** What every event names: the agent it happened on, the run, the trigger that started that run if one did, and when. */
+const runEventFields = {
     agentName: nameSchema,
     agentId: z.uuid(),
-    threadId: z.string(),
-    runId: z.string(),
-    userId: z.string(),
-    firingId: z.uuid().optional(),
+    runId: z.uuid(),
     triggerName: z.string().optional(),
-    approvals: z.array(pendingApprovalSchema.partial({ input: true })),
     occurredAt: z.iso.datetime(),
+};
+
+/**
+ * A run parked on calls that wait for a decision, as every receiver hears
+ * of it: a webhook's body and the agent's server's event are this one
+ * object. `runId` names the run a receiver decides through
+ * `POST /agents/:agentName/runs/:id/answer`. Every call it waits on is
+ * named, a client tool's among them; one whose input would carry the event
+ * past `SERVER_REQUEST_MAX_BYTES` comes without its input. A run waiting
+ * only on its widget's calls is not announced.
+ */
+export const runWaitingEventSchema = z.object({
+    event: z.literal("run_waiting"),
+    ...runEventFields,
+    threadId: z.string(),
+    userId: z.string(),
+    waits: z.array(runWaitSchema.partial({ input: true })),
+});
+export type RunWaitingEvent = z.infer<typeof runWaitingEventSchema>;
+
+/** A run a trigger started that ended, with its record: how it ended and what it answered with. */
+export const runFinishedEventSchema = z.object({
+    event: z.literal("run_finished"),
+    ...runEventFields,
+    run: runRecordSchema,
 });
-export type ApprovalRequestedEvent = z.infer<typeof approvalRequestedEventSchema>;
+export type RunFinishedEvent = z.infer<typeof runFinishedEventSchema>;
+
+/** Any event a receiver hears, told apart by `event`: `POST /events/:event` names it too. */
+export const serverEventSchema = z.discriminatedUnion("event", [
+    runWaitingEventSchema,
+    runFinishedEventSchema,
+]);
+export type ServerEvent = z.infer<typeof serverEventSchema>;
 
 /** 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) {
@@ -304,6 +349,13 @@ export const serverManifestSchema = z.object({
             tools.forEach((tool, index) => refuseBlockedApprovalTitle(tool, context, [index]));
         }),
     verify: z.boolean(),
+    /**
+     * Whether Cortex may act for a user whose token is gone, naming them in
+     * the body with `user.delegated`. Without it, such a run names no user
+     * to the server (`user: null`, as on a trigger's run), so it never acts
+     * for someone who is not there.
+     */
+    delegation: z.boolean(),
     events: z.array(z.enum(SERVER_EVENTS)),
 });
 export type ServerManifest = z.infer<typeof serverManifestSchema>;
@@ -311,9 +363,34 @@ export type ServerManifest = z.infer<typeof serverManifestSchema>;
 /** The agent a call is for. */
 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. */
+/**
+ * Why Cortex acts for a user with no valid token of theirs: their message
+ * waited past its token (`queued`), or a run (`run`), a schedule (`schedule`)
+ * or a trigger (`trigger`) started the work.
+ */
+export const DELEGATION_REASONS = ["queued", "run", "schedule", "trigger"] as const;
+
+/** Cortex acting for a user who is not there: why, and the run that acts. */
+export const delegationSchema = z.object({
+    reason: z.enum(DELEGATION_REASONS),
+    runId: z.uuid(),
+});
+export type Delegation = z.infer<typeof delegationSchema>;
+
+/**
+ * The end user a run acts for, as their token was verified; null for a
+ * trigger's run, and for a run acting for a user who is not there toward a
+ * server whose manifest does not set `delegation`. `delegated` when the run acts for them without their
+ * token, told only to a server whose manifest sets `delegation`, which
+ * then trusts the body's user as it trusts the key: a tool reads it to
+ * refuse what a user who is not there should not do.
+ */
 const serverUserSchema = z
-    .object({ id: userIdSchema, claims: z.record(z.string(), z.unknown()) })
+    .object({
+        id: userIdSchema,
+        claims: z.record(z.string(), z.unknown()),
+        delegated: delegationSchema.optional(),
+    })
     .nullable();
 
 /** `POST /variables`: the values one thread runs with, asked once per thread. */
@@ -355,8 +432,3 @@ export const verifyResponseSchema = z.union([
     z.object({ sub: z.null() }),
 ]);
 export type VerifyResponse = z.infer<typeof verifyResponseSchema>;
-
-/** `POST /events/:event`: the body of each event a manifest subscribes to. */
-export const serverEventSchemas = {
-    approval_requested: approvalRequestedEventSchema,
-} as const satisfies Record<(typeof SERVER_EVENTS)[number], z.ZodType>;

package/src/contracts/triggers/index.ts

@@ -1,116 +1,59 @@
 import { z } from "zod";
 
-import { TRIGGER_DROP_REASONS, TRIGGER_REASONS } from "../wire/index";
+import { inputReceiptSchema, runRecordSchema } from "../runs/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
+ * Triggers: named entry points on an agent. A caller fires one over
  * `POST /agents/:agentName/triggers/:name` with the trigger's secret as its
- * bearer. These are the shapes Cortex answers that caller with.
+ * bearer; the fire is an input on the thread the trigger's policy names,
+ * and the run that takes it is read and decided under `/runs/:id`. 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];
-
-/** The engine route of agent `agentName`, which the widget chats with and its triggers sit under. */
+/** The engine route of agent `agentName`, which the widget chats with and its triggers and runs sit under. */
 export function agentRoute(agentName: string) {
     return `/agents/${encodeURIComponent(agentName)}`;
 }
 
-/** The engine route a trigger is fired at on agent `agentName`; its firings are read and answered under it. */
+/** The engine route a trigger is fired at on agent `agentName`; its runs are listed 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. */
-export const pendingApprovalSchema = z.object({
-    toolCallId: z.string(),
-    toolName: z.string(),
-    input: z.unknown(),
+/** The engine route a run of agent `agentName` is read at, and answered and cancelled under. */
+export function runRoute(agentName: string, runId: string) {
+    return `${agentRoute(agentName)}/runs/${encodeURIComponent(runId)}`;
+}
+
+/** What a fire answers once its run started: its input, run and thread; `GET .../runs/:id` reads the run. */
+export const fireStartedSchema = z.object({
+    inputId: z.uuid(),
+    state: z.literal("started"),
+    runId: z.uuid(),
+    threadId: z.uuid(),
 });
 
-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.enum(TRIGGER_REASONS).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>;
+/** A fire whose payload the trigger refused, each issue at its path. */
+export const fireRejectedSchema = z.object({
+    state: z.literal("rejected"),
+    issues: z.array(z.object({ path: z.string(), message: z.string() })),
+});
 
 /**
- * `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.
+ * What `POST /agents/:agentName/triggers/:name` answers as JSON: the run it
+ * started (`started`, 202); with `?wait=`, that run once it ended (a
+ * `RunRecord`, 200) or parked on a decision (202); the fire's input while it
+ * waits on the thread, once refused, or once cancelled before any run took
+ * it (an `InputReceipt`: 202, or 409, and 429 for a spent budget or
+ * bucket); or a payload the trigger refused (422).
  */
-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/:agentName/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.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. */
-    approvals: z.array(pendingApprovalSchema),
-    createdAt: z.iso.datetime(),
-    finishedAt: z.iso.datetime().nullable(),
-});
-export type TriggerFiringRecord = z.infer<typeof triggerFiringRecordSchema>;
+export const fireAnswerSchema = z.union([
+    fireStartedSchema,
+    fireRejectedSchema,
+    inputReceiptSchema,
+    runRecordSchema,
+]);
+export type FireAnswer = z.infer<typeof fireAnswerSchema>;