@juno-ai/bind 3.0.0 → 5.0.0

package/routing/attempt-errors.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Classification: a thrown transport error → the {@link InferenceAttemptError}
+ * taxonomy the executor routes on.
+ *
+ * `errors.ts` owns what the router *does* with a classified failure
+ * (`failureDisposition`) and `executor.ts` applies it. This module is the step
+ * before both — the one every host was writing itself. The PRD's split is
+ * "transports classify facts; the executor decides," and shipping only the
+ * decider left each consumer to hand-roll the classifier, where the mistakes
+ * are not obvious: misfile a moderation refusal as a credential failure and the
+ * circuit breaker opens the endpoint for everyone sharing that breaker key —
+ * which, for a host that does not set `credentialScope`, is every tenant on the
+ * process.
+ *
+ * The host keeps the two things that are genuinely its own — recognizing its
+ * error class ({@link AttemptClassification.asTransportFailure}) and any
+ * provider-specific status reading ({@link AttemptClassification.categorizeStatus}).
+ * Neither can live here: the first is a class this package must not import, and
+ * the second is provider-registry knowledge.
+ */
+import type { AttemptTarget, HttpFailureCategory, InferenceAttemptError } from "./errors.js";
+import type { ProviderId } from "./canonical-model.js";
+import type { CompletionDefectKind } from "../completion/defects.js";
+/**
+ * What a transport observed, in the vocabulary the taxonomy needs. A host maps
+ * its own error class onto this once.
+ *
+ * `"api"` is the catch-all for a response the provider rejected with a status
+ * the transport did not interpret further; it is the only kind whose routing
+ * behavior depends on {@link TransportFailure.statusCode}.
+ */
+export type TransportFailureKind = CompletionDefectKind | "server_error" | "rate_limit" | "no_credits" | "api" | "network";
+export interface TransportFailure {
+    readonly kind: TransportFailureKind;
+    /** HTTP status when the failure carried one; null for transport-level faults. */
+    readonly statusCode: number | null;
+    /** Parsed `Retry-After`, which bounds-extends the breaker cooldown. */
+    readonly retryAfterMs: number | null;
+}
+export interface AttemptClassification {
+    /**
+     * Recognize the host's own transport-error class and describe it. Return
+     * `null` for anything that is not one — those propagate as a client error
+     * rather than burning the plan (see {@link classifyAttemptError}).
+     */
+    readonly asTransportFailure: (error: unknown) => TransportFailure | null;
+    /**
+     * Provider-specific status → category, consulted before the neutral
+     * {@link categorizeHttpStatus}. Return `null` to fall through to it.
+     *
+     * This exists because status codes are not portable across providers: one
+     * gateway answers 403 for moderation-flagged *input* (request-shaped — a
+     * different provider may accept it, and the endpoint is healthy), where the
+     * neutral mapping reads 403 as a credential failure and opens the circuit
+     * immediately.
+     */
+    readonly categorizeStatus?: (statusCode: number, providerId: ProviderId) => HttpFailureCategory | null;
+    /**
+     * Recognize a caller-cancellation. Defaults to {@link isAbortByName} —
+     * `error.name === "AbortError"`, which is what `AbortSignal` and `fetch`
+     * produce.
+     *
+     * **Override this if your SDK wraps aborts in its own class.** The one that
+     * bites: `openai`'s `APIUserAbortError` extends its `APIError` and never sets
+     * `name`, so `error.name` is the inherited `"Error"` — it matches neither the
+     * default nor an `instanceof` check you didn't write. Left unrecognized, a
+     * deliberate cancellation classifies as a propagating `client_error`: it
+     * still stops the plan, but it is attributed as a fault rather than a
+     * cancellation, which pollutes failure telemetry and any breaker or retry
+     * accounting keyed off it.
+     *
+     * ```ts
+     * isAbort: (e) => e instanceof OpenAI.APIUserAbortError || isAbortByName(e),
+     * ```
+     */
+    readonly isAbort?: (error: unknown) => boolean;
+}
+/**
+ * The default abort test: the `name` an `AbortSignal`-driven `fetch` rejection
+ * carries. Exported so a host overriding {@link AttemptClassification.isAbort}
+ * can widen it rather than replace it.
+ */
+export declare function isAbortByName(error: unknown): boolean;
+/**
+ * Map a thrown error onto the attempt-error taxonomy. The original error rides
+ * in `cause` and is re-thrown verbatim if the plan exhausts, so a host's error
+ * classes and messages survive routing untouched.
+ *
+ * Order is deliberate. An abort is checked first: a cancelled call must never
+ * be reclassified as a provider fault, whatever else is true of it. Anything
+ * the host does not recognize as a transport failure is classified
+ * `client_error` — which propagates rather than traverses — because an error
+ * that escaped the transport without becoming one of its own is a programming
+ * defect (a `TypeError`, a validation throw), and burning every provider and
+ * the fallback model retrying a bug wastes a whole plan to arrive at the same
+ * exception.
+ */
+export declare function classifyAttemptError(error: unknown, target: AttemptTarget, classification: AttemptClassification): InferenceAttemptError;
+/**
+ * Parse a `Retry-After` response header into milliseconds, per RFC 9110: either
+ * delta-seconds or an HTTP-date. Returns `null` when absent or unparseable —
+ * the breaker then falls back to its own cooldown, so a header this cannot read
+ * degrades to the default rather than to no cooldown at all.
+ *
+ * **This value is attacker-influenceable and is not bounded here.** It comes
+ * from whatever answered the request — the provider, a gateway, a proxy — and
+ * RFC 9110 puts no ceiling on it, so a hostile or malfunctioning upstream can
+ * ask for a delay of years. Clamp before using it as a delay:
+ * {@link createCircuitBreaker} already does (`maxCooldownMs`), but a host that
+ * sleeps on this directly must impose its own bound, or one bad response header
+ * parks an endpoint indefinitely.
+ *
+ * `headers` is deliberately `unknown`: SDKs hand back a `Headers`, a plain
+ * object, or a `Map` depending on version and runtime. Anything with a `get`
+ * method is asked for the header (covering `Headers` and `Map` without naming
+ * either global, which keeps this portable to runtimes that ship neither);
+ * a plain object is read case-insensitively for the two spellings that occur
+ * in practice.
+ *
+ * @param now Injectable clock for the HTTP-date branch; defaults to `Date.now`.
+ */
+export declare function retryAfterMsFromHeaders(headers: unknown, now?: () => number): number | null;

