@adaptic/utils 0.0.1037 → 0.0.1038

package/dist/index.mjs

@@ -72345,11 +72345,34 @@ const alpaca = {
  * traffic can neither trip nor be tripped by traffic on the other side of the
  * PD-9 boundary.
  *
+ * How long a tripped breaker stays open depends on WHY it tripped. A provider
+ * that is refusing work because it is momentarily full ("model busy", 429,
+ * 503, 529, or a leg that ran out its budget queued behind other traffic) is
+ * shedding load it expects to take back within seconds; excluding it for a
+ * full minute pushes every call onto the next leg, which is how one provider's
+ * capacity blip becomes the last leg's overload. Such a run opens for the
+ * shorter `capacity_cooldown_ms`. A run that contains any hard failure (a
+ * rejected credential, a malformed request, an unreachable gateway, an answer
+ * that does not parse) says the route is broken rather than busy, and opens
+ * for the full `cooldown_ms`. Either way the route then admits a bounded number
+ * of half-open probes, and one success closes it.
+ *
  * The clock is injected. Breaker behaviour is entirely about elapsed time, and
  * a test that must sleep to observe a cooldown is a test nobody runs.
  *
  * @module llm/circuit-breaker
  */
+/**
+ * @returns A record for a route with no failures on file.
+ */
+function freshRecord() {
+    return {
+        consecutiveFailures: 0,
+        openedAtMs: null,
+        probesInFlight: 0,
+        runHasHardFailure: false,
+    };
+}
 /**
  * Tracks route health and decides whether a leg may be attempted.
  */
@@ -72382,7 +72405,26 @@ class CircuitBreakerRegistry {
             return "closed";
         }
         const elapsed = this.now() - record.openedAtMs;
-        return elapsed >= this.config.cooldown_ms ? "half-open" : "open";
+        return elapsed >= this.cooldownFor(record) ? "half-open" : "open";
+    }
+    /**
+     * The cooldown a record's current run earns.
+     *
+     * A run made only of capacity failures earns the capacity cooldown; one hard
+     * failure anywhere in the run earns the full one. Mixed evidence is read as
+     * the worse case, because a route that is both busy and broken is broken.
+     * The capacity cooldown is never allowed to exceed the full one, so a
+     * misconfigured table cannot make busy routes wait longer than broken ones.
+     *
+     * @param record The route's record.
+     * @returns The cooldown in milliseconds.
+     */
+    cooldownFor(record) {
+        const capacityCooldown = this.config.capacity_cooldown_ms ?? this.config.cooldown_ms;
+        if (record.runHasHardFailure) {
+            return this.config.cooldown_ms;
+        }
+        return Math.min(capacityCooldown, this.config.cooldown_ms);
     }
     /**
      * Whether a route may be attempted now.
@@ -72453,11 +72495,7 @@ class CircuitBreakerRegistry {
      * @returns void
      */
     onSuccess(routeKey) {
-        this.records.set(routeKey, {
-            consecutiveFailures: 0,
-            openedAtMs: null,
-            probesInFlight: 0,
-        });
+        this.records.set(routeKey, freshRecord());
     }
     /**
      * Record a failure, opening the breaker once the threshold is reached.
@@ -72466,13 +72504,19 @@ class CircuitBreakerRegistry {
      * re-accumulate the threshold: the probe was the test, and it failed.
      *
      * @param routeKey The route's stable key.
+     * @param kind Whether the failure was a capacity signal or a hard failure.
+     *   Defaults to `hard`, so a caller that cannot tell gets the longer, safer
+     *   cooldown.
      * @returns void
      */
