@m6d/cortex-cli 0.21.0 → 0.23.0

package/src/contracts/manifest/index.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { datasetIdentifierSchema } from "../datasets/index";
 import { canCarrySecret } from "../egress-policy/index";
+import { triggerScheduleSchema } from "../schedule/index";
 import {
     displayNameSchema,
     EVENT_HEADER,
@@ -11,13 +12,13 @@ import {
     refuseBlockedApprovalTitle,
     serverToolSchema,
 } from "../server/index";
-import { MESSAGE_TRIGGER_NAME } from "../triggers/index";
 import {
     BASE_LOCALE,
     byLocale,
     DEFAULT_MEDIA_FORMS,
     MEDIA_FORMS,
     TOOL_SURFACES,
+    WHILE_BUSY,
     type Greeting,
     type Suggestions,
 } from "../wire/index";
@@ -502,7 +503,7 @@ export function headerListSchema<TEntry extends z.ZodType<{ header: string }>>(
         });
 }
 
-/** A variable by name: one the agent's server declares, or a built-in (`timezone`, `locale`, `utcTime`). */
+/** A variable by name: one the agent's server declares, or a built-in (`timezone`, `locale`, `utcTime`, `threadId`). */
 const variableSourceSchema = z.object({
     kind: z.literal("variable"),
     name: z.string().trim().min(1).max(64),
@@ -522,7 +523,7 @@ const constantHeaderSourceSchema = z.object({
 
 /**
  * Where a header's value comes from: a credential, the run's own token (the
- * end user's in a chat, the trigger's in a firing), a variable, or a
+ * end user's in a chat, the trigger's in a trigger run), a variable, or a
  * constant. A run token or a variable needs a run; a call without one (a
  * webhook delivery, a catalog read) presents only credentials and constants.
  */
@@ -1070,63 +1071,134 @@ const manifestSkillSchema = z.strictObject({
 export type ManifestSkill = z.input<typeof manifestSkillSchema>;
 
 /**
- * Which thread a firing lands in. `single`: one thread for the trigger.
- * `per-firing`: a fresh thread every time. `ephemeral`: a fresh thread that
+ * Which thread a fire lands in. `single`: one thread for the trigger.
+ * `per-input`: 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
+ * the caller as the run'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`).
+ * `/pull_request/number`). `thread`: the existing thread of the agent's whose
+ * id is at the pointer, a user's among them, such as one a tool passed its
+ * backend. Its run acts as the thread's user without their token, which
+ * only a server that allows delegation hears; the trigger's credential is
+ * never presented. Its runs offer no tool that needs approval: nobody
+ * decides the trigger's calls in a user's chat. With `wake: false` no run
+ * starts: the fire leaves its instructions in the thread as a note, its
+ * payload references filled, in its turn behind any run there.
  */
 export const triggerThreadPolicySchema = z.discriminatedUnion("policy", [
     z.object({ policy: z.literal("single") }),
-    z.object({ policy: z.literal("per-firing") }),
+    z.object({ policy: z.literal("per-input") }),
     z.object({ policy: z.literal("ephemeral") }),
     z.object({ policy: z.literal("keyed"), key: jsonPointerSchema }),
+    z.object({
+        policy: z.literal("thread"),
+        key: jsonPointerSchema,
+        wake: z.boolean(),
+    }),
 ]);
 export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
 
+/** Whether a policy reads its thread from the payload, which a fire with none cannot do. */
+export function threadFromPayload(policy: TriggerThreadPolicy) {
+    return policy.policy === "keyed" || policy.policy === "thread";
+}
+
+/**
+ * What a trigger with a schedule may not have, by the part it sits in: it
+ * fires with no payload and no caller, so it takes no input fields, no fire
+ * credential and no thread read from a payload. Each caller words the
+ * issues itself. None for one without.
+ */
+export function scheduledTriggerIssues(trigger: {
+    scheduled: boolean;
+    inputFields: number;
+    fireCredential: boolean;
+    threadPolicy: TriggerThreadPolicy;
+}) {
+    if (!trigger.scheduled) return [];
+    return [
+        trigger.inputFields > 0 && ("input" as const),
+        trigger.fireCredential && ("fireCredential" as const),
+        threadFromPayload(trigger.threadPolicy) && ("threadPolicy" as const),
+    ].filter((issue) => issue !== false);
+}
+
 /** A trigger's description and instructions in characters. The console caps its editor at the same. */
 export const TRIGGER_LIMITS = { descriptionLength: 500, instructionsLength: 20_000 } as const;
 
-/** Fired with its secret, which the apply that creates it answers once and no manifest holds. */
-const manifestTriggerSchema = z.strictObject({
-    /** `message` is the built-in trigger every agent has. */
-    name: nameSchema.refine((name) => name !== MESSAGE_TRIGGER_NAME, "the built-in trigger's name"),
-    displayName: displayNameSchema.default({}),
-    description: z.string().trim().min(1).max(TRIGGER_LIMITS.descriptionLength),
-    inputSchema: objectSchema.default(EMPTY_OBJECT),
-    /** The shape the run answers in; absent, the run answers in free text. */
-    outputSchema: objectSchema
-        .refine(
-            (schema) => Object.keys(schema.properties ?? {}).length > 0,
-            "declares a property; leave it out for a free-text answer",
-        )
-        .optional(),
-    /** Rich text: it may mention tools, skills and datasets, and read `{{variables}}` and `{{/payload/pointer}}`s. */
-    instructions: z.string().trim().min(1).max(TRIGGER_LIMITS.instructionsLength),
-    threadPolicy: triggerThreadPolicySchema.default({ policy: "single" }),
-    /** Firings a day per agent; absent, no limit. */
-    budgetPerDay: z.number().int().positive().optional(),
-    /** Consecutive failed or rejected firings before the trigger disables itself; it stays off until an operator enables it. */
-    disableAfterFailures: setting(SETTING_BOUNDS.trigger.disableAfterFailures),
-    /** The credential the run acts with, presented wherever the end user's token would go. */
-    credential: nameSchema.optional(),
-    /** A static credential whose value callers fire with, in place of a minted secret. */
-    fireCredential: nameSchema.optional(),
-    /** The model its runs talk to, over each agent's. */
-    model: modelSchema.optional(),
-    audience: audienceSchema,
-    overridable: overridable([
-        "displayName",
-        "description",
-        "instructions",
-        "threadPolicy",
-        "budgetPerDay",
-        "disableAfterFailures",
-        "model",
-    ]),
-});
+/**
+ * Fired with its secret, which the apply that creates it answers once and no
+ * manifest holds; or, with a `schedule`, by Cortex itself on its cron, with
+ * no payload and no caller, so it takes no input fields, no fire credential
+ * and no thread read from a payload. Whether it has a schedule is fixed once it
+ * exists.
+ */
+const manifestTriggerSchema = z
+    .strictObject({
+        name: nameSchema,
+        displayName: displayNameSchema.default({}),
+        description: z.string().trim().min(1).max(TRIGGER_LIMITS.descriptionLength),
+        inputSchema: objectSchema.default(EMPTY_OBJECT),
+        /** The shape the run answers in; absent, the run answers in free text. */
+        outputSchema: objectSchema
+            .refine(
+                (schema) => Object.keys(schema.properties ?? {}).length > 0,
+                "declares a property; leave it out for a free-text answer",
+            )
+            .optional(),
+        /** Rich text: it may mention tools, skills and datasets, and read `{{variables}}` and `{{/payload/pointer}}`s. */
+        instructions: z.string().trim().min(1).max(TRIGGER_LIMITS.instructionsLength),
+        threadPolicy: triggerThreadPolicySchema.default({ policy: "single" }),
+        /** A fire that finds its thread busy: queued as the next turn (the default), steering a running turn of this trigger's, or refused. */
+        whileBusy: z.enum(WHILE_BUSY).default("queue"),
+        /** Fires a day per agent; absent, no limit. */
+        budgetPerDay: z.number().int().positive().optional(),
+        /** Consecutive failed runs or rejected fires before the trigger disables itself; it stays off until an operator enables it. */
+        disableAfterFailures: setting(SETTING_BOUNDS.trigger.disableAfterFailures),
+        /** The credential the run acts with, presented wherever the end user's token would go. */
+        credential: nameSchema.optional(),
+        /** A static credential whose value callers fire with, in place of a minted secret. */
+        fireCredential: nameSchema.optional(),
+        /** The model its runs talk to, over each agent's. */
+        model: modelSchema.optional(),
+        /** When Cortex fires it itself; absent, it fires when a caller calls it. */
+        schedule: triggerScheduleSchema.optional(),
+        audience: audienceSchema,
+        overridable: overridable([
+            "displayName",
+            "description",
+            "instructions",
+            "threadPolicy",
+            "whileBusy",
+            "budgetPerDay",
+            "disableAfterFailures",
+            "model",
+            "schedule",
+        ]),
+    })
+    .superRefine((trigger, context) => {
+        const issues = {
+            input: [
+                "inputSchema",
+                "a scheduled trigger fires with no payload, so it takes no input fields",
+            ],
+            fireCredential: ["fireCredential", "a scheduled trigger has no caller to fire it"],
+            threadPolicy: [
+                "threadPolicy",
+                "a scheduled trigger has no payload to read its thread from",
+            ],
+        } as const;
+        for (const issue of scheduledTriggerIssues({
+            scheduled: trigger.schedule !== undefined,
+            inputFields: Object.keys(trigger.inputSchema.properties ?? {}).length,
+            fireCredential: trigger.fireCredential !== undefined,
+            threadPolicy: trigger.threadPolicy,
+        })) {
+            const [path, message] = issues[issue];
+            context.addIssue({ code: "custom", path: [path], message });
+        }
+    });
 export type ManifestTrigger = z.input<typeof manifestTriggerSchema>;
 
 /** The datasets `pinned` lists that `expose` does not: a host pins only what it exposes. */
@@ -1196,24 +1268,68 @@ export const mcpToolNamesSchema = z
     )
     .max(200);
 
-const manifestMcpServerSchema = z.strictObject({
-    /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
-    name: identifierSchema,
-    displayName: displayNameSchema.default({}),
-    url: upstreamUrlSchema,
-    headers: declaredHeadersSchema(
-        presentedHeaderSchema.refine(
-            (name) => !mcpTransportHeaders.has(name.toLowerCase()),
-            "a header the MCP transport sets",
-        ),
-        headerSourceSchema,
-    ),
-    /** The server's own tool names to offer; empty offers every tool. */
-    include: mcpToolNamesSchema.default([]),
-    exclude: mcpToolNamesSchema.default([]),
-    audience: audienceSchema,
-    overridable: overridable(["displayName", "include", "exclude", "headers"]),
+/** Who holds an MCP server's sign-in: one connection an operator makes for every agent, or one per end user of each agent. */
+export const MCP_CONNECTION_OWNERS = ["shared", "endUser"] as const;
+
+/**
+ * How Cortex signs in to an MCP server that takes OAuth: who connects, the
+ * scope it asks for (absent, what the server advertises), and, for an
+ * authorization server that takes neither a client ID document nor dynamic
+ * registration, the credential holding the app registered there beforehand:
+ * an OAuth2 client credentials one naming that server as its issuer.
+ */
+export const mcpSignInSchema = z.strictObject({
+    connects: z.enum(MCP_CONNECTION_OWNERS),
+    scope: z.string().trim().min(1).max(1_000).optional(),
+    credential: nameSchema.optional(),
 });
+export type McpSignIn = z.infer<typeof mcpSignInSchema>;
+
+/**
+ * The index of the Authorization header a server that signs in declares
+ * beside its sign-in, whose token travels under that header; -1 when it
+ * signs in without one, or declares one without signing in.
+ */
+export function authorizationBesideSignIn(server: {
+    signIn?: McpSignIn | null;
+    headers: ReadonlyArray<{ header: string }>;
+}) {
+    return server.signIn
+        ? server.headers.findIndex((entry) => entry.header.toLowerCase() === "authorization")
+        : -1;
+}
+
+const manifestMcpServerSchema = z
+    .strictObject({
+        /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
+        name: identifierSchema,
+        displayName: displayNameSchema.default({}),
+        url: upstreamUrlSchema,
+        headers: declaredHeadersSchema(
+            presentedHeaderSchema.refine(
+                (name) => !mcpTransportHeaders.has(name.toLowerCase()),
+                "a header the MCP transport sets",
+            ),
+            headerSourceSchema,
+        ),
+        /** Absent, every request carries only its headers. */
+        signIn: mcpSignInSchema.optional(),
+        /** The server's own tool names to offer; empty offers every tool. */
+        include: mcpToolNamesSchema.default([]),
+        exclude: mcpToolNamesSchema.default([]),
+        audience: audienceSchema,
+        overridable: overridable(["displayName", "include", "exclude", "headers", "signIn"]),
+    })
+    .superRefine((server, context) => {
+        const index = authorizationBesideSignIn(server);
+        if (index >= 0) {
+            context.addIssue({
+                code: "custom",
+                path: ["headers", index, "header"],
+                message: "the sign-in's token travels under Authorization",
+            });
+        }
+    });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
 /**
@@ -1458,6 +1574,10 @@ export const agentSettingsSchema = z.strictObject({
     toolRegistryEnabled: z.boolean().default(false),
     /** Lets `searchRegistries` search the services the agent sees. */
     serviceRegistryEnabled: z.boolean().default(false),
+    /** Lets the agent hand a task to a copy of itself (`delegateTask`), in its turn or in the background. */
+    subagentsEnabled: z.boolean().default(false),
+    /** Lets the agent schedule a check-back on a user's thread (`scheduleWake`): it comes back later on its own. */
+    checkBacksEnabled: z.boolean().default(false),
     attachmentsEnabled: z.boolean().default(true),
     /** Hosts the built-in `fetchImage` tool may pull images from; none, no such tool. */
     fetchImageHostnames: z
@@ -1468,7 +1588,9 @@ export const agentSettingsSchema = z.strictObject({
     /** The fenced media forms the agent may draw, which its prompt then describes. */
     media: z.array(z.enum(MEDIA_FORMS)).default([...DEFAULT_MEDIA_FORMS]),
     /** Off, end users cannot message the agent: only its triggers reach it. */
-    messageTrigger: z.boolean().default(true),
+    messages: z.boolean().default(true),
+    /** A message sent while the agent works: refused, queued, or steering the running turn. */
+    whileBusy: z.enum(WHILE_BUSY).default("refuse"),
     defaultLocale: localeSchema.default(BASE_LOCALE),
     context: z
         .strictObject({

package/src/contracts/runs/index.ts

@@ -0,0 +1,187 @@
+import { z } from "zod";
+
+/*
+ * Runs: every piece of work Cortex does on a thread, a turn, a subagent or a
+ * tool moved to the background. A run that is `running` holds a lease its
+ * producer renews; one past its lease is lost.
+ */
+
+export const RUN_KINDS = ["turn", "subagent", "tool"] as const;
+
+export const RUN_STATUSES = ["running", "waiting", "completed", "failed", "cancelled"] as const;
+export type RunStatus = (typeof RUN_STATUSES)[number];
+
+/**
+ * Why a run ended as it did: a trigger's answer that never came or never
+ * fit its schema, a stop, a cancel (its own, or its parent's), a producer
+ * that died (`lost`), or one that ran out of time.
+ */
+export const RUN_REASONS = [
+    "no_output",
+    "invalid_output",
+    "stopped",
+    "cancelled",
+    "parent_cancelled",
+    "lost",
+    "timeout",
+] as const;
+export type RunReason = (typeof RUN_REASONS)[number];
+
+/*
+ * Inputs: anything that asks a thread for work. Every source offers one the
+ * same way, and a run takes it: a user's message, a trigger's fire, a
+ * schedule come due, a finished run waking its parent.
+ */
+
+export const INPUT_SOURCES = ["user", "trigger", "schedule", "run"] as const;
+export type InputSource = (typeof INPUT_SOURCES)[number];
+
+/**
+ * How an input reaches its thread. `prompt`: the thread's busy rule decides
+ * (`whileBusy`). `steer`: it joins the running turn before its next step.
+ * `followUp`: a turn of its own after the running one. `answer`: it decides
+ * a run's waits. `note`: an event message, and no turn.
+ */
+export const INPUT_DELIVERIES = ["prompt", "steer", "followUp", "answer", "note"] as const;
+export type InputDelivery = (typeof INPUT_DELIVERIES)[number];
+
+/** `scheduled` until it is due, `waiting` for a run, `taken` by one, `done` once that run stored it; or `refused`, or `cancelled`. */
+export const INPUT_STATES = [
+    "scheduled",
+    "waiting",
+    "taken",
+    "done",
+    "refused",
+    "cancelled",
+] as const;
+export type InputState = (typeof INPUT_STATES)[number];
+
+/**
+ * Why an input was refused: its thread is busy and its busy rule refuses, a
+ * call waits for a decision, its key names an input with another actor or
+ * body, the agent's request bucket or the trigger's daily budget is spent,
+ * the thread holds as many waiting prompts as it takes, or an answer finds
+ * no call waiting for it.
+ */
+export const INPUT_REFUSALS = [
+    "busy",
+    "approval_pending",
+    "conflict",
+    "rate_limited",
+    "budget",
+    "full",
+    "not_waiting",
+] as const;
+export type InputRefusal = (typeof INPUT_REFUSALS)[number];
+
+/** Why an input that waited never ran: the thread was stopped or deleted, or its trigger was. */
+export const INPUT_CANCEL_REASONS = ["stopped"] as const;
+export type InputCancelReason = (typeof INPUT_CANCEL_REASONS)[number];
+
+/** Every reason an input records: a refusal, or why it never ran. */
+export const INPUT_REASONS = [...INPUT_REFUSALS, ...INPUT_CANCEL_REASONS] as const;
+
+/** Who a run acts as: a user, or the named credential a trigger acts with. */
+export type Actor = { type: "user"; id: string } | { type: "credential"; name: string };
+
+/**
+ * What became of an offered input no run took at once: `POST /chat` and a
+ * trigger's fire answer 202 while it waits, 409 or 429 once it is refused,
+ * and a fire held for its run (`?wait=`) 409 once it was cancelled before
+ * any run took it.
+ * A refused input is kept for its history (`inputId`), except a
+ * `conflict`, whose key names another input, an answer nothing waits for
+ * (`not_waiting`), and one the agent's request bucket refused
+ * (`rate_limited`), which leave nothing behind.
+ */
+export const inputReceiptSchema = z.discriminatedUnion("state", [
+    z.object({
+        inputId: z.uuid(),
+        state: z.literal("waiting"),
+        delivery: z.enum(INPUT_DELIVERIES),
+    }),
+    z.object({
+        inputId: z.uuid().nullable(),
+        state: z.literal("refused"),
+        reason: z.enum(INPUT_REFUSALS),
+    }),
+    /* An input that waited and never ran (`INPUT_CANCEL_REASONS`). */
+    z.object({
+        inputId: z.uuid(),
+        state: z.literal("cancelled"),
+        reason: z.enum(INPUT_CANCEL_REASONS),
+    }),
+]);
+export type InputReceipt = z.infer<typeof inputReceiptSchema>;
+
+/*
+ * Waits: what a run needs from outside before it goes on. A run that parks
+ * opens one per call it stopped on and waits until each is answered, or
+ * ends, which cancels those still open.
+ */
+
+/** `approval`: a server tool call someone decides. `client_tool`: a call the widget runs and answers. */
+export const WAIT_KINDS = ["approval", "client_tool"] as const;
+
+export const WAIT_STATES = ["open", "answered", "cancelled"] as const;
+export type WaitState = (typeof WAIT_STATES)[number];
+
+/**
+ * One call a waiting run waits on, and the arguments it was made with: an
+ * approval, which `POST /agents/:agentName/runs/:id/answer` decides, or a
+ * client tool's call, which its widget answers.
+ */
+export const runWaitSchema = z.object({
+    kind: z.enum(WAIT_KINDS),
+    toolCallId: z.string(),
+    toolName: z.string(),
+    input: z.unknown(),
+});
+export type RunWait = z.infer<typeof runWaitSchema>;
+
+/**
+ * A run as `GET /agents/:agentName/runs/:id` reads it, and each row of
+ * `GET /agents/:agentName/triggers/:name/runs`: the input it answers, and
+ * its thread, null once that thread is gone.
+ */
+export const runRecordSchema = z.object({
+    id: z.uuid(),
+    threadId: z.uuid().nullable(),
+    inputId: z.uuid().nullable(),
+    kind: z.enum(RUN_KINDS),
+    /** A subagent's run: the id its parent's stream knew it by; each run of a copy has its own. */
+    subagentRunId: z.string().nullable(),
+    status: z.enum(RUN_STATUSES),
+    reason: z.enum(RUN_REASONS).nullable(),
+    /**
+     * What a completed run answered with: a trigger's validated answer when
+     * it declares an output schema, else the run's last text (null when it
+     * wrote none), cut past 1 MiB with a trailing `…[truncated]`; null for
+     * any other status.
+     */
+    result: z.unknown(),
+    /** The calls a `waiting` run waits on; empty for any other status. */
+    waits: z.array(runWaitSchema),
+    createdAt: z.iso.datetime(),
+    finishedAt: z.iso.datetime().nullable(),
+});
+export type RunRecord = z.infer<typeof runRecordSchema>;
+
+/** `GET /agents/:agentName/triggers/:name/runs`: a page of the trigger's runs, newest first. */
+export const runListSchema = z.object({ runs: z.array(runRecordSchema) });
+export type RunList = z.infer<typeof runListSchema>;
+
+/** `POST /agents/:agentName/runs/:id/cancel`: whether it stopped or ended anything; a run already over is left as it is. */
+export const runCancelSchema = z.object({ cancelled: z.boolean() });
+export type RunCancel = z.infer<typeof runCancelSchema>;
+
+/**
+ * `POST /agents/:agentName/runs/:id/answer`: the decision on one call the
+ * run waits on. 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.
+ */
+export const runAnswerSchema = z.object({
+    toolCallId: z.string().min(1),
+    approved: z.boolean(),
+});
+export type RunAnswer = z.infer<typeof runAnswerSchema>;

package/src/contracts/schedule/index.ts

@@ -0,0 +1,62 @@
+import { CronExpressionParser } from "cron-parser";
+import { z } from "zod";
+
+/*
+ * A trigger's schedule: a five-field cron read in an IANA time zone, on
+ * which Cortex fires the trigger itself. The manifest checks one with
+ * `triggerScheduleSchema`, the console with its own words for the same
+ * checks (`triggerScheduleSchemaWith`); the sweep that fires it and the console
+ * that shows what comes next read its times with `dueTimes`.
+ */
+
+/** Whether `timeZone` is an IANA zone this runtime knows. */
+function isTimeZone(timeZone: string) {
+    try {
+        new Intl.DateTimeFormat("en", { timeZone });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Whether `cron` is five fields (minute, hour, day of month, month, day of
+ * week) the parser reads; seconds and aliases are left out, and so is `H`,
+ * which the parser fills with a new random value on every read.
+ */
+function isCron(cron: string) {
+    if (cron.split(/\s+/).length !== 5 || /\bH\b/i.test(cron)) return false;
+    try {
+        CronExpressionParser.parse(cron);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * A schedule whose issues read `messages`, by the field each sits on: the
+ * console passes its translations, `triggerScheduleSchema` the English the
+ * manifest and the API answer with.
+ */
+export function triggerScheduleSchemaWith(messages: Record<"cron" | "timeZone", () => string>) {
+    return z.object({
+        cron: z.string().trim().refine(isCron, { error: messages.cron }),
+        timeZone: z.string().trim().refine(isTimeZone, { error: messages.timeZone }),
+    });
+}
+
+export const triggerScheduleSchema = triggerScheduleSchemaWith({
+    cron: () => "is not a cron of five fields: minute, hour, day of month, month, day of week",
+    timeZone: () => "is not an IANA time zone, such as Asia/Dubai",
+});
+export type TriggerSchedule = z.infer<typeof triggerScheduleSchema>;
+
+/** The `count` times `schedule` falls due after `after`, soonest first. */
+export function dueTimes(schedule: TriggerSchedule, after: Date, count = 1) {
+    const expression = CronExpressionParser.parse(schedule.cron, {
+        tz: schedule.timeZone,
+        currentDate: after,
+    });
+    return Array.from({ length: count }, () => expression.next().toDate());
+}