@m6d/cortex-cli 0.21.0 → 0.23.0

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",
@@ -164,6 +189,47 @@ export type ClientToolBinding = {
     embedOrigin: string;
 };
 
+/**
+ * How the widget connects an end user's account for a `connectAccount`
+ * call, stamped on the call: where the engine starts a sign-in, at the URL
+ * browsers reach it, the agent it is for, and each server the call may
+ * name, by name: its display name, and the scope it still needs when the
+ * account is connected but lacks access.
+ */
+export type ConnectAccountBinding = {
+    startUrl: string;
+    agent: string;
+    servers: Record<string, { displayName: Partial<LocalizedText>; scope?: string }>;
+};
+
+/**
+ * Response of `GET /connections/:server?call=<toolCallId>`: where the
+ * caller's own account stands with the agent's MCP server of that name, for
+ * the card of that `connectAccount` call. `connected` with all a sign-in
+ * may ask for; `pending` while it is not connected, or lacks access a
+ * sign-in may still grant; `refused` once the card's own sign-in came back
+ * without it, or no sign-in may ask again.
+ */
+export type AccountConnection = {
+    status: "connected" | "pending" | "refused";
+};
+
+/**
+ * The form `POST /oauth/start` takes, posted into the window a sign-in runs
+ * in with its bearer in the body, so no link can start one: the console's
+ * operator token and the server's id for the shared connection.
+ */
+export type SharedSignInStart = { operatorToken: string; mcpServerId: string };
+
+/** An end user's own start: their token, their agent, the server's name, and the `connectAccount` call it answers. */
+export type EndUserSignInStart = {
+    token: string;
+    agent: string;
+    server: string;
+    threadId: string;
+    toolCallId: string;
+};
+
 /**
  * What Cortex offers this agent's clients, fetched once at widget startup.
  * The widget hides UI for anything absent; Cortex enforces each.
@@ -180,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. */
@@ -199,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;
 };
 
 /**
@@ -239,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;
@@ -263,6 +347,25 @@ export type ToolCallMetadata = {
     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;
+    /** 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. */
@@ -271,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;
 };
 
 /**
@@ -289,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 };
 }
 
 /**
@@ -384,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 = {
@@ -399,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";
@@ -430,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.

package/src/management/flags.ts

@@ -10,6 +10,8 @@ export type Flag = {
     description: string;
     /** A secret: never an argv flag (argv is world-readable), prompted masked or read from stdin. */
     sensitive: boolean;
+    /** Takes `null`, which a blank prompted answer sends. */
+    nullable: boolean;
 };
 
 /** Follows a local `$ref` into `components/schemas`; anything else is returned as is. */
@@ -36,6 +38,12 @@ function isSensitive(property: JsonSchema, document: OpenApiDocument): boolean {
     );
 }
 
+/** Whether `null` is allowed, as a type list or as zod's `anyOf` alternative for a nullable property. */
+function isNullable(property: JsonSchema) {
+    if (Array.isArray(property.type)) return property.type.includes("null");
+    return (property.anyOf ?? []).some((alternative) => alternative.type === "null");
+}
+
 /** The flag kind a property's schema maps to; scalars and scalar arrays get typed flags, the rest is JSON. */
 function kindOf(property: JsonSchema, document: OpenApiDocument) {
     if (property.enum) return "enum" as const;
@@ -71,19 +79,21 @@ export function flagsFor(input: JsonSchema, document: OpenApiDocument) {
             choices: property.enum?.map(String),
             description: property.description ?? "",
             sensitive: isSensitive(property, document),
+            nullable: isNullable(property),
         } satisfies Flag;
     });
 }
 
 /**
  * A prompted answer, parsed and checked exactly as the flag's option would
- * be; `undefined` when it does not fit, so the caller can ask again.
+ * be; `undefined` when it does not fit, so the caller can ask again. A blank
+ * answer is `null` for a nullable flag.
  */
 export function parseAnswer(flag: Flag, answer: string) {
-    // A string is taken verbatim: a secret's whitespace is part of it. Every
-    // other kind is lexical and trimmed before parsing.
+    // A secret's whitespace is part of it; any other answer of only spaces is blank.
+    if ((flag.sensitive ? answer : answer.trim()) === "") return flag.nullable ? null : undefined;
+    // A string is taken verbatim. Every other kind is lexical and trimmed before parsing.
     const text = flag.kind === "string" ? answer : answer.trim();
-    if (text === "") return undefined;
     return ANSWER_PARSERS[flag.kind](text, flag);
 }
 

