@cotal-ai/runtime 0.0.1 → 0.25.0

package/dist/resolve-checkpoint.js

@@ -0,0 +1,108 @@
+/**
+ * `resolveCheckpoint` — the run-driver command through which a checkpoint is answered.
+ *
+ * **Nothing outside presents the token.** A checkpoint's resume is holder-bound (SPEC §13.10), and
+ * a workflow checkpoint's holder is the run driver: it is the one principal guaranteed to exist for
+ * the pause's whole life. So an observer UI, a notification action, or another agent does not talk
+ * to `endpoint-checkpoint` at all — each calls this, which authorizes the caller under the run's
+ * own ACL, files their answer, and then presents the token as the driver. "Resolvable from
+ * anywhere" is true at the product level while resume stays holder-bound at the protocol level, and
+ * §13.10 is not weakened by a millimetre. The cost is that the driver must be reachable to answer a
+ * checkpoint, which is the same condition under which the run advances at all.
+ *
+ * **The answer is written BEFORE the token is presented,** and the two are separate facts on
+ * purpose. The record is the payload; the settle is the one-use arbiter that releases the run. In
+ * that order a crash in between leaves an answer nobody accepted — orphaned, read by nothing, and
+ * harmless. In the other order it would leave a run released with its answer nowhere.
+ *
+ * **The step is addressed by its KEY, not by its token.** A token is `ctx.requestId`, derived from
+ * the run, the step key, the input hash and the attempt, and a resolver has none of those: it knows
+ * "the checkpoint named `approve` in this run". The journal is what maps one to the other, and it is
+ * also what says whether that step is still open — which is the question a resolver most needs
+ * answered before it collects a human's decision.
+ */
+import { replayRunJournal, newTakeoverId, recordCheckpointAnswer, checkpointAnswerId, resumeCheckpoint, } from "@cotal-ai/core";
+import { journalEntryKeyString } from "@cotal-ai/lang";
+/** No open checkpoint answers to this address in this run. */
+export class CheckpointNotOpen extends Error {
+    runId;
+    stepKey;
+    why;
+    constructor(runId, stepKey, why) {
+        super(`run ${runId} has no open checkpoint at ${stepKey}: ${{
+            unknown: "no step is recorded under that key",
+            settled: "that step has already settled",
+            "not-a-checkpoint": "that step is not a checkpoint",
+            "no-identity": "that step is pending but carries no request id, so the checkpoint it is waiting on cannot be named",
+        }[why]}`);
+        this.runId = runId;
+        this.stepKey = stepKey;
+        this.why = why;
+        this.name = "CheckpointNotOpen";
+    }
+}
+/**
+ * Answer a run's open checkpoint.
+ *
+ * Refusals are the plane's own and are not softened here: a checkpoint already resumed is a
+ * `conflict` (resume authorization is one-use) and one already expired is a `failed-precondition`
+ * (expiry fails closed). Both mean the answer arrived too late, and both leave this resolver's
+ * record filed and unaccepted — which is what the caller needs to be told rather than a success
+ * that names a settlement somebody else won.
+ */
+export async function resolveCheckpoint(deps, req) {
+    const entries = await replayRunEntries(deps, req.runId);
+    const token = openCheckpointToken(entries, req.runId, req.stepKey);
+    const answerId = checkpointAnswerId({
+        token,
+        by: req.by,
+        ...(req.value !== undefined ? { value: req.value } : {}),
+        ...(req.artifact !== undefined ? { artifact: req.artifact } : {}),
+    });
+    await recordCheckpointAnswer(deps.kv, deps.endpoint, {
+        v: 1,
+        token,
+        answerId,
+        ...(req.value !== undefined ? { value: req.value } : {}),
+        ...(req.artifact !== undefined ? { artifact: req.artifact } : {}),
+        by: req.by,
+        at: req.now,
+    });
+    const settle = await resumeCheckpoint(deps.kv, deps.js, deps.jsm, deps.space, {
+        ref: { endpoint: deps.endpoint, token },
+        presenter: deps.holder,
+        now: req.now,
+        answerId,
+    });
+    return { token, answerId, settle };
+}
+/** The token of the open checkpoint at this address, or a loud refusal naming which it is not. */
+export function openCheckpointToken(entries, runId, stepKey) {
+    // Append order, later record wins: a settled step has a settled entry written after its pending
+    // one, and answering the pending one would present a token whose pause is already over.
+    let entry;
+    for (const e of entries)
+        if (journalEntryKeyString(e) === stepKey)
+            entry = e;
+    if (entry === undefined)
+        throw new CheckpointNotOpen(runId, stepKey, "unknown");
+    if (entry.kind !== "checkpoint")
+        throw new CheckpointNotOpen(runId, stepKey, "not-a-checkpoint");
+    if (entry.state !== "pending")
+        throw new CheckpointNotOpen(runId, stepKey, "settled");
+    if (entry.requestId === undefined)
+        throw new CheckpointNotOpen(runId, stepKey, "no-identity");
+    return entry.requestId;
+}
+/** The run's step entries, in append order. Read-only: this replays under its own consumer name and
+ *  activates nothing, so it never contends with the driver actually holding the run. */
+async function replayRunEntries(deps, runId) {
+    const replay = await replayRunJournal(deps.js, deps.jsm, deps.space, runId, newTakeoverId());
+    const entries = [];
+    for (const stored of replay.records) {
+        if (stored.record.kind === "step")
+            entries.push(stored.record.entry);
+    }
+    return entries;
+}
+//# sourceMappingURL=resolve-checkpoint.js.map

