@juno-ai/bind 2.0.0 → 4.0.0

package/run/children.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Child runs: lineage, admission, and waiting.
+ *
+ * A sub-agent is not a special kind of thing — it is **a run that another run
+ * asked for**. Everything the harness already gives a run applies to it
+ * unchanged: its own deadline, its own heartbeat, its own stats, its own route
+ * plan. What is genuinely new is the relationship between runs, and that is
+ * what this module owns:
+ *
+ *  - **Lineage** — where a run sits in the chain that produced it.
+ *  - **Admission** — whether the next child may be created at all.
+ *  - **Waiting** — how long to sleep before checking on a child again.
+ *
+ * All three are pure. The queue, the persistence, the counting, and the choice
+ * of bounds stay with the host: the harness decides, it does not measure. That
+ * split is deliberate — counting runs needs a database, and deciding whether a
+ * count is too high does not.
+ */
+/**
+ * A run's position in the chain that spawned it.
+ *
+ * `rootRunId` and `parentRunId` are `null` at depth 0, where the run *is* the
+ * root — a chain's origin has no id to point at until its own row exists, so
+ * the convention is "null means me". Read the root of any chain as
+ * `chain.rootRunId ?? thisRunId`; {@link descendChain} does exactly that when
+ * it hands the id down, so every descendant carries a concrete root.
+ */
+export interface ChainRef {
+    /** 0 for a run nobody spawned; one more than its parent otherwise. */
+    readonly depth: number;
+    /** The run that started the chain, or `null` when this run is that run. */
+    readonly rootRunId: string | null;
+    /** The run that spawned this one, or `null` when nothing did. */
+    readonly parentRunId: string | null;
+}
+/** The lineage of a run that nothing spawned — the origin of a new chain. */
+export declare function rootChain(): ChainRef;
+/**
+ * The lineage a child of `parentRunId` should carry.
+ *
+ * The root-id fallback is the part hosts get wrong: a depth-1 child must adopt
+ * its parent's *id* as the root (the parent's own `rootRunId` is null), while a
+ * depth-2 grandchild must adopt the root the parent already carries. Getting it
+ * backwards makes each generation start a fresh chain, which silently defeats
+ * every per-chain bound — the counts stay small because they count the wrong
+ * set.
+ */
+export declare function descendChain(parentRunId: string, parent: Pick<ChainRef, "depth" | "rootRunId">): ChainRef;
+/**
+ * One admission rule, carrying its limit and the measurement it applies to.
+ *
+ * Limit and fact travel together on purpose. The alternative — a bounds object
+ * beside a facts object — lets a host configure a bound whose count was never
+ * wired up, and the only symptom is a limit that silently never fires. Here a
+ * rule cannot be expressed without the number it judges, so a host pays only
+ * for what it actually measures and cannot ask for a bound it does not feed.
+ */
+export type ChainRule = 
+/**
+ * How deep the chain may go. `parentDepth` is the spawning run's own depth,
+ * so the child would sit at `parentDepth + 1`; the rule rejects once that
+ * would reach `maxDepth`. A `maxDepth` of 5 therefore permits depths 0
+ * through 4 — five runs deep counting the root.
+ */
+{
+    kind: "depth";
+    parentDepth: number;
+    maxDepth: number;
+}
+/**
+ * Total runs one chain may produce. Caps the spend of a chain that stays
+ * shallow but keeps fanning out, which a depth bound alone does not touch.
+ */
+ | {
+    kind: "chain_budget";
+    runsInChain: number;
+    maxRuns: number;
+}
+/**
+ * Minimum spacing between spawns from the same parent, which is what stops
+ * two runs ping-ponging work at each other. `msSinceLastSpawn` is `null` when
+ * this parent has not spawned before — always admitted.
+ */
+ | {
+    kind: "pair_cooldown";
+    msSinceLastSpawn: number | null;
+    cooldownMs: number;
+}
+/**
+ * A ceiling on concurrent runs for the whole tenant. Worth having alongside
+ * the chain rules: depth and chain budgets constrain one lineage, and neither
+ * stops someone starting a thousand independent ones.
+ */
+ | {
+    kind: "tenant_ceiling";
+    activeRuns: number;
+    maxActiveRuns: number;
+};
+export type ChildAdmission = {
+    admitted: true;
+} | {
+    admitted: false;
+    /** Which rule refused, for metrics and for branching. */
+    rule: ChainRule["kind"];
+    /**
+     * Could waiting change this answer?
+     *
+     * The four rules are not the same kind of refusal, and prose alone does
+     * not separate them: a cooldown clears on its own, a spent chain budget
+     * never does. Without this a model reads "refused" and has to guess
+     * between waiting and giving up — and guessing wrong either wastes the
+     * run on retries into the same wall or abandons work it could have done
+     * a moment later.
+     */
+    retryable: boolean;
+    /**
+     * Why, in prose, for the model to read as a tool error. Names the limit,
+     * the measurement, and what to do instead — a refusal that reports only
+     * the failure invites a retry into the identical wall.
+     */
+    reason: string;
+};
+/**
+ * Decide whether one more child run may be created.
+ *
+ * Evaluated in the order given, first refusal wins, so a host controls which
+ * reason the model sees when several apply. An empty rule list admits — this
+ * function bounds what it is given and claims nothing about what it is not.
+ *
+ * **Call before enqueuing, never after.** A chain that is bounded only once its
+ * runs are already queued is not bounded; it is billed.
+ *
+ * **This is the decision, not the claim.** A counted rule (`chain_budget`,
+ * `tenant_ceiling`) bounds only as tightly as the host's count is atomic with
+ * the create. Two spawners that read the same count both admit — two replicas,
+ * or two spawn calls in one assistant batch, which the tool loop fans out
+ * concurrently. If you need the bound to hold under concurrency, take a lock or
+ * use a conditional insert around count-then-create; this function cannot see
+ * the race and will not tell you about it.
+ *
+ * A non-finite number anywhere in a rule — the measurement or the limit —
+ * refuses rather than admits. Comparisons against `NaN` are always false, so
+ * the natural reading of every rule below would silently admit, turning a
+ * broken count or a misread config into an unbounded chain. That is the one
+ * failure this function exists to prevent, so it fails toward refusing.
+ */
+export declare function admitChildRun(rules: readonly ChainRule[]): ChildAdmission;
+/**
+ * What a poller should do next while waiting on a child run.
+ *
+ * `wait` is already clamped to whatever budget remains, so sleeping for it can
+ * never overshoot the deadline — the next call returns `expired` instead.
+ */
+export type PollStep = {
+    kind: "wait";
+    delayMs: number;
+} | {
+    kind: "expired";
+    waitedMs: number;
+};
+export interface PollScheduleOptions {
+    /** First delay. Clamped to at least `minDelayMs` and at most `maxDelayMs`. */
+    readonly initialDelayMs: number;
+    /** Ceiling the doubling backoff climbs to. */
+    readonly maxDelayMs: number;
+    /** Total wall-clock the poll may consume before giving up. */
+    readonly budgetMs: number;
+    /**
+     * Floor on any single delay, defaulting to 50ms — which is the real guard
+     * against an `initialDelayMs` of 0 turning the poll into a busy loop.
+     *
+     * Setting it explicitly *lowers* that guard: the hard floor is 1ms, so
+     * `minDelayMs: 0` yields 1ms rather than the default. That is deliberate — a
+     * host asking for a sub-50ms poll gets one — but it means passing 0 to mean
+     * "no floor" gives you the tightest loop this module allows, not the safest.
+     *
+     * If this exceeds `maxDelayMs`, the floor wins and the ceiling is raised to
+     * match: a delay below the floor would defeat the busy-loop guard, while one
+     * above the ceiling only polls less often.
+     */
+    readonly minDelayMs?: number;
+}
+export interface PollSchedule {
+    /**
+     * The next step, given how long the poll has been running. Elapsed time is an
+     * argument rather than something read from a clock, which keeps this pure and
+     * lets a test drive the whole backoff without waiting for any of it.
+     *
+     * A schedule carries the backoff state for **one** wait and advances on every
+     * call, so it is not shareable between concurrent waiters — build one per
+     * wait, which is cheap. Two schedules from identical options are fully
+     * independent.
+     */
+    next(elapsedMs: number): PollStep;
+}
+/**
+ * A doubling backoff bounded by a total budget.
+ *
+ * Polling a child run is the alternative to suspending the parent and letting
+ * completion wake it. It keeps the parent's transcript intact but holds its
+ * worker slot for the duration — so the budget belongs well under the parent's
+ * own deadline, or the parent dies waiting instead of reporting what it learned.
+ */
+export declare function createPollSchedule(options: PollScheduleOptions): PollSchedule;