package/src/scaffold/files.ts

@@ -28,7 +28,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.20.0";
+const CORTEX_VERSION = "0.22.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -147,7 +147,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.8.0",
+                "@m6d/cortex": "~0.10.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",
@@ -246,6 +246,9 @@ COMPOSE_PROJECT_NAME=
 DEFAULT_ADMIN_EMAIL=admin@example.com
 DEFAULT_ADMIN_PASSWORD=
 BOOTSTRAP_MANAGEMENT_KEY=
+# The Cortex license key you were given. Without one Cortex serves no console
+# and runs no agent.
+CORTEX_LICENSE_KEY=
 # Session signing, the key the secrets store is encrypted with, and object
 # storage's password (storage is published on this machine for uploads).
 BETTER_AUTH_SECRET=
@@ -497,7 +500,9 @@ A backend for Cortex agents, and Cortex itself to run them on.
 
 ## Getting started
 
-On a fresh clone, run \`bun install\` first (\`cortex new\` already did): it writes \`.env\`.
+On a fresh clone, run \`bun install\` first (\`cortex new\` already did): it writes \`.env\`. Put
+your Cortex license key in its \`CORTEX_LICENSE_KEY\`: without one Cortex serves no console and runs no
+agent.
 
 \`\`\`sh
 bun run dev

package/src/ui/prompts.ts

@@ -84,40 +84,34 @@ export async function askToProceed(message: string) {
 }
 
 /**
- * A required value a command was not given: asked by name, re-asked while
- * empty or while `check` returns a complaint about the trimmed value.
+ * How an asked value is checked: re-asked while `check` complains about it,
+ * and while empty unless `blank` accepts an empty answer.
  */
-export function askValue(
-    name: string,
-    hint?: string,
-    check: (value: string) => string | undefined = () => undefined,
-) {
+type AskOptions = { check?: (value: string) => string | undefined; blank?: boolean };
+
+function validator(name: string, { check = () => undefined, blank = false }: AskOptions) {
+    return function (value: string | undefined) {
+        if (value) return check(value);
+        return blank ? undefined : `${name} is required.`;
+    };
+}
+
+/** A value a command was not given: asked by name and checked trimmed. */
+export function askValue(name: string, { hint, ...options }: AskOptions & { hint?: string } = {}) {
+    const validate = validator(name, options);
     return orExit(
         text({
             message: name,
             placeholder: hint,
             output,
-            validate: function (value) {
-                const candidate = (value ?? "").trim();
-                return candidate.length === 0 ? `${name} is required.` : check(candidate);
-            },
+            validate: (value) => validate(value?.trim()),
         }),
     );
 }
 
-/** A credential: typed masked, never echoed, and re-asked while `check` complains. */
-export function askSecret(
-    name: string,
-    check: (value: string) => string | undefined = () => undefined,
-) {
-    return orExit(
-        password({
-            message: name,
-            output,
-            validate: (value) =>
-                (value ?? "").length === 0 ? `${name} is required.` : check(value ?? ""),
-        }),
-    );
+/** A credential: typed masked, never echoed, and checked as typed. */
+export function askSecret(name: string, options: AskOptions = {}) {
+    return orExit(password({ message: name, output, validate: validator(name, options) }));
 }
 
 type Step = { title: string; run: () => string | undefined | Promise<string | undefined> };