@m6d/cortex-cli 0.22.0 → 0.24.0

package/src/contracts/server/index.ts

@@ -1,14 +1,22 @@
 import { z } from "zod";
 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,6 +156,7 @@ export const BUILT_IN_TOOL_NAMES = [
     "readReport",
     "searchRegistries",
     "searchThreadHistory",
+    SCHEDULE_WAKE_TOOL,
     REQUEST_LOCATION_TOOL,
     CONNECT_ACCOUNT_TOOL,
     TRIGGER_ANSWER_TOOL_NAME,
@@ -188,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) {
@@ -305,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>;
@@ -312,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. */
@@ -356,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>;

package/src/contracts/wire/index.ts

@@ -8,6 +8,8 @@
  * alike.
  */
 
+import type { RunReason, RunStatus } from "../runs/index";
+
 /** 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];
@@ -31,8 +33,8 @@ export function byLocale<T>(valueOf: (locale: Locale) => T) {
 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;
+/** `event` rows hold something that happened, a trigger's rendered instructions among them; the model sees them as `user` turns. */
+export const MESSAGE_ROLES = ["system", "user", "assistant", "event"] as const;
 export type MessageRole = (typeof MESSAGE_ROLES)[number];
 
 /** The fenced blocks an agent may draw in its replies instead of text. */
@@ -46,6 +48,29 @@ export const DEFAULT_MEDIA_FORMS = [
     "map",
 ] as const satisfies readonly MediaForm[];
 
+/**
+ * What an agent does with a message someone sends while a run holds its
+ * thread: refuses it, queues it as the next turn, or steers the running turn
+ * with it before its next step (one that arrives too late is queued).
+ */
+export const WHILE_BUSY = ["refuse", "queue", "steer"] as const;
+export type WhileBusy = (typeof WHILE_BUSY)[number];
+
+/**
+ * Where one message sent while a run holds its thread goes, named by its
+ * sender under `forwardedProps[MESSAGE_BUSY_KEY]`, or set on a waiting one
+ * by `PATCH /threads/:threadId/inputs/:inputId` (`{ busy }`): `steer` joins
+ * the running turn, `queue` waits for a turn of its own.
+ */
+export const MESSAGE_BUSY = ["queue", "steer"] as const;
+export type MessageBusy = (typeof MESSAGE_BUSY)[number];
+export const MESSAGE_BUSY_KEY = "busy";
+
+/** What a message sent while a run holds the thread does: its sender's pick, never past an agent that refuses. */
+export function busyFor(whileBusy: WhileBusy, picked: MessageBusy | undefined) {
+    return whileBusy === "refuse" ? whileBusy : (picked ?? whileBusy);
+}
+
 export const ATTACHMENT_MIME_TYPES = [
     "image/png",
     "image/jpeg",
@@ -221,6 +246,8 @@ export type AgentCapabilities = {
     messages: boolean;
     /** True when the caller only reads, as an operator inspecting a user's thread does. */
     readOnly: boolean;
+    /** What a message sent while a run holds the thread does; under `refuse`, nothing sends until the run ends. */
+    whileBusy: WhileBusy;
     /** 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. */
@@ -240,8 +267,8 @@ export type MessageMetadata = {
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
-    /** Set on `trigger` messages: the firing that wrote them. */
-    trigger?: TriggerFiringSummary;
+    /** Set on `event` messages: what happened, and the input that brought it. */
+    event?: EventSummary;
 };
 
 /**
@@ -280,6 +307,22 @@ export const STATEMENT_TOOLS = ["executeCode", "queryDataset", "describeDataset"
  */
 export const APPROVAL_TITLE_FIELD = "approvalTitle";
 
+/**
+ * The chat's own tool by which an agent hands a task to a copy of itself.
+ * Its input's `brief` is the task, which the copy's card shows.
+ */
+export const DELEGATE_TASK_TOOL = "delegateTask";
+
+/** The chat's tool by which an agent stops a copy it handed a task, by the subagent id its start answered. */
+export const CANCEL_TASK_TOOL = "cancelTask";
+
+/**
+ * The chat's tool by which an agent schedules a check-back: it comes back
+ * to the thread on its own at a time it picks, with a note to itself. Its
+ * output's `checkBackId` is the input the user may cancel.
+ */
+export const SCHEDULE_WAKE_TOOL = "scheduleWake";
+
 /** 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;
@@ -306,6 +349,23 @@ export type ToolCallMetadata = {
     embed?: ClientToolBinding;
     /** Set beside `answeredBy` on a `connectAccount` call: the widget starts the sign-in with it. */
     connect?: ConnectAccountBinding;
+    /**
+     * Set on a call a run paused on for the user's decision: the interrupt the run raised for
+     * it and the run it paused, so a client that reloads re-prompts the decision exactly as the
+     * live run asked it.
+     */
+    paused?: { runId: string; interrupt: RunInterrupt };
+};
+
+/** An interrupt as a paused run raises it on its end, in AG-UI's shape. */
+export type RunInterrupt = {
+    id: string;
+    reason: string;
+    message?: string;
+    toolCallId?: string;
+    responseSchema?: Record<string, unknown>;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
 };
 
 /** The `metadata.cortex` a tool call carries, when Cortex stamped one. */
@@ -314,11 +374,16 @@ export function toolCallMetadataOf(part: { metadata?: unknown }) {
     return metadata?.cortex ?? undefined;
 }
 
-export type TriggerFiringSummary = {
+/** An event that entered a conversation: a trigger fired, a schedule came due, a run finished. */
+export type EventSummary = {
+    source: "trigger" | "schedule" | "run";
+    /** The trigger's name, or what the schedule or run was for. */
     name: string;
-    firingId: string;
-    firedAt: string;
+    inputId: string;
+    at: string;
     payload: unknown;
+    /** What a trigger that leaves a note tells the thread, for its user to read. */
+    note?: string;
 };
 
 /**
@@ -332,19 +397,19 @@ export type TriggerFiringSummary = {
  */
 export type CortexMessage<TPart = unknown> = {
     id: string;
-    /** `trigger` rows carry a firing's instructions; the UIs render them as an event, not a bubble. */
+    /** `event` rows carry what happened; the UIs render them as an event, not a bubble. */
     role: MessageRole;
     parts: TPart[];
     metadata?: MessageMetadata;
 };
 
 /**
- * A stored message as the SDK's chat client takes it. The SDK has no `trigger`
- * role, so a firing's message travels as a user turn; its true role stays on
- * the envelope (`metadata.trigger`), which is what the UIs render the event from.
+ * A stored message as the SDK's chat client takes it. The SDK has no `event`
+ * role, so an event message travels as a user turn; its true role stays on
+ * the envelope (`metadata.event`), which is what the UIs render the event from.
  */
 export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
-    return { ...message, role: message.role === "trigger" ? ("user" as const) : message.role };
+    return { ...message, role: message.role === "event" ? ("user" as const) : message.role };
 }
 
 /**
@@ -427,14 +492,20 @@ export type ThreadRunStartedEvent = {
 
 /**
  * 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.
+ * a new message now; whatever turn it committed is in the transcript.
+ * `status` and `reason` say how: `waiting` for a run parked on calls that
+ * wait. 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; runId: string };
+    payload: {
+        thread: ThreadSummary;
+        runId: string;
+        status: RunStatus;
+        reason: RunReason | null;
+    };
 };
 
 export type ThreadMessagesUpdatedEvent = {
@@ -442,13 +513,26 @@ export type ThreadMessagesUpdatedEvent = {
     payload: { thread: ThreadSummary };
 };
 
+/**
+ * The inputs waiting on the thread changed: one was offered, taken up as a
+ * turn of its own, or cancelled. `inputIds` are the ones still waiting, in
+ * the order dispatch takes them; `GET /threads/:threadId/inputs` reads
+ * them. A steer the running turn took in waits on until that turn stores
+ * it, which announces nothing: the run's stream carries it.
+ */
+export type ThreadInputsChangedEvent = {
+    type: "thread:inputs-changed";
+    payload: { threadId: string; inputIds: string[] };
+};
+
 export type WsEvent =
     | ThreadCreatedEvent
     | ThreadDeletedEvent
     | ThreadTitleUpdatedEvent
     | ThreadRunStartedEvent
     | ThreadRunFinishedEvent
-    | ThreadMessagesUpdatedEvent;
+    | ThreadMessagesUpdatedEvent
+    | ThreadInputsChangedEvent;
 
 /** 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";
@@ -473,53 +557,33 @@ export const OPERATOR_HEADER = "X-Cortex-Operator";
 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`.
+ * One input waiting on a thread, in the order dispatch takes them, in
+ * `GET /threads/:threadId/inputs`: the user message as it will be stored
+ * once a run takes it up, and how it waits: to steer the running turn, or
+ * for a turn of its own. `DELETE /threads/:threadId/inputs/:inputId`
+ * cancels it and `PATCH` (`{ busy }`) moves it to steer or queue, unless a
+ * run already took it in (404).
  */
-export type ChatDropped = {
-    outcome: "dropped";
-    reason: Exclude<TriggerDropReason, "budget"> | "no_turn";
+export type WaitingInput<TPart = unknown> = {
+    inputId: string;
+    delivery: "prompt" | "steer" | "followUp" | "answer" | "note";
+    message: CortexMessage<TPart>;
+    /** Whether it is text alone, which a running turn may take in as a steer; one with files waits for a turn of its own. */
+    textOnly: boolean;
 };
 
 /**
- * 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.
+ * The refusal 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
+ * refusal shows as a failed turn.
  */
-export type SendRefusal = Extract<ChatDropped["reason"], "approval_pending">;
+export type SendRefusal = "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
+ * nothing. `refused` (4xx, an `InputReceipt` 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.