@m6d/cortex-cli 0.22.0 → 0.24.0

package/src/contracts/pattern/index.ts

@@ -0,0 +1,276 @@
+// cspell:ignore fefe fff
+import { RE2JS } from "re2js";
+
+/*
+ * A tool input schema's `pattern`: a regular expression JavaScript reads with
+ * no flags, which Cortex matches on RE2 so a value is checked in time linear
+ * in its length. A pattern RE2 cannot match as JavaScript reads it is refused
+ * by Cortex and left out of what the TypeScript SDK exports.
+ *
+ * RE2 matches code points where JavaScript matches UTF-16 units, so the
+ * pattern and every input lift each surrogate unit into a private-use plane,
+ * where it is one code point: RE2 then reads the units JavaScript reads.
+ * Nothing collides there, since a real character in that plane is astral,
+ * arrives as two surrogate units and is lifted in turn.
+ */
+
+/**
+ * What one escape or character in a class stands for, spelled as the inside
+ * of an RE2 class: a single character carries its UTF-16 unit, and an
+ * unescaped `-` is marked as one that may make a range.
+ */
+type Atom = { body: string; char?: number; dash?: boolean };
+
+/** JavaScript's `\s`, its WhiteSpace and LineTerminator characters, as the inside of an RE2 class. */
+const SPACE =
+    "\\x{9}-\\x{d}\\x{20}\\x{a0}\\x{1680}\\x{2000}-\\x{200a}\\x{2028}\\x{2029}\\x{202f}\\x{205f}\\x{3000}\\x{feff}";
+/** Every character `SPACE` leaves out: JavaScript's `\S`. */
+const NON_SPACE =
+    "\\x{0}-\\x{8}\\x{e}-\\x{1f}\\x{21}-\\x{9f}\\x{a1}-\\x{167f}\\x{1681}-\\x{1fff}\\x{200b}-\\x{2027}" +
+    "\\x{202a}-\\x{202e}\\x{2030}-\\x{205e}\\x{2060}-\\x{2fff}\\x{3001}-\\x{fefe}\\x{ff00}-\\x{10ffff}";
+/** The set escapes as JavaScript reads them; RE2's own `\d` and `\w` match, its `\s` holds only ASCII. */
+const SET_ESCAPES = new Map([
+    ["d", "\\d"],
+    ["D", "\\D"],
+    ["w", "\\w"],
+    ["W", "\\W"],
+    ["s", SPACE],
+    ["S", NON_SPACE],
+]);
+/** JavaScript's `.`: every character but a line terminator, where RE2's leaves out only `\n`. */
+const DOT = "[^\\x{a}\\x{d}\\x{2028}\\x{2029}]";
+const CONTROL_ESCAPES = new Map([
+    ["f", 0x0c],
+    ["n", 0x0a],
+    ["r", 0x0d],
+    ["t", 0x09],
+    ["v", 0x0b],
+]);
+const QUANTIFIER = /\{\d+(?:,\d*)?\}/y;
+const SURROGATE = /[\uD800-\uDFFF]/g;
+/** Where surrogate unit `0xd800 + n` is lifted: code point `0xf0000 + n`. */
+const LIFTED_SURROGATES = 0xf0000;
+const HEX = /[0-9A-Fa-f]+/y;
+/** What JavaScript's `[^]` and `[]` hold: every character, and none. */
+const ANY = "[\\x{0}-\\x{10ffff}]";
+const NONE = "[^\\x{0}-\\x{10ffff}]";
+
+/** A thrown error: the pattern holds what RE2 cannot match as JavaScript reads it. */
+function unsupported(what: string): never {
+    throw new Error(`a pattern with ${what}`);
+}
+
+/** A UTF-16 unit as the one code point RE2 reads: a surrogate lifted, any other unit itself. */
+function lifted(unit: number) {
+    return unit >= 0xd800 && unit <= 0xdfff ? LIFTED_SURROGATES + unit - 0xd800 : unit;
+}
+
+/** `input` with every surrogate unit lifted, one code point per UTF-16 unit. */
+function liftedText(input: string) {
+    return input.replace(SURROGATE, (unit) => String.fromCodePoint(lifted(unit.charCodeAt(0))));
+}
+
+/** One UTF-16 unit as RE2 reads it literally, inside a class or out. */
+function literal(unit: number) {
+    const char = lifted(unit);
+    const spelled = String.fromCodePoint(char);
+    return /^[A-Za-z0-9]$/.test(spelled) ? spelled : `\\x{${char.toString(16)}}`;
+}
+
+/**
+ * The units from `from` to `to` as the inside of an RE2 class: the part
+ * among the surrogates, lifted, apart from the parts below and above it.
+ */
+function unitRange(from: number, to: number) {
+    return (
+        [
+            [from, Math.min(to, 0xd7ff)],
+            [Math.max(from, 0xd800), Math.min(to, 0xdfff)],
+            [Math.max(from, 0xe000), to],
+        ] satisfies Array<[number, number]>
+    )
+        .filter(([low, high]) => low <= high)
+        .map(([low, high]) => `${literal(low)}-${literal(high)}`)
+        .join("");
+}
+
+function character(char: number, dash = false) {
+    return { body: literal(char), char, dash };
+}
+
+/**
+ * A class's atoms as the inside of an RE2 class: an unescaped dash between
+ * two characters makes a range, and beside a set escape it is a character,
+ * as JavaScript reads them.
+ */
+function classBody(atoms: Atom[]) {
+    let body = "";
+    for (let index = 0; index < atoms.length; index += 1) {
+        const [from, dash, to] = atoms.slice(index, index + 3);
+        if (!from) break;
+        if (!dash?.dash || !to) {
+            body += from.body;
+            continue;
+        }
+        body +=
+            from.char !== undefined && to.char !== undefined
+                ? unitRange(from.char, to.char)
+                : `${from.body}${dash.body}${to.body}`;
+        index += 2;
+    }
+    return body;
+}
+
+/**
+ * A pattern read left to right as JavaScript reads it with no flags (Annex B
+ * included), written in RE2's syntax; throws on a lookaround, a
+ * backreference, a legacy octal escape, a group modifier or a `\c` without
+ * its letter. It reads UTF-16 units, as JavaScript does. Groups do not
+ * capture: nothing reads them.
+ */
+class Translation {
+    private at = 0;
+
+    public constructor(private readonly pattern: string) {}
+
+    public spell() {
+        let re2 = "";
+        while (this.at < this.pattern.length) re2 += this.term();
+        return re2;
+    }
+
+    private term() {
+        const char = this.pattern[this.at] ?? "";
+        if (char === "\\") return this.escapeOutsideClass();
+        if (char === "[") return this.characterClass();
+        if (char === "(") return this.group();
+        if (char === "{") return this.brace();
+        if (!"|)^$*+?.".includes(char)) return literal(this.unit());
+        this.at += 1;
+        return char === "." ? DOT : char;
+    }
+
+    private escapeOutsideClass() {
+        this.at += 1;
+        const assertion = this.pattern[this.at];
+        if (assertion === "b" || assertion === "B") {
+            this.at += 1;
+            return `\\${assertion}`;
+        }
+        const atom = this.escape(false);
+        return "char" in atom ? atom.body : `[${atom.body}]`;
+    }
+
+    /** The escape after a backslash, which `at` is past; in a class `\b` is a backspace. */
+    private escape(insideClass: boolean) {
+        const next = this.pattern[this.at] ?? unsupported("a trailing backslash");
+        this.at += 1;
+        const set = SET_ESCAPES.get(next);
+        if (set) return { body: set };
+        const control = insideClass && next === "b" ? 0x08 : CONTROL_ESCAPES.get(next);
+        if (control !== undefined) return character(control);
+        if (next === "c") return character(this.controlLetter(insideClass));
+        if (next === "x" || next === "u") {
+            return character(this.hex(next === "x" ? 2 : 4) ?? next.charCodeAt(0));
+        }
+        if (next === "0" && !/^\d$/.test(this.pattern[this.at] ?? "")) return character(0);
+        if (/^[\dk]$/.test(next)) unsupported("a backreference or an octal escape");
+        this.at -= 1;
+        return character(this.unit());
+    }
+
+    /** The control character a `\c` names: a letter, or in a class also a digit or `_`. */
+    private controlLetter(insideClass: boolean) {
+        const letter = this.pattern[this.at] ?? "";
+        if (!(insideClass ? /^\w$/ : /^[A-Za-z]$/).test(letter)) {
+            unsupported("a \\c without its letter");
+        }
+        this.at += 1;
+        return letter.charCodeAt(0) % 32;
+    }
+
+    /** `length` hex digits at `at` as a UTF-16 unit, consumed; undefined when fewer follow. */
+    private hex(length: number) {
+        HEX.lastIndex = this.at;
+        const digits = HEX.exec(this.pattern)?.[0] ?? "";
+        if (digits.length < length) return undefined;
+        this.at += length;
+        return Number.parseInt(digits.slice(0, length), 16);
+    }
+
+    private unit() {
+        const unit = this.pattern.charCodeAt(this.at);
+        if (Number.isNaN(unit)) unsupported("a pattern cut short");
+        this.at += 1;
+        return unit;
+    }
+
+    /**
+     * A class, `at` on its `[`. In JavaScript a `]` always closes one, so
+     * `[]` holds nothing and `[^]` everything.
+     */
+    private characterClass() {
+        this.at += 1;
+        const negated = this.pattern[this.at] === "^";
+        if (negated) this.at += 1;
+        const atoms: Atom[] = [];
+        while (this.pattern[this.at] !== "]") {
+            if (this.at >= this.pattern.length) unsupported("an unclosed class");
+            atoms.push(this.classAtom());
+        }
+        this.at += 1;
+        const body = classBody(atoms);
+        if (!body) return negated ? ANY : NONE;
+        return `[${negated ? "^" : ""}${body}]`;
+    }
+
+    private classAtom() {
+        const char = this.pattern[this.at];
+        this.at += 1;
+        if (char === "\\") return this.escape(true);
+        if (char === "-") return character(0x2d, true);
+        this.at -= 1;
+        return character(this.unit());
+    }
+
+    /** A group's opening as RE2 reads it: every group, named or not, without a capture. */
+    private group() {
+        const opening = this.pattern.slice(this.at, this.at + 4);
+        if (/^\(\?<[^=!]/.test(opening)) {
+            const name = this.pattern.indexOf(">", this.at);
+            if (name < 0) unsupported("an unclosed group name");
+            this.at = name + 1;
+        } else if (opening.startsWith("(?")) {
+            if (!opening.startsWith("(?:")) unsupported("a lookaround or a group modifier");
+            this.at += 3;
+        } else {
+            this.at += 1;
+        }
+        return "(?:";
+    }
+
+    /** A quantifier, or a brace JavaScript reads as a character because it opens none. */
+    private brace() {
+        QUANTIFIER.lastIndex = this.at;
+        const quantifier = QUANTIFIER.exec(this.pattern)?.[0];
+        this.at += quantifier?.length ?? 1;
+        return quantifier ?? literal(0x7b);
+    }
+}
+
+/**
+ * A matcher for a pattern JavaScript compiles, meaning what the pattern
+ * means to JavaScript with no flags, UTF-16 unit for unit; undefined when
+ * RE2 cannot match it so, as for a lookaround, a backreference or a
+ * repetition past 1000. Its `test` runs on RE2, in time linear in the input.
+ * It never calls `new RegExp`, so it works while a caller has replaced that
+ * global.
+ */
+export function linearPattern(pattern: string) {
+    try {
+        const re2 = RE2JS.compile(new Translation(pattern).spell());
+        return { test: (input: string) => re2.test(liftedText(input)) };
+    } catch {
+        return undefined;
+    }
+}

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());
+}