package/dist/resolve-checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-checkpoint.js","sourceRoot":"","sources":["../src/resolve-checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/run-context.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `<run-context>` render: what a workflow's notices look like in an agent's context.
+ *
+ * **A fixed key→value table, never a sentence.** The property this buys is the whole reason
+ * `notify` exists in its bounded form: a notice reads as DATA in the receiving agent's context and
+ * cannot be mistaken for an instruction from the workflow. Prose would be an instruction whatever
+ * intended, because an agent reading prose in its prompt has no way to tell who wrote it.
+ *
+ * Eight short scalars in a labelled table is not enough room to write an instruction. That is the
+ * bound's purpose rather than a side effect of it, and it is enforced at the effect boundary
+ * (L3043) before a notice is ever written — so this renderer never has to decide what to do with a
+ * value it cannot render. It REFUSES one instead: a value that could end a line could forge a row
+ * or a closing tag, and a renderer that quietly escaped it would be the one place where the bound
+ * is a formatting convention rather than a rule.
+ */
+import type { RunNoticeRead } from "@cotal-ai/core";
+/** A notice this renderer cannot put in one row. Loud, because the alternative is a forged row. */
+export declare class UnrenderableNotice extends Error {
+    readonly noticeId: string;
+    readonly field: string;
+    constructor(noticeId: string, field: string);
+}
+export interface RunContextRender {
+    /** The run whose notices these are. */
+    readonly run: string;
+    /** The step the addressee is about to take — the coordinates of the turn this precedes, not of
+     *  the steps that decided the notices. Each notice's own step is a fact about the program's
+     *  history and belongs to the run, not to this header. */
+    readonly step: string;
+    readonly notices: readonly RunNoticeRead[];
+}
+/**
+ * Render the notices addressed to one agent, ahead of one turn.
+ *
+ * Columns are padded to a fixed layout so the table reads as a table; the detail column is
+ * `key=value` pairs in the order the notice recorded them, which is the order the program wrote
+ * them. An empty set renders as an empty table rather than as nothing: "no decisions were told to
+ * you" and "nobody rendered your context" are different facts, and only one of them is this
+ * renderer's to state.
+ */
+export declare function renderRunContext(req: RunContextRender): string;
+//# sourceMappingURL=run-context.d.ts.map

package/dist/run-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.d.ts","sourceRoot":"","sources":["../src/run-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD,mGAAmG;AACnG,qBAAa,kBAAmB,SAAQ,KAAK;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAxC,QAAQ,EAAE,MAAM,EAAW,KAAK,EAAE,MAAM;CAO9D;AAED,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;8DAE0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAUD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CA0B9D"}

package/dist/run-context.js

