@juno-ai/bind 4.0.0 → 6.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

@@ -86,6 +86,26 @@ export type ChainRule =
     msSinceLastSpawn: number | null;
     cooldownMs: number;
 }
+/**
+ * Whether this parent→child pair has *already* run, at all, within whatever
+ * scope the host measured over. The stronger sibling of
+ * `pair_cooldown`: a cooldown lets a pair repeat once enough time passes,
+ * while this permits the pair exactly once and never again.
+ *
+ * Reach for it where a repeat is not slow but wrong — two agents that answer
+ * each other are a loop whose every hop looks individually reasonable, and a
+ * time-based bound only makes such a loop cheaper per hour rather than
+ * ending it.
+ *
+ * The scope is the host's to choose and is deliberately not modelled here:
+ * "already paired in this chain" and "already paired in this conversation"
+ * are the same rule over different measurements, and naming either one would
+ * put a product's containment vocabulary into the harness.
+ */
+ | {
+    kind: "pair_seen";
+    alreadyPaired: boolean;
+}
 /**
  * A ceiling on concurrent runs for the whole tenant. Worth having alongside
  * the chain rules: depth and chain budgets constrain one lineage, and neither
@@ -95,6 +115,26 @@ export type ChainRule =
     kind: "tenant_ceiling";
     activeRuns: number;
     maxActiveRuns: number;
+}
+/**
+ * How many runs a tenant may *start* within a rolling window, as opposed to
+ * how many may be in flight at once (`tenant_ceiling`).
+ *
+ * The two bound different abuses and neither implies the other. A ceiling
+ * caps concurrency, so a caller that starts and finishes runs quickly slips
+ * under it indefinitely — a message flood, or one fan-out across a large
+ * group, is exactly that shape. A rate caps total starts, so it bounds spend
+ * where the ceiling bounds load.
+ *
+ * `windowMs` is carried only so the refusal can say how long the wait is;
+ * the rule does not roll the window itself. The host measures over whatever
+ * window it chose and passes both.
+ */
+ | {
+    kind: "tenant_rate";
+    runsInWindow: number;
+    maxRuns: number;
+    windowMs: number;
 };
 export type ChildAdmission = {
     admitted: true;
@@ -105,9 +145,9 @@ export type ChildAdmission = {
     /**
      * 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
+     * The rules are not all the same kind of refusal, and prose alone does
+     * not separate them: a cooldown or a rolling window clears on its own, a
+     * spent chain budget or a repeated pair 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.
@@ -127,6 +167,18 @@ export type ChildAdmission = {
  * 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.
  *
+ * **When a measurement fails, omit the rule — do not pass a sentinel.** The
+ * two failure postures here answer different questions and are easy to
+ * conflate. A rule whose number arrived broken (`NaN`, negative) refuses,
+ * because a nonsense count is not evidence of safety. A rule you could not
+ * measure at all — the count query threw, the store was unreachable — is
+ * absent, and absence admits. That is a deliberate seam, not an oversight:
+ * whether a transient infrastructure failure should stop all work or let it
+ * through is an availability judgement about a specific product, and this
+ * function has no standing to make it. Decide it at the call site, in a
+ * `catch`, by choosing whether to append the rule. Passing `NaN` or `-1` to
+ * mean "unknown" inverts the answer you almost certainly want.
+ *
  * **Call before enqueuing, never after.** A chain that is bounded only once its
  * runs are already queued is not bounded; it is billed.
  *

package/run/children.js

@@ -48,6 +48,18 @@ parent) {
  * 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.
  *
+ * **When a measurement fails, omit the rule — do not pass a sentinel.** The
+ * two failure postures here answer different questions and are easy to
+ * conflate. A rule whose number arrived broken (`NaN`, negative) refuses,
+ * because a nonsense count is not evidence of safety. A rule you could not
+ * measure at all — the count query threw, the store was unreachable — is
+ * absent, and absence admits. That is a deliberate seam, not an oversight:
+ * whether a transient infrastructure failure should stop all work or let it
+ * through is an availability judgement about a specific product, and this
+ * function has no standing to make it. Decide it at the call site, in a
+ * `catch`, by choosing whether to append the rule. Passing `NaN` or `-1` to
+ * mean "unknown" inverts the answer you almost certainly want.
+ *
  * **Call before enqueuing, never after.** A chain that is bounded only once its
  * runs are already queued is not bounded; it is billed.
  *
@@ -83,8 +95,8 @@ function evaluateRule(rule) {
             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`)
+                    `as far as work may be handed on, and waiting will not change ` +
+                    `that; do this work here rather than delegating again`)
                 : null;
         }
         case "chain_budget": {
@@ -94,8 +106,8 @@ function evaluateRule(rule) {
                 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`)
+                    `spent for this whole chain and it does not refill, so do this ` +
+                    `work here rather than delegating again`)
                 : null;
         }
         case "pair_cooldown": {
@@ -106,10 +118,19 @@ function evaluateRule(rule) {
             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`)
+                ? refuse(rule, true, `handoff cooldown active — retry in ` +
+                    `${rule.cooldownMs - rule.msSinceLastSpawn}ms, or do this work ` +
+                    `here (${rule.msSinceLastSpawn}ms since the last handoff, ` +
+                    `${rule.cooldownMs}ms required)`)
+                : null;
+        }
+        case "pair_seen": {
+            // A boolean carries no measurement to validate — the host either
+            // observed the prior pairing or it did not.
+            return rule.alreadyPaired
+                ? refuse(rule, false, `repeat handoff refused — these two have already worked together ` +
+                    `here and are allowed to only once, so waiting will not change ` +
+                    `that; do this work here instead`)
                 : null;
         }
         case "tenant_ceiling": {
@@ -119,8 +140,20 @@ function evaluateRule(rule) {
                 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`)
+                    `${rule.maxActiveRuns}) — clears as other runs finish, so retry ` +
+                    `shortly or do this work here`)
+                : null;
+        }
+        case "tenant_rate": {
+            const broken = unmeasurable(rule, rule.runsInWindow, "runsInWindow") ??
+                unmeasurable(rule, rule.maxRuns, "maxRuns") ??
+                unmeasurable(rule, rule.windowMs, "windowMs");
+            if (broken)
+                return broken;
+            return rule.runsInWindow >= rule.maxRuns
+                ? refuse(rule, true, `start-rate limit reached (${rule.runsInWindow}/${rule.maxRuns} ` +
+                    `runs in the last ${rule.windowMs}ms) — the window rolls, so ` +
+                    `wait up to ${rule.windowMs}ms and retry, or do this work here`)
                 : null;
         }
         default: {