package/routing/attempt-errors.js

@@ -0,0 +1,176 @@
+/**
+ * Classification: a thrown transport error → the {@link InferenceAttemptError}
+ * taxonomy the executor routes on.
+ *
+ * `errors.ts` owns what the router *does* with a classified failure
+ * (`failureDisposition`) and `executor.ts` applies it. This module is the step
+ * before both — the one every host was writing itself. The PRD's split is
+ * "transports classify facts; the executor decides," and shipping only the
+ * decider left each consumer to hand-roll the classifier, where the mistakes
+ * are not obvious: misfile a moderation refusal as a credential failure and the
+ * circuit breaker opens the endpoint for everyone sharing that breaker key —
+ * which, for a host that does not set `credentialScope`, is every tenant on the
+ * process.
+ *
+ * The host keeps the two things that are genuinely its own — recognizing its
+ * error class ({@link AttemptClassification.asTransportFailure}) and any
+ * provider-specific status reading ({@link AttemptClassification.categorizeStatus}).
+ * Neither can live here: the first is a class this package must not import, and
+ * the second is provider-registry knowledge.
+ */
+import { categorizeHttpStatus } from "./errors.js";
+/**
+ * The default abort test: the `name` an `AbortSignal`-driven `fetch` rejection
+ * carries. Exported so a host overriding {@link AttemptClassification.isAbort}
+ * can widen it rather than replace it.
+ */
+export function isAbortByName(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+/**
+ * Map a thrown error onto the attempt-error taxonomy. The original error rides
+ * in `cause` and is re-thrown verbatim if the plan exhausts, so a host's error
+ * classes and messages survive routing untouched.
+ *
+ * Order is deliberate. An abort is checked first: a cancelled call must never
+ * be reclassified as a provider fault, whatever else is true of it. Anything
+ * the host does not recognize as a transport failure is classified
+ * `client_error` — which propagates rather than traverses — because an error
+ * that escaped the transport without becoming one of its own is a programming
+ * defect (a `TypeError`, a validation throw), and burning every provider and
+ * the fallback model retrying a bug wastes a whole plan to arrive at the same
+ * exception.
+ */
+export function classifyAttemptError(error, target, classification) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const isAbort = classification.isAbort ?? isAbortByName;
+    if (isAbort(error)) {
+        return { kind: "aborted", target, cause };
+    }
+    const failure = classification.asTransportFailure(error);
+    if (failure === null) {
+        return {
+            kind: "http",
+            category: "client_error",
+            statusCode: 0,
+            retryAfterMs: null,
+            target,
+            cause,
+        };
+    }
+    switch (failure.kind) {
+        case "empty_completion":
+        case "truncated_tool_call":
+            return { kind: "completion_defect", defect: failure.kind, target, cause };
+        case "network":
+            return { kind: "network", target, cause };
+        case "rate_limit":
+            return httpError("rate_limit", failure.statusCode ?? 429, failure, target, cause);
+        case "no_credits":
+            return httpError("credits", failure.statusCode ?? 402, failure, target, cause);
+        case "server_error":
+            return httpError("server_error", failure.statusCode ?? 500, failure, target, cause);
+        case "api": {
+            const statusCode = failure.statusCode;
+            // No status at all means the transport could not attribute the rejection
+            // to the endpoint; propagate rather than traverse.
+            const category = statusCode === null
+                ? "client_error"
+                : (classification.categorizeStatus?.(statusCode, target.providerId) ??
+                    categorizeHttpStatus(statusCode));
+            return httpError(category, statusCode ?? 0, failure, target, cause);
+        }
+        default: {
+            const _exhaustive = failure.kind;
+            throw new Error(`unknown transport failure kind: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+function httpError(category, statusCode, failure, target, cause) {
+    return {
+        kind: "http",
+        category,
+        statusCode,
+        retryAfterMs: failure.retryAfterMs,
+        target,
+        cause,
+    };
+}
+/**
+ * Parse a `Retry-After` response header into milliseconds, per RFC 9110: either
+ * delta-seconds or an HTTP-date. Returns `null` when absent or unparseable —
+ * the breaker then falls back to its own cooldown, so a header this cannot read
+ * degrades to the default rather than to no cooldown at all.
+ *
+ * **This value is attacker-influenceable and is not bounded here.** It comes
+ * from whatever answered the request — the provider, a gateway, a proxy — and
+ * RFC 9110 puts no ceiling on it, so a hostile or malfunctioning upstream can
+ * ask for a delay of years. Clamp before using it as a delay:
+ * {@link createCircuitBreaker} already does (`maxCooldownMs`), but a host that
+ * sleeps on this directly must impose its own bound, or one bad response header
+ * parks an endpoint indefinitely.
+ *
+ * `headers` is deliberately `unknown`: SDKs hand back a `Headers`, a plain
+ * object, or a `Map` depending on version and runtime. Anything with a `get`
+ * method is asked for the header (covering `Headers` and `Map` without naming
+ * either global, which keeps this portable to runtimes that ship neither);
+ * a plain object is read case-insensitively for the two spellings that occur
+ * in practice.
+ *
+ * @param now Injectable clock for the HTTP-date branch; defaults to `Date.now`.
+ */
+export function retryAfterMsFromHeaders(headers, now = Date.now) {
+    const raw = rawRetryAfter(headers);
+    if (raw === null || raw === "")
+        return null;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds)) {
+        // A negative delta is malformed, and the date branch below would not
+        // reliably reject a bare "-5" either. Reject here instead.
+        if (seconds < 0)
+            return null;
+        // `1e308` is finite but overflows to Infinity once scaled to ms, and a
+        // non-finite delay is the one value that makes a timer fire immediately
+        // rather than never — the same trap `requirePositiveMs` guards in the
+        // watchdog. Refuse it rather than hand a caller a poisoned number.
+        const ms = Math.round(seconds * 1000);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    const dateMs = Date.parse(raw);
+    if (Number.isFinite(dateMs))
+        return Math.max(0, dateMs - now());
+    return null;
+}
+function rawRetryAfter(headers) {
+    if (typeof headers !== "object" || headers === null)
+        return null;
+    const getter = headers.get;
+    if (typeof getter === "function") {
+        // The getter belongs to the caller's object, so it is arbitrary code. This
+        // runs inside a host's `catch` while classifying a failure; letting a throw
+        // escape would replace the real provider error with this one and lose the
+        // classification entirely.
+        let value;
+        try {
+            value = getter.call(headers, "retry-after");
+        }
+        catch {
+            return null;
+        }
+        if (typeof value === "string")
+            return value;
+        // A `Map<string, number>` is as plausible as a `Map<string, string>`; the
+        // plain-object branch below accepts a number, so this one must too or the
+        // same header is read from one container and dropped from the other.
+        if (typeof value === "number")
+            return String(value);
+        return null;
+    }
+    const record = headers;
+    const value = record["retry-after"] ?? record["Retry-After"];
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    return null;
+}

package/routing/executor.js

@@ -42,7 +42,22 @@ export async function executeRoutePlan(options) {
                     endpointAttempt,
                 });
                 attemptCount += 1;
-                const outcome = await options.attempt(candidate, cursor);
+                // `attempt` is host code and is expected to resolve to an outcome, not
+                // throw — but if it does throw (a bug in its own classification, a
+                // host-supplied port raising), the throw must not carry a half-open
+                // probe out of the loop with it. The probe slot would stay occupied for
+                // the process's lifetime and every later call for this endpoint would
+                // be refused admission, silently, with no failure recorded to ever
+                // reopen it.
+                let outcome;
+                try {
+                    outcome = await options.attempt(candidate, cursor);
+                }
+                catch (error) {
+                    if (halfOpenProbe)
+                        breaker?.releaseProbe(breakerKey);
+                    throw error;
+                }
                 if (outcome.kind === "success") {
                     breaker?.recordSuccess(breakerKey);
                     return {

package/routing/index.d.ts

@@ -7,5 +7,6 @@ export { buildRoutePlanWithConfigDegradation, type DegradedStage, type DegradedP
 export { computeConfiguredRatesCostCents, type BillingBasisUsage, type BillingBasisResult, } from "./billing-basis.js";
 export { fallbackKindOfCursor } from "./executor.js";
 export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, type RouteAttemptCursor, type AttemptTarget, type HttpFailureCategory, type InferenceAttemptError, type FailureDisposition, type BreakerEffect, } from "./errors.js";
+export { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, type AttemptClassification, type TransportFailure, type TransportFailureKind, } from "./attempt-errors.js";
 export { createCircuitBreaker, type BreakerKey, type CircuitBreakerOptions, type EndpointAdmission, type RecordFailureOptions, type RouteCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, type AttemptOutcome, type AttemptFn, type FallbackKind, type ExecutePlanOptions, type RouteExecutionResult, } from "./executor.js";

package/routing/index.js

@@ -7,5 +7,6 @@ export { buildRoutePlanWithConfigDegradation, } from "./plan-degradation.js";
 export { computeConfiguredRatesCostCents, } from "./billing-basis.js";
 export { fallbackKindOfCursor } from "./executor.js";
 export { failureDisposition, categorizeHttpStatus, isRetriableAttemptError, } from "./errors.js";
+export { classifyAttemptError, retryAfterMsFromHeaders, isAbortByName, } from "./attempt-errors.js";
 export { createCircuitBreaker, } from "./circuit-breaker.js";
 export { executeRoutePlan, } from "./executor.js";

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;