package/run/children.js

@@ -0,0 +1,226 @@
+/**
+ * Child runs: lineage, admission, and waiting.
+ *
+ * A sub-agent is not a special kind of thing — it is **a run that another run
+ * asked for**. Everything the harness already gives a run applies to it
+ * unchanged: its own deadline, its own heartbeat, its own stats, its own route
+ * plan. What is genuinely new is the relationship between runs, and that is
+ * what this module owns:
+ *
+ *  - **Lineage** — where a run sits in the chain that produced it.
+ *  - **Admission** — whether the next child may be created at all.
+ *  - **Waiting** — how long to sleep before checking on a child again.
+ *
+ * All three are pure. The queue, the persistence, the counting, and the choice
+ * of bounds stay with the host: the harness decides, it does not measure. That
+ * split is deliberate — counting runs needs a database, and deciding whether a
+ * count is too high does not.
+ */
+/** The lineage of a run that nothing spawned — the origin of a new chain. */
+export function rootChain() {
+    return { depth: 0, rootRunId: null, parentRunId: null };
+}
+/**
+ * The lineage a child of `parentRunId` should carry.
+ *
+ * The root-id fallback is the part hosts get wrong: a depth-1 child must adopt
+ * its parent's *id* as the root (the parent's own `rootRunId` is null), while a
+ * depth-2 grandchild must adopt the root the parent already carries. Getting it
+ * backwards makes each generation start a fresh chain, which silently defeats
+ * every per-chain bound — the counts stay small because they count the wrong
+ * set.
+ */
+export function descendChain(parentRunId, 
+// Only what the arithmetic reads, so a host storing lineage as flat columns
+// can pass the two it has rather than assembling a whole `ChainRef` around a
+// field this never looks at.
+parent) {
+    return {
+        depth: parent.depth + 1,
+        rootRunId: parent.rootRunId ?? parentRunId,
+        parentRunId,
+    };
+}
+/**
+ * Decide whether one more child run may be created.
+ *
+ * Evaluated in the order given, first refusal wins, so a host controls which
+ * reason the model sees when several apply. An empty rule list admits — this
+ * function bounds what it is given and claims nothing about what it is not.
+ *
+ * **Call before enqueuing, never after.** A chain that is bounded only once its
+ * runs are already queued is not bounded; it is billed.
+ *
+ * **This is the decision, not the claim.** A counted rule (`chain_budget`,
+ * `tenant_ceiling`) bounds only as tightly as the host's count is atomic with
+ * the create. Two spawners that read the same count both admit — two replicas,
+ * or two spawn calls in one assistant batch, which the tool loop fans out
+ * concurrently. If you need the bound to hold under concurrency, take a lock or
+ * use a conditional insert around count-then-create; this function cannot see
+ * the race and will not tell you about it.
+ *
+ * A non-finite number anywhere in a rule — the measurement or the limit —
+ * refuses rather than admits. Comparisons against `NaN` are always false, so
+ * the natural reading of every rule below would silently admit, turning a
+ * broken count or a misread config into an unbounded chain. That is the one
+ * failure this function exists to prevent, so it fails toward refusing.
+ */
+export function admitChildRun(rules) {
+    for (const rule of rules) {
+        const refusal = evaluateRule(rule);
+        if (refusal !== null)
+            return refusal;
+    }
+    return { admitted: true };
+}
+function evaluateRule(rule) {
+    switch (rule.kind) {
+        case "depth": {
+            const broken = unmeasurable(rule, rule.parentDepth, "parentDepth") ??
+                unmeasurable(rule, rule.maxDepth, "maxDepth");
+            if (broken)
+                return broken;
+            const childDepth = rule.parentDepth + 1;
+            return childDepth >= rule.maxDepth
+                ? refuse(rule, false, `chain depth limit reached (${childDepth}/${rule.maxDepth}) — ` +
+                    `this is as deep as the chain may go, so do the work in this run ` +
+                    `instead of spawning`)
+                : null;
+        }
+        case "chain_budget": {
+            const broken = unmeasurable(rule, rule.runsInChain, "runsInChain") ??
+                unmeasurable(rule, rule.maxRuns, "maxRuns");
+            if (broken)
+                return broken;
+            return rule.runsInChain >= rule.maxRuns
+                ? refuse(rule, false, `chain run budget exhausted (${rule.runsInChain}/${rule.maxRuns}) — ` +
+                    `the budget is spent for this whole chain and does not refill, so ` +
+                    `do the work in this run instead of spawning`)
+                : null;
+        }
+        case "pair_cooldown": {
+            if (rule.msSinceLastSpawn === null)
+                return null;
+            const broken = unmeasurable(rule, rule.msSinceLastSpawn, "msSinceLastSpawn") ??
+                unmeasurable(rule, rule.cooldownMs, "cooldownMs");
+            if (broken)
+                return broken;
+            return rule.msSinceLastSpawn < rule.cooldownMs
+                ? refuse(rule, true, `spawn cooldown active (${rule.msSinceLastSpawn}ms since the last ` +
+                    `spawn, ${rule.cooldownMs}ms required) — retry in ` +
+                    `${rule.cooldownMs - rule.msSinceLastSpawn}ms, or do the work in ` +
+                    `this run`)
+                : null;
+        }
+        case "tenant_ceiling": {
+            const broken = unmeasurable(rule, rule.activeRuns, "activeRuns") ??
+                unmeasurable(rule, rule.maxActiveRuns, "maxActiveRuns");
+            if (broken)
+                return broken;
+            return rule.activeRuns >= rule.maxActiveRuns
+                ? refuse(rule, true, `concurrent run ceiling reached (${rule.activeRuns}/` +
+                    `${rule.maxActiveRuns}) — this clears as other runs finish, so ` +
+                    `retry shortly or do the work in this run`)
+                : null;
+        }
+        default: {
+            const _exhaustive = rule;
+            throw new Error(`Unhandled chain rule: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+const refuse = (rule, retryable, reason) => ({
+    admitted: false,
+    rule: rule.kind,
+    retryable,
+    reason,
+});
+/**
+ * Every number a rule carries must be a finite, non-negative count — the
+ * measurement AND the limit.
+ *
+ * The limit matters as much as the count and for the same reason: every
+ * comparison below is `<` or `>=`, both false against `NaN`, so a `maxDepth`
+ * that arrived as `NaN` (a bad config read, an `undefined` coerced by
+ * arithmetic) leaves the chain unbounded with nothing to show for it.
+ *
+ * Negatives are rejected on the same grounds rather than as a style rule. No
+ * depth, count, or elapsed span can legitimately be below zero, so a negative
+ * means the host's bookkeeping is wrong — and the result is not a *stricter*
+ * bound but no bound at all: `runsInChain: -1` against `maxRuns: 10` admits,
+ * and keeps admitting. To express "no cooldown", omit the rule rather than
+ * passing a negative one.
+ *
+ * A rule that cannot be evaluated refuses, because "we could not check" and
+ * "it is fine" are not the same answer.
+ */
+const unmeasurable = (rule, value, field) => Number.isFinite(value) && value >= 0
+    ? null
+    : // A noun phrase, like every other reason, so it still reads correctly
+        // when a host prefixes it ("Sub-agent chain bound unreadable…"). A verb
+        // phrase here would invert the actor and read as though the child were
+        // the one refusing.
+        refuse(rule, false, `chain bound unreadable (${field} is ${value}) — a misconfiguration, ` +
+            `not a limit that clears, so do the work in this run rather than ` +
+            `retrying`);
+function requireFinite(value, field) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`createPollSchedule: ${field} must be a finite number, got ${value}.`);
+    }
+}
+/**
+ * A doubling backoff bounded by a total budget.
+ *
+ * Polling a child run is the alternative to suspending the parent and letting
+ * completion wake it. It keeps the parent's transcript intact but holds its
+ * worker slot for the duration — so the budget belongs well under the parent's
+ * own deadline, or the parent dies waiting instead of reporting what it learned.
+ */
+export function createPollSchedule(options) {
+    // Rejected at construction, not clamped. `Math.min`/`Math.max` propagate
+    // `NaN`, so one non-finite option reaches the caller as `sleep(NaN)` — which
+    // fires immediately and turns the poll into a busy loop. A non-finite
+    // `budgetMs` is worse still: `NaN <= 0` is false, so it also never expires.
+    //
+    // Unlike a bad measurement in `admitChildRun`, which has a safe answer
+    // (refuse), a bad *option* here has none — there is no way to guess the
+    // budget that was meant. Substituting a default would hide the caller's bug
+    // behind a poll nobody configured, so this throws at the call that made the
+    // mistake rather than inside the loop that inherits it.
+    requireFinite(options.initialDelayMs, "initialDelayMs");
+    requireFinite(options.maxDelayMs, "maxDelayMs");
+    requireFinite(options.budgetMs, "budgetMs");
+    if (options.minDelayMs !== undefined) {
+        requireFinite(options.minDelayMs, "minDelayMs");
+    }
+    const minDelayMs = Math.max(1, options.minDelayMs ?? 50);
+    const maxDelayMs = Math.max(minDelayMs, options.maxDelayMs);
+    // Snapshot, not read live: the guards above run once, so a host that mutates
+    // its options object afterwards would otherwise walk a `NaN` budget straight
+    // past them on the next call.
+    const budgetMs = options.budgetMs;
+    let delayMs = Math.min(Math.max(options.initialDelayMs, minDelayMs), maxDelayMs);
+    return {
+        next(elapsedMs) {
+            // The options are validated at construction; this is the one number that
+            // arrives per call, and it fails the same way — `NaN <= 0` is false, so a
+            // bad elapsed never expires, and it poisons the delay into `sleep(NaN)`.
+            // A host computing `Date.now() - new Date(row.started_at).getTime()`
+            // against an unparsed timestamp string produces exactly that.
+            //
+            // Expires rather than throws: unlike a bad option there IS a safe reading
+            // here — we cannot tell how long this has been running, so stop waiting.
+            if (!Number.isFinite(elapsedMs)) {
+                return { kind: "expired", waitedMs: budgetMs };
+            }
+            const remainingMs = budgetMs - elapsedMs;
+            if (remainingMs <= 0)
+                return { kind: "expired", waitedMs: elapsedMs };
+            // Clamped to what is left, so the caller cannot sleep past its own
+            // budget and report a timeout later than the one it promised.
+            const step = Math.min(delayMs, remainingMs);
+            delayMs = Math.min(delayMs * 2, maxDelayMs);
+            return { kind: "wait", delayMs: step };
+        },
+    };
+}

package/run/harness.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Cross-cutting run mechanics for an agent loop:
+ *
+ *   1. a **wall-clock deadline** that aborts a hung run (thread its signal into
+ *      every model and tool call, and re-check at the top of each iteration);
+ *   2. a **coalesced progress heartbeat** for hosts that record liveness;
+ *   3. a **failure classifier** mapping a thrown run to a terminal status
+ *      (`timed_out` vs `failed`).
+ *
+ * Any driver of the loop needs all three, and reimplementing them per driver
+ * is how one ends up unbounded: a loop whose abort signal never fires holds its
+ * worker slot until an external reaper notices, which is a stall the user sees
+ * as an agent that never answers.
+ *
+ * This module owns no persistence and makes no model calls — it is pure
+ * mechanics, so a small consumer can use it without pulling in a loop's
+ * transitive graph.
+ */
+/** Thrown by {@link RunDeadline.throwIfTimedOut} once the wall-clock budget is
+ *  exhausted. Distinct from a caller-driven cancellation so callers can map it
+ *  to a `timed_out` terminal status (or simply read {@link RunDeadline.timedOut}). */
+export declare class RunTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, label: string);
+}
+/**
+ * Call `unref()` on a timer when the runtime exposes it (Node/Bun) so a
+ * forgotten clear can't hold the event loop open; a no-op under the DOM `number`
+ * timer type. Feature-detected rather than `as`-cast to keep type safety.
+ */
+export declare function unrefTimer(timer: ReturnType<typeof setTimeout>): void;
+/**
+ * A wall-clock budget for a single run. Backed by an `AbortController` that
+ * fires after `timeoutMs`; `signal` is threaded into LLM/tool calls so an
+ * in-flight upstream request is actually torn down on timeout (not merely
+ * abandoned). `timedOut` reflects *this* deadline firing only — it stays false
+ * when a combined external (cancellation) signal aborts — so it is a reliable
+ * basis for classifying a `timed_out` outcome regardless of which error shape
+ * surfaced (a `RunTimeoutError` from {@link throwIfTimedOut} or an `AbortError`
+ * from a torn-down `callLLM` stream).
+ */
+export interface RunDeadline {
+    /** The deadline's own abort signal. Combine with a cancellation signal via
+     *  {@link withExternal} before handing to `callLLM`. */
+    readonly signal: AbortSignal;
+    /** True once this deadline's timer has fired. Unaffected by external signals. */
+    readonly timedOut: boolean;
+    /** Throw {@link RunTimeoutError} if the budget is exhausted; no-op otherwise.
+     *  Call at the top of each loop iteration. */
+    throwIfTimedOut(): void;
+    /** Combine this deadline with an optional external signal (e.g. a DB-backed
+     *  cancellation controller). Returns the deadline's own signal when no
+     *  external signal is given. */
+    withExternal(external?: AbortSignal | null): AbortSignal;
+    /** Clear the underlying timer. Idempotent; call in a `finally`. */
+    dispose(): void;
+}
+export declare function createRunDeadline(opts: {
+    timeoutMs: number;
+    label?: string;
+}): RunDeadline;
+/**
+ * Classify a run that ended by throwing into its terminal status. A run whose
+ * deadline fired — or whose error is a {@link RunTimeoutError} — is `timed_out`;
+ * anything else is `failed`. Checking the error too makes the result robust to
+ * the surfaced shape (an `AbortError` from a torn-down stream leaves
+ * `deadline.timedOut` true; a `RunTimeoutError` thrown between iterations is
+ * caught directly even if a combined-signal edge left `timedOut` unread).
+ *
+ * Caller-driven cancellation is a distinct outcome and must be handled *before*
+ * calling this (the executor special-cases `AgentRunCancelledError`); the
+ * one-off/onboarding path has no cancellation, so this split is complete there.
+ */
+export declare function classifyRunFailure(deadline: RunDeadline, error?: unknown): "timed_out" | "failed";
+/** A progress heartbeat that collapses bursts of calls into at most one flush
+ *  per `coalesceMs` window (a `force` beat always flushes). */
+export interface CoalescedHeartbeat {
+    beat(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Build a coalesced heartbeat. A run with N concurrent tool calls would
+ * otherwise fire N near-simultaneous run-row UPDATEs; coalescing collapses
+ * them to one per window while a `force: true` beat (used at the end of each
+ * iteration) guarantees a bump within the reaper's stale threshold. `flush`
+ * owns the actual write; a flush failure is reported to `onError` and
+ * swallowed so a transient DB hiccup never aborts the run.
+ */
+export declare function createCoalescedHeartbeat(opts: {
+    coalesceMs: number;
+    flush: () => Promise<void>;
+    onError?: (err: unknown) => void;
+}): CoalescedHeartbeat;

package/run/harness.js

@@ -0,0 +1,140 @@
+/**
+ * Cross-cutting run mechanics for an agent loop:
+ *
+ *   1. a **wall-clock deadline** that aborts a hung run (thread its signal into
+ *      every model and tool call, and re-check at the top of each iteration);
+ *   2. a **coalesced progress heartbeat** for hosts that record liveness;
+ *   3. a **failure classifier** mapping a thrown run to a terminal status
+ *      (`timed_out` vs `failed`).
+ *
+ * Any driver of the loop needs all three, and reimplementing them per driver
+ * is how one ends up unbounded: a loop whose abort signal never fires holds its
+ * worker slot until an external reaper notices, which is a stall the user sees
+ * as an agent that never answers.
+ *
+ * This module owns no persistence and makes no model calls — it is pure
+ * mechanics, so a small consumer can use it without pulling in a loop's
+ * transitive graph.
+ */
+/** Thrown by {@link RunDeadline.throwIfTimedOut} once the wall-clock budget is
+ *  exhausted. Distinct from a caller-driven cancellation so callers can map it
+ *  to a `timed_out` terminal status (or simply read {@link RunDeadline.timedOut}). */
+export class RunTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs, label) {
+        super(`${label} exceeded ${formatDuration(timeoutMs)} timeout`);
+        this.timeoutMs = timeoutMs;
+        this.name = "RunTimeoutError";
+    }
+}
+function formatDuration(ms) {
+    if (ms % 60_000 === 0) {
+        const m = ms / 60_000;
+        return `${m} ${m === 1 ? "minute" : "minutes"}`;
+    }
+    // Floor at 1 so a sub-second budget (e.g. a 50ms test deadline) never reads
+    // "0 seconds".
+    const s = Math.max(1, Math.round(ms / 1000));
+    return `${s} ${s === 1 ? "second" : "seconds"}`;
+}
+/**
+ * Call `unref()` on a timer when the runtime exposes it (Node/Bun) so a
+ * forgotten clear can't hold the event loop open; a no-op under the DOM `number`
+ * timer type. Feature-detected rather than `as`-cast to keep type safety.
+ */
+export function unrefTimer(timer) {
+    if (typeof timer === "object" &&
+        timer !== null &&
+        typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+export function createRunDeadline(opts) {
+    const label = opts.label ?? "agent run";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    // Unref so a forgotten dispose() (e.g. in a test) can't hold the event loop
+    // open; the timer is always cleared on the real run path.
+    unrefTimer(timer);
+    return {
+        signal: controller.signal,
+        get timedOut() {
+            return controller.signal.aborted;
+        },
+        throwIfTimedOut() {
+            if (controller.signal.aborted) {
+                throw new RunTimeoutError(opts.timeoutMs, label);
+            }
+        },
+        withExternal(external) {
+            if (!external)
+                return controller.signal;
+            return AbortSignal.any([external, controller.signal]);
+        },
+        dispose() {
+            clearTimeout(timer);
+        },
+    };
+}
+/**
+ * Classify a run that ended by throwing into its terminal status. A run whose
+ * deadline fired — or whose error is a {@link RunTimeoutError} — is `timed_out`;
+ * anything else is `failed`. Checking the error too makes the result robust to
+ * the surfaced shape (an `AbortError` from a torn-down stream leaves
+ * `deadline.timedOut` true; a `RunTimeoutError` thrown between iterations is
+ * caught directly even if a combined-signal edge left `timedOut` unread).
+ *
+ * Caller-driven cancellation is a distinct outcome and must be handled *before*
+ * calling this (the executor special-cases `AgentRunCancelledError`); the
+ * one-off/onboarding path has no cancellation, so this split is complete there.
+ */
+export function classifyRunFailure(deadline, error) {
+    if (deadline.timedOut || error instanceof RunTimeoutError)
+        return "timed_out";
+    return "failed";
+}
+/**
+ * Build a coalesced heartbeat. A run with N concurrent tool calls would
+ * otherwise fire N near-simultaneous run-row UPDATEs; coalescing collapses
+ * them to one per window while a `force: true` beat (used at the end of each
+ * iteration) guarantees a bump within the reaper's stale threshold. `flush`
+ * owns the actual write; a flush failure is reported to `onError` and
+ * swallowed so a transient DB hiccup never aborts the run.
+ */
+export function createCoalescedHeartbeat(opts) {
+    let lastAt = 0;
+    let inFlight = null;
+    let queued = false;
+    // Drain queued flushes ONE AT A TIME, so a coalesced background beat and a
+    // forced end-of-iteration beat can never run `flush()` concurrently — two
+    // overlapping DB writes could otherwise resolve out of order and let an older
+    // token/cost snapshot overwrite a newer one. `flush` reads live state at call
+    // time, so each drained flush still writes the latest values, and a request
+    // enqueued during the prior await is picked up on the next loop turn.
+    const drain = async () => {
+        while (queued) {
+            queued = false;
+            try {
+                await opts.flush();
+            }
+            catch (err) {
+                opts.onError?.(err);
+            }
+        }
+        inFlight = null;
+    };
+    return {
+        async beat(o) {
+            const now = Date.now();
+            if (!o?.force && now - lastAt < opts.coalesceMs)
+                return;
+            lastAt = now;
+            queued = true;
+            if (!inFlight)
+                inFlight = drain();
+            // Await the drain so a forced beat returns only after the latest write has
+            // landed — the reaper-liveness / token-flush guarantee callers rely on.
+            await inFlight;
+        },
+    };
+}

package/run/index.d.ts

@@ -0,0 +1,3 @@
+export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, type RunDeadline, type CoalescedHeartbeat, } from "./harness.js";
+export { runToolCallsPooledByTool } from "./tool-batch.js";
+export { rootChain, descendChain, admitChildRun, createPollSchedule, type ChainRef, type ChainRule, type ChildAdmission, type PollStep, type PollSchedule, type PollScheduleOptions, } from "./children.js";

package/run/index.js

@@ -0,0 +1,3 @@
+export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, } from "./harness.js";
+export { runToolCallsPooledByTool } from "./tool-batch.js";
+export { rootChain, descendChain, admitChildRun, createPollSchedule, } from "./children.js";