@@ -0,0 +1,55 @@
+/** A value that would break out of one table row — a control character, a line separator, or one
+ *  of the characters the header line is built from. The effect boundary already excludes these from
+ *  a notice; this is the second reader of the same rule, at the point where breaking out matters. */
+const UNRENDERABLE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029"<>]/;
+/** A notice this renderer cannot put in one row. Loud, because the alternative is a forged row. */
+export class UnrenderableNotice extends Error {
+    noticeId;
+    field;
+    constructor(noticeId, field) {
+        super(`notice ${noticeId} carries a line break, a control character or a delimiter in ${field}; ` +
+            `a run-context row is one line, and a value that can end a line can forge a row or the closing tag`);
+        this.noticeId = noticeId;
+        this.field = field;
+        this.name = "UnrenderableNotice";
+    }
+}
+const HEADER = { decision: "decision", outcome: "outcome", detail: "detail" };
+/**
+ * Render the notices addressed to one agent, ahead of one turn.
+ *
+ * Columns are padded to a fixed layout so the table reads as a table; the detail column is
+ * `key=value` pairs in the order the notice recorded them, which is the order the program wrote
+ * them. An empty set renders as an empty table rather than as nothing: "no decisions were told to
+ * you" and "nobody rendered your context" are different facts, and only one of them is this
+ * renderer's to state.
+ */
+export function renderRunContext(req) {
+    for (const [field, value] of [["run", req.run], ["step", req.step]])
+        if (UNRENDERABLE.test(value))
+            throw new UnrenderableNotice(`<${field}>`, field);
+    const rows = req.notices.map((n) => {
+        const fact = n.spec.fact;
+        for (const [field, value] of [["decision", fact.decision], ["outcome", fact.outcome]])
+            if (UNRENDERABLE.test(value))
+                throw new UnrenderableNotice(n.noticeId, field);
+        const detail = Object.entries(fact.detail ?? {}).map(([k, v]) => {
+            if (UNRENDERABLE.test(k))
+                throw new UnrenderableNotice(n.noticeId, `detail key ${k}`);
+            if (typeof v === "string" && UNRENDERABLE.test(v))
+                throw new UnrenderableNotice(n.noticeId, `detail.${k}`);
+            return `${k}=${String(v)}`;
+        });
+        return { decision: fact.decision, outcome: fact.outcome, detail: detail.join("  ") };
+    });
+    const all = [HEADER, ...rows];
+    const dW = Math.max(...all.map((r) => r.decision.length));
+    const oW = Math.max(...all.map((r) => r.outcome.length));
+    const line = (r) => `${r.decision.padEnd(dW)}  ${r.outcome.padEnd(oW)}  ${r.detail}`.trimEnd();
+    return [
+        `<run-context run="${req.run}" step="${req.step}">`,
+        ...all.map(line),
+        "</run-context>",
+    ].join("\n");
+}
+//# sourceMappingURL=run-context.js.map

package/dist/run-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.js","sourceRoot":"","sources":["../src/run-context.ts"],"names":[],"mappings":"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"}

package/dist/run-driver.d.ts