-    onFailure(routeKey) {
+    onFailure(routeKey, kind = "hard") {
         const wasHalfOpen = this.stateOf(routeKey) === "half-open";
         const record = this.recordFor(routeKey);
         record.probesInFlight = 0;
         record.consecutiveFailures += 1;
+        if (kind === "hard") {
+            record.runHasHardFailure = true;
+        }
         if (wasHalfOpen || record.consecutiveFailures >= this.config.failure_threshold) {
             record.openedAtMs = this.now();
         }
@@ -72484,17 +72528,19 @@ class CircuitBreakerRegistry {
      * @returns A snapshot.
      */
     snapshot(routeKey) {
-        const record = this.records.get(routeKey) ?? {
-            consecutiveFailures: 0,
-            openedAtMs: null,
-            probesInFlight: 0,
-        };
+        const record = this.records.get(routeKey) ?? freshRecord();
         return {
             routeKey,
             state: this.stateOf(routeKey),
             consecutiveFailures: record.consecutiveFailures,
             openedAtMs: record.openedAtMs,
             probesInFlight: record.probesInFlight,
+            failureKind: record.consecutiveFailures === 0
+                ? null
+                : record.runHasHardFailure
+                    ? "hard"
+                    : "capacity",
+            cooldownMs: this.cooldownFor(record),
         };
     }
     /**
@@ -72522,7 +72568,7 @@ class CircuitBreakerRegistry {
     recordFor(routeKey) {
         let record = this.records.get(routeKey);
         if (record === undefined) {
-            record = { consecutiveFailures: 0, openedAtMs: null, probesInFlight: 0 };
+            record = freshRecord();
             this.records.set(routeKey, record);
         }
         return record;
@@ -72798,7 +72844,17 @@ var providers$1 = {
 		max_concurrent: 12,
 		acquire_timeout_ms: 15000,
 		source: null,
-		note: "The unit is per model: the scope_source states 'Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously', measured as requests, input tokens and output tokens per minute for each model class, with no concurrency ceiling. Each model therefore gets its own guard, so traffic on one model class (an Opus incumbent serving background aliases) cannot refuse calls to another (the Haiku incumbent of the hot-path alias). The NUMBERS stay conservative-default: the organisation's usage tier sets the real ceilings and is read only from the Claude Console rate-limits page, which has not been transcribed. The lowest standard tier listed at the source allows 1,000 requests per minute per model; organisations with limited history can start on an evaluation tier below that, which is why these values are held well under it. Transcribe the tier's limits (W3-07) and set basis to published."
+		note: "The unit is per model: the scope_source states 'Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously', measured as requests, input tokens and output tokens per minute for each model class, with no concurrency ceiling. Each model therefore gets its own guard, so traffic on one model class (an Opus incumbent serving background aliases) cannot refuse calls to another (the Haiku incumbent of the hot-path alias). The NUMBERS stay conservative-default: the organisation's usage tier sets the real ceilings and is read only from the Claude Console rate-limits page, which has not been transcribed. The lowest standard tier listed at the source allows 1,000 requests per minute per model; organisations with limited history can start on an evaluation tier below that, which is why these values are held well under it. Transcribe the tier's limits (W3-07) and set basis to published.",
+		models: {
+			"claude-haiku-4-5": {
+				basis: "conservative-default",
+				requests_per_minute: 300,
+				max_concurrent: 48,
+				acquire_timeout_ms: 10000,
+				source: null,
+				note: "Raised 2026-09-28 for the closed-incumbent role this model holds on llm.fast, llm.decide and llm.extract. Measured that day: when DeepInfra was capacity-limited ('Model busy, retry later', timeouts at the 30000 ms hot-path budget), both DeepInfra legs of llm.fast opened their breakers and ALL of the alias's traffic fell to this model, where the 12-permit guard could not absorb it. In the 12 minutes to 15:33Z the incumbent leg recorded 18 timeouts, 15 breaker-open and 11 guard refusals ('did not admit the call within 15000 ms'), and the chain exhausted 20-45 times per 5 minutes. Sizing: in-flight demand is arrival rate times leg duration (Little's law), and the leg duration that matters is the worst case the chain permits, 30 s. 12 permits at 30 s serve 24 calls/min; 48 permits serve 96 calls/min at 30 s and up to the 300/min rate bound at haiku's normal single-digit-second latency, which covers the diverted llm.fast load plus normal llm.decide/llm.extract volume on the same guard. requests_per_minute is raised with it (the two bind in series) to 300, which is 30% of the 1,000 requests per minute per model that the scope_source lists for the lowest standard tier, so it remains below any standard tier's ceiling; no Anthropic 429 was observed in the window. acquire_timeout_ms is cut from 15000 to 10000 so an admitted call keeps at least 20 s of its 30 s leg budget: a call admitted after a 15 s wait had half its budget left, timed out at the provider, and that timeout was charged to this route's breaker, which then refused every call for the cooldown. STILL conservative-default: the organisation's tier has not been transcribed from the Claude Console (W3-07). Other Anthropic models keep the provider numbers."
+			}
+		}
 	},
 	openai: {
 		basis: "conservative-default",
@@ -72907,18 +72963,42 @@ const SECONDS_PER_MINUTE = 60;
 const TOKENS_PER_REQUEST = 1;
 const config$1 = limitsConfig;
 /**
- * Resolve the limits that apply to a provider.
+ * Resolve the limits that apply to a provider, or to one of its models.
  *
  * An unregistered provider falls back to the conservative defaults rather than
  * to no limit at all. Treating "unknown" as "unlimited" would make every newly
  * onboarded provider the one most likely to be over-driven, which is exactly
  * backwards: a new provider is the one whose real ceiling is least understood.
  *
+ * A model with an override on a per-model provider runs at the override's
+ * numbers and provenance; every other model runs at the provider's. The
+ * override is ignored for a provider scoped as a whole, because that provider
+ * has one guard and a per-model number cannot be enforced on it.
+ *
  * @param provider The provider key.
+ * @param modelId The model, when the caller knows which one it addresses.
  * @returns Its limits.
  */
-function limitsFor(provider) {
-    return config$1.providers[provider] ?? config$1.defaults;
+function limitsFor(provider, modelId) {
+    const limits = config$1.providers[provider] ?? config$1.defaults;
+    if (limits.scope !== "model" || modelId === undefined || modelId.length === 0) {
+        return limits;
+    }
+    const override = limits.models?.[modelId];
+    if (override === undefined) {
+        return limits;
+    }
+    const { models: _siblings, ...providerLimits } = limits;
+    return {
+        ...providerLimits,
+        basis: override.basis,
+        requests_per_minute: override.requests_per_minute,
+        requests_per_minute_basis: override.requests_per_minute_basis,
+        max_concurrent: override.max_concurrent,
+        acquire_timeout_ms: override.acquire_timeout_ms,
+        source: override.source ?? null,
+        note: override.note,
+    };
 }
 /** Every provider with a recorded limit, plus whether it is published or a default. */
 function limitsInventory() {
@@ -73114,7 +73194,7 @@ const guardIdentities = new Map();
 function rateLimiterFor(identity) {
     let limiter = rateLimiters.get(identity.key);
     if (limiter === undefined) {
-        const limits = limitsFor(identity.provider);
+        const limits = limitsFor(identity.provider, identity.modelId);
         limiter = new TokenBucketRateLimiter({
             maxTokens: limits.requests_per_minute,
             refillRate: limits.requests_per_minute / SECONDS_PER_MINUTE,
@@ -73135,7 +73215,7 @@ function rateLimiterFor(identity) {
 function concurrencyGateFor(identity) {
     let gate = concurrencyGates.get(identity.key);
     if (gate === undefined) {
-        gate = new ConcurrencyGate(identity, limitsFor(identity.provider).max_concurrent);
+        gate = new ConcurrencyGate(identity, limitsFor(identity.provider, identity.modelId).max_concurrent);
         concurrencyGates.set(identity.key, gate);
         guardIdentities.set(identity.key, identity);
     }
@@ -73165,8 +73245,8 @@ function concurrencyGateFor(identity) {
  *   or the caller stopped waiting first.
  */
 async function withProviderGuards(provider, call, maxWaitMs, scope = {}) {
-    const limits = limitsFor(provider);
     const identity = guardIdentity(provider, scope.modelId);
+    const limits = limitsFor(provider, identity.modelId);
     const waitBudgetMs = maxWaitMs === undefined
         ? limits.acquire_timeout_ms
         : Math.min(maxWaitMs, limits.acquire_timeout_ms);
@@ -73198,7 +73278,7 @@ function guardSnapshots() {
     return [...guardIdentities.values()]
         .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
         .map((identity) => {
-        const limits = limitsFor(identity.provider);
+        const limits = limitsFor(identity.provider, identity.modelId);
         const limiter = rateLimiters.get(identity.key);
         const gate = concurrencyGates.get(identity.key);
         return {
@@ -73518,6 +73598,38 @@ async function runLeg(leg, params, execution, budgetMs) {
         execution.callerSignal?.removeEventListener("abort", forwardAbort);
     }
 }
+/**
+ * HTTP statuses a provider (or the gateway relaying it) uses to say it is full
+ * rather than that the request or the route is wrong: request timeout, too
+ * early, too many requests, service unavailable, and Anthropic's overloaded.
+ */
+const CAPACITY_STATUSES = new Set([408, 425, 429, 503, 529]);
+/**
+ * Wording providers use for a capacity refusal when the status is lost on the
+ * way (a relayed body, a client library's own error). DeepInfra's is
+ * "Model busy, retry later"; Anthropic's is "Overloaded".
+ */
+const CAPACITY_WORDING = /\b(busy|overloaded|capacity|rate[ -]?limit(ed)?|too many requests)\b/i;
+/**
+ * Whether a failure is the provider saying it is full rather than broken.
+ *
+ * Read by shape rather than by class, because the same signal reaches the
+ * chain from more than one transport and not every transport's error class is
+ * importable here.
+ *
+ * @param error The thrown value.
+ * @param reason Its message.
+ * @returns Whether it is a capacity signal.
+ */
+function isCapacitySignal(error, reason) {
+    if (typeof error === "object" && error !== null) {
+        const status = error.status;
+        if (typeof status === "number" && CAPACITY_STATUSES.has(status)) {
+            return true;
+        }
+    }
+    return CAPACITY_WORDING.test(reason);
+}
 /**
  * Classify why a leg failed.
  *
@@ -73526,6 +73638,13 @@ async function runLeg(leg, params, execution, budgetMs) {
  * cancellation as a provider failure would let a burst of user-cancelled
  * requests open the breaker on a perfectly healthy route.
  *
+ * Among failures that do count, a capacity signal (the provider said it is
+ * busy, or the leg ran out its budget waiting on it) is told apart from a hard
+ * failure so the breaker can re-admit a busy route sooner than a broken one. A
+ * timeout is read as capacity: on a reachable provider it is what a full queue
+ * looks like from outside, and a provider that is actually down still costs no
+ * more than one probe per capacity cooldown.
+ *
  * @param error The thrown value.
  * @param callerSignal The caller's cancellation signal, if any.
  * @returns The outcome and whether it counts against route health.
@@ -73536,24 +73655,45 @@ function classify(error, callerSignal) {
             outcome: "skipped",
             reason: "caller cancelled",
             countsAgainstHealth: false,
+            failureKind: "hard",
         };
     }
     if (error instanceof LegTimeoutError) {
-        return { outcome: "timeout", reason: error.message, countsAgainstHealth: true };
+        return {
+            outcome: "timeout",
+            reason: error.message,
+            countsAgainstHealth: true,
+            failureKind: "capacity",
+        };
     }
     if (error instanceof UnsupportedCapabilityError) {
-        return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
+        return {
+            outcome: "skipped",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
     }
     if (error instanceof ToolChoiceIgnoredError) {
         // The route answered; it broke a declared guarantee rather than failing to
         // be available, so its breaker is not charged for it.
-        return { outcome: "error", reason: error.message, countsAgainstHealth: false };
+        return {
+            outcome: "error",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
     }
+    // Self-inflicted pacing, not provider ill-health. Counting it would let the
+    // client's own throttling open a breaker on a perfectly healthy provider and
+    // permanently reroute traffic nobody chose to reroute.
     if (error instanceof RateGuardTimeoutError) {
-        // Self-inflicted pacing, not provider ill-health. Counting it would let the
-        // client's own throttling open a breaker on a perfectly healthy provider
-        // and permanently reroute traffic nobody chose to reroute.
-        return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
+        return {
+            outcome: "skipped",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
     }
     const reason = error instanceof Error ? error.message : String(error);
     if (/abort/i.test(reason)) {
@@ -73561,9 +73701,20 @@ function classify(error, callerSignal) {
             outcome: "timeout",
             reason: `aborted: ${reason}`,
             countsAgainstHealth: true,
+            failureKind: "capacity",
         };
     }
-    return { outcome: "error", reason, countsAgainstHealth: true };
+    if (error instanceof LlmResponseFormatError) {
+        // The provider answered, badly. That is a route defect, not a full queue,
+        // whatever words the unparseable content happens to contain.
+        return { outcome: "error", reason, countsAgainstHealth: true, failureKind: "hard" };
+    }
+    return {
+        outcome: "error",
+        reason,
+        countsAgainstHealth: true,
+        failureKind: isCapacitySignal(error, reason) ? "capacity" : "hard",
+    };
 }
 /**
  * Whether the caller has stopped waiting.
@@ -73682,9 +73833,9 @@ async function executeChain(alias, execution) {
             return { response, servedBy: route, attempts, totalUsage };
         }
         catch (error) {
-            const { outcome, reason, countsAgainstHealth } = classify(error, execution.callerSignal);
+            const { outcome, reason, countsAgainstHealth, failureKind } = classify(error, execution.callerSignal);
             if (countsAgainstHealth) {
-                execution.breakers.onFailure(route.routeKey);
+                execution.breakers.onFailure(route.routeKey, failureKind);
             }
             else if (holdsProbe) {
                 // No verdict on the route's health, but the probe slot this attempt
@@ -73732,6 +73883,7 @@ var defaults = {
 	circuit_breaker: {
 		failure_threshold: 5,
 		cooldown_ms: 60000,
+		capacity_cooldown_ms: 15000,
 		half_open_probes: 1
 	}
 };