@juno-ai/bind 3.0.0 → 5.0.0

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/index.d.ts

@@ -1,2 +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

@@ -1,2 +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";