@@ -0,0 +1,124 @@
+import type { JetStreamClient, JetStreamManager } from "@nats-io/jetstream";
+import type { KV } from "@nats-io/kv";
+import { type EffectHandler, type JournalEntry, type RunResult } from "@cotal-ai/lang";
+/**
+ * The lease this driver holds the run under, from the work pool.
+ *
+ * `fencingToken` is `WorkLease.fencingToken` — monotonic per item, and the coordinate the barrier
+ * orders takeovers by. `holder` and `epoch` are the identity it is bound to: a token alone would let
+ * a returning process re-establish itself on a lease it still remembers, which is the same defect
+ * the barrier exists to prevent.
+ */
+export interface RunLease {
+    readonly holder: string;
+    readonly epoch: number;
+    readonly fencingToken: number;
+    /**
+     * The takeover id this driver's journal credential was minted for.
+     *
+     * It names the replay consumer, and a consumer name is one subject token, so it cannot be covered
+     * by a grant pattern — it has to be known when the rows are minted. That is when the lease is
+     * handed out, which is why it arrives with the lease rather than being chosen here.
+     */
+    readonly takeoverId: string;
+}
+/**
+ * A pause an operator can ask for while a run is being driven.
+ *
+ * The driver reads it before each effect it has not already recorded, so a pause takes effect at the
+ * next boundary and never in the middle of one. It is one-way on purpose: resuming is starting a
+ * drive again, which is the same act as any other takeover and goes through the barrier like one.
+ */
+export declare class PauseToken {
+    private why;
+    pause(reason: string): void;
+    get reason(): string | undefined;
+}
+export interface DriveRequest {
+    readonly space: string;
+    /**
+     * The endpoint HOSTING this driver — the manager daemon. It leads the run record's
+     * key, so a retirement drain and a per-endpoint enumeration both work by prefix.
+     */
+    readonly endpoint: string;
+    readonly runId: string;
+    /** The program. A resume MUST be handed the same source: a different one is a fork, not a resume. */
+    readonly source: string;
+    readonly lease: RunLease;
+    readonly handler: EffectHandler;
+    /**
+     * The records bucket. NOT optional, and deliberately so: the run record holds the pins a resume
+     * must read back and the high-water ordinal that is the only thing able to see a truncated
+     * journal tail. A driver that could run without it would skip both silently, which is the failure
+     * mode both exist to prevent.
+     */
+    readonly kv: KV;
+    readonly seed?: string;
+    readonly file?: string;
+    readonly effectCeiling?: number;
+    readonly stepBudget?: number;
+    /**
+     * The ABSOLUTE work horizon this driver accepted the item under (`WorkLease.workExpiry`).
+     *
+     * Past it the pool has already reconciled the item, so a driver still appending is writing into a
+     * run the authority considers finished with. Nothing needs to be read to know this: the horizon is
+     * fixed at acceptance and never re-set (SPEC 13.8), which is exactly what makes it safe to check
+     * locally — unlike a lease deadline, whose current value is a fact on another machine and whose
+     * check would be a read-then-publish with a gap that cannot be closed.
+     */
+    readonly workExpiry?: number;
+    /** An operator's pause, honoured at the next effect boundary. */
+    readonly pause?: PauseToken;
+    /**
+     * Repair external state bound to the PREVIOUS holder, once this driver holds the run and before
+     * the program is resumed.
+     *
+     * The case that exists is timers: a checkpoint's armed schedule fires onto a subject derived from
+     * the instance and epoch that armed it, so a run adopted by another host has live timers firing
+     * where nobody is listening, and resuming the program does not repair that — the pause replays as
+     * pending and goes straight back to waiting. What to re-arm is the mesh handler's business, not
+     * the driver's, so the driver only says WHEN: after the activation, because arming timers for a
+     * run this process turned out not to hold would point another driver's fires at this one.
+     *
+     * A failure here is a failure to take the run over, and is not swallowed: a driver that resumed a
+     * program whose pauses it could not re-arm would look like it was holding a run it cannot advance.
+     *
+     * OPTIONAL BECAUSE IT IS AN OVERRIDE, NOT BECAUSE THE REPAIR IS. A handler that knows how to
+     * repair its own external state says so with an `adopted` method, and the driver calls that when
+     * no callback is supplied — found by review, which noticed that this hook had NO caller anywhere
+     * in the tree, so every adopted run left its timers armed at the predecessor's coordinates. A
+     * seam that every future host must remember to wire is a defect waiting on its first host.
+     */
+    readonly onActivated?: (entries: readonly JournalEntry[]) => Promise<void>;
+}
+/**
+ * A handler that owns external state bound to whoever was holding the run, and can repair it.
+ *
+ * Declared here rather than on `EffectHandler` because it is the DRIVER's concern: the language's
+ * handler interface describes performing effects, and nothing in `packages/lang` has a notion of one
+ * host taking a run over from another.
+ */
+export interface AdoptingHandler {
+    adopted(entries: readonly JournalEntry[]): Promise<unknown>;
+}
+/**
+ * What a drive attempt did, as a two-exit answer rather than a value plus exceptions.
+ *
+ * `completed` is the program finishing under this driver. `released` is this driver ceasing to hold
+ * the run — superseded, stalled, retired — which says nothing about the program and must never be
+ * recorded as if it did. A program that FAILS is still `completed`: the failure is the run's result,
+ * and the journal has it.
+ */
+export type DriveOutcome = {
+    readonly status: "completed";
+    readonly result: RunResult;
+} | {
+    readonly status: "released";
+    readonly reason: Error;
+};
+/** Start a run that has never been driven. Refused if the journal already has records. */
+export declare function startRun(js: JetStreamClient, jsm: JetStreamManager, req: DriveRequest): Promise<DriveOutcome>;
+/** Take over a run that already exists and drive it to quiescence. Refused if its journal is empty:
+ *  a run whose records were purged is retired, and re-running it would repeat what it already did. */
+export declare function driveRun(js: JetStreamClient, jsm: JetStreamManager, req: DriveRequest): Promise<DriveOutcome>;
+//# sourceMappingURL=run-driver.d.ts.map

package/dist/run-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-driver.d.ts","sourceRoot":"","sources":["../src/run-driver.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAWL,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAyHxB;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAqB;IAEhC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,IAAI,MAAM,IAAI,MAAM,GAAG,SAAS,CAE/B;CACF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qGAAqG;IACrG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAOD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;CAAE,CAAC;AAE5D,0FAA0F;AAC1F,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,eAAe,EACnB,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED;sGACsG;AACtG,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,eAAe,EACnB,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,YAAY,CAAC,CAEvB"}