vern-llm 2.4.2 → 2.6.0

package/dist/{index.d.ts → index.d.mts}

@@ -7,16 +7,7 @@ type LLMErrorType = 'timeout' | 'api' | 'network' | 'parse' | 'validation' | 'in
  * e.g. `authentication`/`authorization` apply the same way regardless of
  * which type wraps them.
  */
-type LLMErrorCode = 'unknown_tool' | 'duplicate_tool_call_id' | 'tool_choice_none_violated' | 'unexpected_tool_calls' | 'unsupported_capability' | 'duplicate_tool_names' | 'unknown_tool_choice' | 'duplicate_tool_result_ids' | 'unknown_tool_result_ids' | 'missing_tool_results' | 'rate_limit_queue_full' | 'rate_limit_queue_timeout' | 'rate_limit_capacity_exceeded' | 'provider_rate_limited' | 'request_timeout' | 'idle_timeout' | 'authentication' | 'authorization' | 'not_found' | 'payload_too_large' | 'server_error' | 'empty_response' | 'connection_failed' | 'circuit_cooling_down' | 'circuit_trial_in_flight' | 'fallback_exhausted' | 'tool_arguments_parse_failed' | 'stream_frame_invalid';
-/**
- * Tool contract codes: a model or provider response defect, not a
- * transient provider fault. Deterministic on the wire request, so
- * retrying can't change the outcome and it shouldn't count toward the
- * circuit breaker either. Shared by `LLMError.retryable` below and by
- * `CallExecutor`'s own retry/breaker accounting, so the two can't drift
- * apart.
- */
-
+type LLMErrorCode = 'unknown_tool' | 'duplicate_tool_call_id' | 'tool_choice_none_violated' | 'unexpected_tool_calls' | 'unsupported_capability' | 'duplicate_tool_names' | 'unknown_tool_choice' | 'duplicate_tool_result_ids' | 'unknown_tool_result_ids' | 'missing_tool_results' | 'middleware_threw' | 'rate_limit_queue_full' | 'rate_limit_queue_timeout' | 'rate_limit_capacity_exceeded' | 'provider_rate_limited' | 'retry_budget_exhausted' | 'request_timeout' | 'idle_timeout' | 'middleware_timeout' | 'deadline_exceeded' | 'authentication' | 'authorization' | 'not_found' | 'payload_too_large' | 'server_error' | 'empty_response' | 'connection_failed' | 'circuit_cooling_down' | 'circuit_trial_in_flight' | 'fallback_exhausted' | 'tool_arguments_parse_failed' | 'stream_frame_invalid' | 'soft_failure_detected';
 /** One tool call's contract failure, used to report every bad call in a response at once. */
 interface ToolIssue {
   name: string;
@@ -133,21 +124,6 @@ interface LLMRequestSnapshot {
   /** Wall clock time the attempt started, ms since epoch. */
   startedAt: number;
 }
-/**
- * Builds a point-in-time, plain data copy of one attempt's outgoing
- * request. Mirrors `LLMError.toSnapshot()`: never thrown or dispatched
- * again, safe to serialize and store. A plain function rather than a
- * method, since unlike `LLMError` a request has no throwable identity or
- * derived state worth wrapping in a class.
- *
- * `startedAt` is optional so existing call sites (and tests) that don't
- * care about exact timing keep working, but a caller that has a real
- * capture time should always pass it: this function may run well after
- * the request was actually dispatched (e.g. `callExecutor` only builds
- * the snapshot once an attempt has failed), so defaulting to `Date.now()`
- * here would record failure-handling time, not request-start time.
- */
-
 /**
  * One failed attempt on the way to a terminal error: which attempt index
  * it was, and a snapshot of the error it failed with. The base shape
@@ -187,11 +163,20 @@ declare class LLMError extends Error {
    * `nonRetryableStatus` list. False for `parse`/`validation`/
    * `invalid_params`/`aborted` types (the caller's own input, the model's
    * own response, or intentional cancellation, none of which are the
-   * provider being unhealthy), the tool contract codes, and the local
-   * rate limit codes. Subclasses (see `FallbackExhaustedError`) may
-   * override this when `type` alone carries no retry signal.
+   * provider being unhealthy), the tool contract codes, the local
+   * rate limit codes, and the middleware timeout code.
+   * Subclasses (see `FallbackExhaustedError`) may override this when `type`
+   * alone carries no retry signal.
    */
   get retryable(): boolean;
+  /**
+   * Whether this failure should count toward the circuit breaker's
+   * failure threshold. Not the same question as `retryable`:
+   * `quota_exceeded` is retryable but says nothing about provider
+   * health, so it's excluded here even though `retryable` is true for
+   * it. Always false whenever `retryable` is false.
+   */
+  get countsTowardBreaker(): boolean;
   /**
    * Copies this error's fields into an {@link LLMErrorSnapshot}, for
    * recording as a `RetryAttempt`/`FallbackAttempt`. `retryable` is
@@ -234,10 +219,9 @@ declare function isLLMError(err: unknown): err is LLMError;
 declare function hasIssues<C extends keyof LLMErrorIssuesByCode>(err: LLMError, code: C): err is LLMError & {
   code: C;
   issues: LLMErrorIssuesByCode[C];
-}; //#endregion
+};
+//#endregion
 //#region src/types/cache.d.ts
-
-//# sourceMappingURL=errors.d.ts.map
 interface CacheAdapter<T = unknown> {
   get(key: string): Promise<{
     hit: boolean;
@@ -248,13 +232,20 @@ interface CacheAdapter<T = unknown> {
   resolveKey?(key: string): Promise<string>;
 }
 /**
- * Trivial default so the package works out of the box with no external deps
- * Not shared across processes, swap in Redis/Upstash/etc for production
+ * Which entry `InMemoryCacheAdapter` evicts once `maxSize` is exceeded.
+ * `'fifo'` (default) drops the oldest inserted entry. `'lru'` drops the
+ * least recently read or written entry.
+ */
+type EvictionOption = 'fifo' | 'lru';
+/**
+ * Trivial default so the package works out of the box with no external deps.
+ * Not shared across processes, swap in Redis/Upstash/etc for production.
  */
 declare class InMemoryCacheAdapter<T = unknown> implements CacheAdapter<T> {
   private readonly maxSize;
   private store;
-  constructor(maxSize?: number);
+  private readonly eviction;
+  constructor(maxSize?: number, eviction?: EvictionOption);
   get(key: string): Promise<{
     hit: boolean;
     value: T | null;
@@ -301,104 +292,512 @@ declare class TieredCacheAdapter<T = unknown> implements CacheAdapter<T> {
   set(key: string, value: T, ttl: number): Promise<void>;
   delete(key: string): Promise<void>;
 }
-
+//#endregion
+//#region src/types/events.d.ts
+/**
+ * Reports what happened during a call. Fire and forget, mirroring
+ * `onUsage`: the return value is never read and a throwing handler cannot
+ * change what the call does, only what gets reported about it.
+ */
+type VernLLMEvent = {
+  kind: 'retry';
+  requestId: string;
+  provider: string;
+  /** The model actually resolved for this call (honors a per-call `model` override). */
+  model: string;
+  /** The 1-based retry ordinal (the 1st retry is `1`, not the overall attempt count). */
+  attempt: number;
+  maxRetries: number;
+  delayMs: number;
+  retryAfterHonored: boolean;
+  error: LLMError;
+} | {
+  kind: 'circuit_state';
+  provider: string;
+  /**
+   * The model of the call that triggered this specific transition
+   * (whatever was passed to the `assertClosed`/`recordSuccess`/
+   * `recordFailure` call that caused it), not a property of the
+   * circuit itself: the breaker still counts failures across every
+   * model together, so a threshold crossing can be the sum of
+   * several different models' failures even though only the
+   * triggering call's `model` is reported here.
+   */
+  model: string;
+  from: CircuitState;
+  to: CircuitState;
+  consecutiveFailures: number;
+} | {
+  kind: 'fallback';
+  requestId: string;
+  /** Provider name of the target that just failed. */
+  from: string;
+  /** Provider name of the target about to be tried next. */
+  to: string;
+  /** `-1` for the primary target, otherwise the index into `fallback`. */
+  fromIndex: number;
+  toIndex: number;
+  /** The normalized error that caused `from` to be abandoned. */
+  error: LLMError;
+  /** Time spent on `from`, including its own retries, before giving up. */
+  elapsedMs: number;
+} | {
+  kind: 'rate_limited';
+  requestId: string;
+  provider: string;
+  /** The model actually resolved for this call (honors a per-call `model` override). */
+  model: string;
+  /** How long this attempt sat queued for capacity before it was let through. */
+  waitedMs: number;
+  /** Which configured bucket was blocking this attempt just before it cleared. */
+  reason: 'concurrency' | 'rpm' | 'tpm';
+} | {
+  kind: 'middleware';
+  requestId: string;
+  /** This middleware's `name`, or its array position if unnamed. */
+  middleware: string;
+  hook: 'transform' | 'wrap_short_circuit' | 'enabled_skip';
+  /** For `hook: 'transform'` only: which top-level fields the merged patch touched. */
+  patchedFields?: string[];
+};
+type OnEvent = (event: VernLLMEvent) => void;
+//#endregion
+//#region src/types/middleware.d.ts
+/** Capabilities of the target a middleware hook is currently looking at. */
+interface MiddlewareCapabilities {
+  /**
+   * Whether this target honors `response_format: { type: 'json_object' }`
+   * as a real constraint. Mirrors `LLMClient.supportsJsonObjectMode`.
+   * `false` for `fromAnthropic` and `fromBedrock`.
+   */
+  supportsJsonObjectMode: boolean;
+}
+/**
+ * A typed reference to one slot in `ctx.state`. Create one with
+ * `createStateKey`, export it, and import the same reference wherever
+ * another middleware needs to read or write the same value. There's no
+ * string key anywhere in this path, so a typo becomes a missing import
+ * or an undefined variable, a compile error, instead of a silently
+ * created new property.
+ */
+interface MiddlewareStateKey<T> {
+  readonly debugName: string;
+  /**
+   * Never set at runtime; exists purely so `T` is actually used
+   * somewhere in this interface's shape (a phantom type), which is what
+   * lets `MiddlewareStateBag.get`/`set` infer the right type for a given
+   * key instead of two `MiddlewareStateKey<string>` and
+   * `MiddlewareStateKey<number>` keys being structurally identical.
+   */
+  readonly __phantom?: T;
+}
+/** Creates a new, distinct `MiddlewareStateKey`. `debugName` is used only in log lines and the `'middleware'` event; it never affects equality. */
+declare function createStateKey<T>(debugName: string): MiddlewareStateKey<T>;
+/**
+ * Typed, per-logical-call storage two middleware can deliberately share a
+ * value through (a span ID one sets, another reads). Backed by a plain
+ * `Map` internally, created once per logical call and never read or
+ * written by VernLLM itself.
+ */
+interface MiddlewareStateBag {
+  get<T>(key: MiddlewareStateKey<T>): T | undefined;
+  set<T>(key: MiddlewareStateKey<T>, value: T): void;
+}
+/** A plain, `Map`-backed `MiddlewareStateBag`. */
+declare function createMiddlewareStateBag(): MiddlewareStateBag;
+/** Fields every `MiddlewareContext` variant carries, regardless of `stage`. */
+interface MiddlewareContextBase {
+  requestId: string;
+  /** Capabilities of the target this stage's identity fields describe. */
+  capabilities: MiddlewareCapabilities;
+  signal?: AbortSignal;
+  /** Shared, collision-proof state for two middleware to deliberately coordinate through. See `MiddlewareStateBag`. */
+  state: MiddlewareStateBag;
+  /** Simple, string-keyed scratch space, pre-namespaced to this one middleware so two middleware can never collide here even by accident. */
+  own: Record<string, unknown>;
+}
+/**
+ * The `ctx` `transform` receives, and every attempt-scoped event context
+ * (`'retry'`, `'fallback'`, `'circuit_state'`, `'middleware'`). Built once
+ * a specific target has actually been selected for this attempt, so every
+ * field describes the real target, not a placeholder.
+ */
+interface AttemptContext extends MiddlewareContextBase {
+  stage: 'attempt';
+  /** The target this attempt is actually dispatched to. */
+  requestedProvider: string;
+  requestedModel: string;
+  isFallbackAttempt: boolean;
+  /**
+   * The real, current attempt number for this dispatch.
+   *
+   * Exception: on a `'circuit_state'` event triggered by a pre-dispatch
+   * check (`assertClosed`, before any attempt has been made), this is
+   * `1` regardless of which attempt is about to run, since no attempt
+   * exists yet to report. Every other `'circuit_state'` event, and every
+   * other attempt-scoped event, reports the real attempt number.
+   */
+  attempt: number;
+}
+/**
+ * The `ctx` `wrap` receives before `next()` resolves (and `onError`'s own
+ * `ctx`, built the same way under the hood). Built once, before any
+ * fallback target is chosen, so it only ever describes the primary
+ * target. There is no real "requested" target yet, and no attempt count,
+ * fallback flag, or per-attempt capability to report. Read `next()`'s
+ * resolved `CallResult.meta` once you need to know what actually
+ * happened.
+ */
+interface PreDispatchContext extends MiddlewareContextBase {
+  stage: 'pre-dispatch';
+  /** The primary target only, not necessarily who ends up answering. */
+  primaryProvider: string;
+  primaryModel: string;
+}
+/**
+ * `enabled` and `onEvent` are called from both stages (gating/observing
+ * `transform` as well as `wrap`), so they receive this union and must
+ * narrow on `ctx.stage` before reading stage-specific fields.
+ * `transform` and `wrap` themselves receive the single variant that's
+ * always accurate for them (`AttemptContext`/`PreDispatchContext`
+ * respectively). See `VernLLMMiddleware`.
+ */
+type MiddlewareContext = AttemptContext | PreDispatchContext;
+/** The `response_format` shape `RequestBuilder` can put on the wire. */
+type WireResponseFormat = {
+  type: 'json_object';
+} | {
+  type: 'json_schema';
+  json_schema: {
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+    description?: string;
+  };
+};
+/** A tool as it appears on the wire, OpenAI's `function`-wrapped shape. */
+interface WireTool {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+/**
+ * The wire-shaped request `RequestBuilder.build()` produces for one call
+ * attempt, before dispatch. Read only inside `transform`; return a patch
+ * of the fields you want to change instead of the whole object.
+ */
+interface WireCallRequest {
+  model: string;
+  temperature?: number;
+  max_tokens: number;
+  response_format?: WireResponseFormat;
+  reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+  budget_tokens?: number;
+  tools?: WireTool[];
+  tool_choice?: WireToolChoice;
+  messages: WireMessage[];
+}
+/**
+ * What `transform` returns: a patch merged onto the request that
+ * `RequestBuilder.build()` (plus every earlier middleware's own patch)
+ * already produced, not a replacement for it. `model` and
+ * `response_format` can't be expressed here at all, since everything
+ * downstream that attributes a call to a target keys off the values
+ * `RequestBuilder` already resolved for those two fields, not off
+ * whatever ends up on the wire request. `messages`/`tools` are joined by
+ * a separate `add*` field, appended rather than replaced, so two
+ * independently written middleware can each add to the list without one
+ * silently clobbering what the other already added.
+ */
+interface WireCallRequestPatch {
+  temperature?: number;
+  max_tokens?: number;
+  reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+  budget_tokens?: number;
+  tool_choice?: WireToolChoice;
+  /** Replaces the whole message list. Prefer `addMessages` unless a full replace is genuinely the intent. */
+  messages?: WireMessage[];
+  /** Appended after whatever earlier middleware already added. Never clobbers a prior addition. */
+  addMessages?: WireMessage[];
+  /** Replaces the whole tool list. Prefer `addTools`, same reasoning as `messages`/`addMessages`. */
+  tools?: WireTool[];
+  /** Appended after whatever earlier middleware already added. Never clobbers a prior addition. */
+  addTools?: WireTool[];
+}
+/**
+ * The settled outcome of one logical call, passed to `wrap`'s `next()`.
+ * `meta` is populated once a target has actually answered, for both
+ * streaming and non-streaming calls (`undefined` only on a cache hit,
+ * where nothing was actually spent).
+ */
+interface CallResult<T = unknown> {
+  value: T;
+  meta?: CallMeta;
+}
+/**
+ * One entry in `VernLLMOptions.middleware`. All four hooks are optional;
+ * an entry that sets none of them is inert. See the middleware docs for
+ * how `transform`, `wrap`, `onEvent`, and `enabled` compose across
+ * several entries.
+ */
+interface VernLLMMiddleware {
+  /** Used in log lines and the `'middleware'` event. Defaults to this entry's array position when omitted. */
+  name?: string;
+  /** Sort key for composition order, ascending, ties broken by array order. See the middleware docs for what "lower runs first" means for `wrap`. */
+  priority?: number;
+  /**
+   * Boolean for a static on/off switch, or a predicate evaluated per
+   * call. A throwing, rejecting, or timed-out predicate is logged and
+   * treated as `false` for that call.
+   */
+  enabled?: boolean | ((ctx: MiddlewareContext) => boolean | Promise<boolean>);
+  /** Per-middleware override of the instance-level `middlewareTimeoutMs`, applied to this entry's `transform` and function `enabled`. `<= 0` means unbounded (no timer at all). */
+  timeoutMs?: number;
+  /** Transforms the outgoing wire request for one attempt. Runs once per attempt, including retries. `ctx` is always accurate to the real target for this attempt. */
+  transform?: (request: Readonly<WireCallRequest>, ctx: AttemptContext) => WireCallRequestPatch | Promise<WireCallRequestPatch>;
+  /**
+   * Wraps one whole logical call, exactly once, regardless of how many
+   * retries or fallback targets ran underneath it. `ctx` is built once,
+   * before any fallback target is chosen, so it only describes the
+   * primary target. There is no `requestedProvider`/`isFallbackAttempt`/
+   * `attempt` to read here. Read `next()`'s resolved `CallResult.meta`
+   * for what actually happened.
+   */
+  wrap?: (request: Readonly<WireCallRequest>, next: () => Promise<CallResult>, ctx: PreDispatchContext) => Promise<CallResult>;
+  /** Observes the same events reported on `VernLLMOptions.onEvent`, filtered by this middleware's own `enabled`. Called from both stages; narrow on `ctx.stage` before reading stage-specific fields. */
+  onEvent?: (event: VernLLMEvent, ctx: MiddlewareContext) => void;
+}
 //#endregion
 //#region src/circuitBreaker.d.ts
-//# sourceMappingURL=cache.d.ts.map
+/** The call this mutation happened as part of, forwarded to `onStateChange` untouched. */
+interface CircuitBreakerCallContext {
+  requestId: string;
+  state: MiddlewareStateBag;
+  signal?: AbortSignal;
+  /** Omitted for calls before any attempt exists, like `assertClosed`'s pre-dispatch check. */
+  attempt?: number;
+}
 interface CircuitBreakerOptions {
   /** Consecutive failures before the circuit opens, default 5 */
   threshold?: number;
   /** How long the circuit stays open before allowing a trial request, in ms. Default 30000 */
   cooldownMs?: number;
   /**
-   * Called after every real state change, never for a no-op transition
-   * (e.g. open to open). `model` is the resolved model of whichever call
-   * triggered this specific transition (the `model` passed to whichever
-   * of `assertClosed`/`recordSuccess`/`recordFailure` caused it).
-   *
-   * With `isolateByModel` off (the default), this is a label only: the
-   * breaker still counts failures across every model together, so a
-   * threshold crossing can be the sum of several different models'
-   * failures even though only the triggering call's `model` is reported
-   * here. With `isolateByModel` on, it's exact: each model has its own
-   * counter, so the transition really was caused solely by that model.
+   * Fires after every real state change, never a no-op transition. `model`
+   * is the resolved model of whichever call triggered it. With
+   * `isolateByModel` off, failures are still counted across every model.
    */
-  onStateChange?: (from: CircuitState, to: CircuitState, consecutiveFailures: number, model?: string) => void;
+  onStateChange?: (from: CircuitState, to: CircuitState, consecutiveFailures: number, model?: string, context?: CircuitBreakerCallContext) => void;
   /**
    * Track a separate circuit per resolved model instead of one shared
-   * circuit for the whole instance. A failure on one model then never
-   * opens another model's circuit, at the cost of slower detection for
-   * an outage spread across many distinct models (each model's counter
-   * must independently cross `threshold`). Default false: one shared
-   * circuit, matching every version before this option existed.
-   *
-   * A call that omits `model` (only possible calling `CircuitBreaker`
-   * directly, `VernLLM` always passes one) falls into one shared bucket
-   * alongside every other call that also omits it.
+   * circuit. Default false. A call that omits `model` falls into one
+   * shared bucket alongside every other call that also omits it.
    */
   isolateByModel?: boolean;
+  /** Trial calls allowed through per half-open cycle. Default 1, clamped to at least 1. */
+  halfOpenProbes?: number;
+  /** Fraction of `halfOpenProbes` that must succeed to close the circuit. Default 1, clamped to `[0, 1]`. */
+  halfOpenSuccessRatio?: number;
+  /**
+   * Grows `cooldownMs` on each repeat open instead of a fixed wait.
+   * `{ multiplier, maxMs }` covers exponential growth; a `CooldownBackoff`
+   * function covers anything else. Omitted means `cooldownMs` stays fixed.
+   */
+  cooldownBackoff?: ExponentialBackoffOptions | CooldownBackoff;
+  /**
+   * Decides when a bucket's failures should open the circuit.
+   * `{ kind: 'consecutive', threshold }` (the default) opens after that
+   * many failures in a row. `{ kind: 'rolling', windowMs, minCalls,
+   * failureRatio }` opens once at least `minCalls` calls have landed in
+   * the trailing `windowMs` and the failure ratio reaches `failureRatio`.
+   * `minCalls` must be a non-negative integer; `failureRatio` must be
+   * finite and within `[0, 1]`. Both are validated at construction,
+   * thrown as `RangeError`. A `TrippingPolicy` covers anything else, one
+   * instance shared across every model automatically under
+   * `isolateByModel`, since it tracks its own state per key rather than
+   * owning one flat counter.
+   */
+  tripping?: TrippingOption;
+}
+/** Computes the cooldown for a bucket's `reopenCount`-th repeat open. */
+type CooldownBackoff = (reopenCount: number, baseCooldownMs: number) => number;
+interface ExponentialBackoffOptions {
+  /** Growth factor applied per repeat open, e.g. 2 doubles each time. */
+  multiplier: number;
+  /** Upper bound on the computed cooldown, in ms. Default `Infinity`. */
+  maxMs?: number;
+}
+/**
+ * Decides when a bucket's failures should open the circuit. Keyed by
+ * `key` (a resolved model, or the shared bucket's key when
+ * `isolateByModel` is off) rather than holding one flat counter, so a
+ * single `TrippingPolicy` instance is always safe to share across every
+ * bucket: `CircuitBreaker` never needs to clone or construct a fresh one
+ * per model, `isolateByModel` isolation falls out of `key` alone.
+ */
+interface TrippingPolicy {
+  onSuccess(key: string): void;
+  /** Returns true if this failure should open the circuit for `key`. */
+  onFailure(key: string): boolean;
+  reset(key: string): void;
+  /**
+   * Called when `key`'s bucket is discarded (closed and idle, under
+   * `isolateByModel`), so a keyed policy can release that key's state.
+   * Optional: omit if there's nothing to release.
+   */
+  forget?(key: string): void;
+}
+declare class ConsecutiveTripping implements TrippingPolicy {
+  private readonly threshold;
+  private failuresByKey;
+  constructor(threshold: number);
+  onSuccess(key: string): void;
+  onFailure(key: string): boolean;
+  reset(key: string): void;
+  forget(key: string): void;
+}
+declare class RollingTripping implements TrippingPolicy {
+  private readonly windowMs;
+  private readonly minCalls;
+  private readonly failureRatio;
+  private ratiosByKey;
+  constructor(windowMs: number, minCalls: number, failureRatio: number);
+  private ratioFor;
+  onSuccess(key: string): void;
+  onFailure(key: string): boolean;
+  reset(key: string): void;
+  forget(key: string): void;
 }
+/** Not exported. Internal shorthand union for `CircuitBreakerOptions.tripping`. */
+type TrippingOption = {
+  kind: 'consecutive';
+  threshold: number;
+} | {
+  kind: 'rolling';
+  windowMs: number;
+  minCalls: number;
+  failureRatio: number;
+} | TrippingPolicy;
 type CircuitState = 'closed' | 'open' | 'half-open';
 /**
- * Per retry VernLLM-instance circuit breaker. Tracks consecutive failures across
- * calls. Once the threshold is hit, short-circuits new calls with an
- * LLMError('circuit_open') instead of hitting the provider, until the
- * cooldown elapses and a single trial call is allowed through
+ * Per retry VernLLM-instance circuit breaker. Tracks consecutive failures
+ * across calls. Once the threshold is hit, short-circuits new calls with
+ * LLMError('circuit_open') until the cooldown elapses and a trial succeeds.
  */
 declare class CircuitBreaker {
-  private readonly threshold;
   private readonly cooldownMs;
   private readonly onStateChange?;
-  /** Whether this breaker tracks failures per model instead of one shared circuit. Read by `CallExecutor`/`VernLLM` to report per-target in `getCircuitStates`. */
+  /** Whether this breaker tracks failures per model instead of one shared circuit. */
   readonly isolateByModel: boolean;
+  private readonly halfOpenProbes;
+  private readonly halfOpenSuccessRatio;
+  private readonly cooldownBackoff?;
+  /** One instance, keyed per model internally. See `TrippingPolicy`. */
+  private readonly tripping;
   private readonly sharedBucket;
   private readonly bucketsByModel;
   constructor(options?: CircuitBreakerOptions);
-  /** Returns the bucket for a model if one already exists, without allocating. */
-  private lookupBucket;
-  /** Creates and stores a bucket for a model when the first mutation needs one. */
-  private ensureBucketFor;
-  /** Every state mutation routes through here, so `onStateChange` fires exactly once per real change. */
-  private transition;
   /**
    * Throws if the circuit is open and the cooldown hasn't elapsed, or if
-   * the circuit is half-open and a trial call is already in flight.
-   * Otherwise, if the circuit just became eligible for a trial (cooldown
-   * elapsed, or half-open with no trial currently running), this call
-   * becomes that trial
-   */
-  assertClosed(model?: string): void;
-  recordSuccess(model?: string): void;
-  recordFailure(model?: string): void;
-  /**
-   * With `isolateByModel` off (the default), `model` is ignored and the
-   * one shared circuit's state is returned, unchanged from every version
-   * before this option existed. With `isolateByModel` on, returns that
-   * model's own state, `'closed'` for a model never seen yet, same as a
-   * fresh breaker.
+   * half-open with every trial slot claimed. Otherwise claims a trial slot.
    */
+  assertClosed(model?: string, context?: CircuitBreakerCallContext): void;
+  recordSuccess(model?: string, context?: CircuitBreakerCallContext): void;
+  /** `code`, when present, is the failing `LLMError`'s `code`. Missing attributes to `'unknown'`. */
+  recordFailure(model?: string, context?: CircuitBreakerCallContext, code?: LLMErrorCode): void;
+  /** With `isolateByModel` off, `model` is ignored and the shared circuit's state is returned. */
   getState(model?: string): CircuitState;
+  /** Failure counts by `LLMErrorCode` for `model`'s bucket. Returned as a plain object copy. */
+  getFailureBreakdown(model?: string): Partial<Record<LLMErrorCode | 'unknown', number>>;
+  /** Manually opens the circuit, as if `threshold` consecutive failures had just happened. */
+  open(model?: string, context?: CircuitBreakerCallContext): void;
+  /** Manually closes the circuit and resets its failure count, without requiring a real success first. */
+  close(model?: string, context?: CircuitBreakerCallContext): void;
+  /**
+   * Opens `bucket`: stamps `openedAt`/`cooldownMsForOpen` and transitions
+   * to `open`. Shared by `recordFailure`'s trip, `settleTrialIfComplete`'s
+   * reopen, and the manual `open()`, all of which reach this with
+   * `bucket.trial` already `null`.
+   */
+  private openBucket;
+  /** Computes and clamps the cooldown for `bucket`'s current `reopenCount`. Called once, on open. */
+  private computeCooldown;
+  /** Returns the bucket for a model if one already exists, without allocating. */
+  private lookupBucket;
   /**
-   * Manually opens the circuit, as if `threshold` consecutive failures had
-   * just happened, e.g. to pull a provider out of rotation ahead of known
-   * maintenance. Resets the cooldown window from now, same as a real
-   * threshold-crossing failure would, and clears any in-flight half-open
-   * trial since it no longer applies once the circuit is (re)opened.
-   */
-  open(model?: string): void;
-  /**
-   * Manually closes the circuit and resets its failure count, e.g. once a
-   * provider is confirmed healthy again without waiting out the cooldown.
-   * Mirrors `recordSuccess`'s bookkeeping (including dropping the
-   * per-model bucket under `isolateByModel`, once idle) but without
-   * requiring an actual successful call first.
+   * The key `tripping` is called with. Real per-model isolation under
+   * `isolateByModel`, matching `ensureBucketFor`/`lookupBucket`'s own
+   * per-model key. Otherwise one fixed shared key regardless of what
+   * `model` was passed, matching `sharedBucket` being the one and only
+   * bucket in that mode: `model` is never allowed to split tripping state
+   * when `isolateByModel` is off, the same way it never splits which
+   * bucket a call lands in.
    */
-  close(model?: string): void;
+  private trippingKeyFor;
+  /** Creates and stores a bucket for a model when the first mutation needs one. */
+  private ensureBucketFor;
+  /** Drops an idle model's bucket and lets `tripping` release that key's state too. */
+  private forgetModel;
+  /** Every state mutation routes through here, so `onStateChange` fires exactly once per real change. */
+  private transition;
+  /** Once every admitted trial has reported in, closes or reopens based on `halfOpenSuccessRatio`. */
+  private settleTrialIfComplete;
+}
+//#endregion
+//#region src/internal/retryBudget.d.ts
+/**
+ * Tunables for a `RetryBudget`. `windowMs`/`minCalls` behave the same as
+ * `RollingTripping`'s (see `circuitBreaker.ts`): `minCalls` gates the
+ * check so a cold start with too little traffic to judge doesn't trip.
+ * `retryRatio` is the max fraction of calls in the window allowed to be
+ * retries before the budget stops allowing more. `minCalls` must be a
+ * non-negative integer; `retryRatio` must be finite and within `[0, 1]`.
+ * Both are validated at construction, thrown as `RangeError`.
+ */
+interface RetryBudgetOptions {
+  windowMs: number;
+  minCalls: number;
+  retryRatio: number;
+}
+/**
+ * Caps how much of a target's recent traffic is allowed to be retries,
+ * independent of the circuit breaker. The breaker asks whether the
+ * provider is healthy; this asks whether retrying is still worth the
+ * capacity it costs, regardless of provider health. Reuses `RollingRatio`,
+ * the same primitive `RollingTripping` is built on, rather than a second
+ * hand rolled window.
+ */
+declare class RetryBudget {
+  private readonly options;
+  private readonly ratio;
+  constructor(options: RetryBudgetOptions);
+  /**
+   * Throws `LLMError('retry_budget_exhausted')` once at least `minCalls`
+   * calls have landed in the trailing `windowMs` and the retry ratio
+   * among them has reached `retryRatio`. A no-op otherwise.
+   */
+  assertAvailable(): void;
+  /** Records one attempt. `isRetry` is false for a call's first attempt, true for every attempt after it. */
+  recordAttempt(isRetry: boolean): void;
+  /** Current traffic and retry ratio in the trailing window. */
+  getSnapshot(): {
+    attempts: number;
+    retryRatio: number;
+  };
+}
+//#endregion
+//#region src/internal/utils/rateLimitHint.utils.d.ts
+/** A normalized read of a provider's rate limit headers. */
+interface ProviderRateLimitHint {
+  remainingRequests?: number;
+  limitRequests?: number;
+  resetAfterMs?: number;
 }
-
 //#endregion
 //#region src/rateLimit.d.ts
-//# sourceMappingURL=circuitBreaker.d.ts.map
 /** The request shape sent to `LLMClient['chat']['completions']['create']`, used for token estimation. */
 type WireRequest = Parameters<LLMClient['chat']['completions']['create']>[0];
 /** Which configured bucket is currently blocking a call. */
@@ -427,6 +826,27 @@ interface RateLimitOptions {
    * chars/4 heuristic over message content plus `max_tokens`.
    */
   estimateTokens?: (request: WireRequest) => number;
+  /**
+   * AIMD against the `requestsPerMinute` bucket. Omit for a fixed
+   * ceiling, today's behavior. Requires `requestsPerMinute`.
+   */
+  aimd?: AimdOptions;
+}
+interface AimdOptions {
+  /** Added to the requests-per-minute ceiling on every clean release. */
+  increaseBy: number;
+  /** Multiplied against the ceiling on a rate-limit signal. Must be in `(0, 1]`; clamped otherwise. */
+  decreaseFactor: number;
+  /** Floor the ceiling never shrinks below. */
+  minCapacity: number;
+  /** Ceiling the bucket never grows above. */
+  maxCapacity: number;
+  /**
+   * Shrink proactively once a provider hint reports `remainingRequests`
+   * at or below this, before a real 429 happens. Default 0, meaning
+   * off.
+   */
+  proactiveFloor?: number;
 }
 interface RateLimitAcquireResult {
   /**
@@ -435,7 +855,7 @@ interface RateLimitAcquireResult {
    * Idempotent: only the first call does anything. Must run in a
    * `finally` block so a slot is never leaked on a failed attempt.
    */
-  release: (actualTokens?: number) => void;
+  release: (actualTokens?: number, success?: boolean) => void;
   /** How long this attempt waited in queue before capacity was available. */
   waitedMs: number;
   /** Which bucket was blocking this attempt just before it cleared, if any wait happened. */
@@ -443,19 +863,35 @@ interface RateLimitAcquireResult {
 }
 /** Default `estimateTokens`: chars/4 over every message's content, plus the requested `max_tokens`. */
 declare function defaultEstimateTokens(request: WireRequest): number;
+/**
+ * What VernLLM's dispatch layer needs from a limiter. `RateLimiter`
+ * implements this; a caller wanting cross-process coordination can hand
+ * over their own instance instead, see `buildRateLimit`. Every method is
+ * required, `RateLimiter` itself already no-ops the AIMD methods when
+ * `aimd` isn't configured, so a custom limiter follows the same pattern.
+ */
+interface RateLimiterAdapter {
+  estimate(request: WireRequest): number;
+  acquire(estimatedTokens: number, signal?: AbortSignal): Promise<RateLimitAcquireResult>;
+  signalRateLimit(): void;
+  reactToRateLimitHint(hint: ProviderRateLimitHint | undefined): void;
+}
 /**
  * Per-target rate limiter. Up to three buckets (requests/min, tokens/min,
  * concurrency) behind one FIFO queue, so a large call isn't starved by a
  * stream of small ones. Any bucket omitted from `options` has infinite
  * capacity and never blocks.
  */
-declare class RateLimiter {
+declare class RateLimiter implements RateLimiterAdapter {
   private readonly requests?;
   private readonly tokens?;
   private readonly concurrency?;
+  /** Buckets in acquire precedence order (concurrency, rpm, tpm), omitted ones filtered out. Built once so order can't drift between `tryAcquireBuckets` and `scheduleWake`. */
+  private readonly buckets;
   private readonly maxQueueMs;
   private readonly maxQueueSize;
   private readonly estimateTokensFn;
+  private readonly aimd?;
   private readonly queue;
   /**
    * A single scheduled re-check for the head of the queue when it's
@@ -476,12 +912,7 @@ declare class RateLimiter {
   acquire(estimatedTokens: number, signal?: AbortSignal): Promise<RateLimitAcquireResult>;
   private queueFullError;
   private enqueue;
-  /**
-   * Checks and takes from every configured bucket as one atomic unit: if
-   * any bucket lacks capacity, whatever was already taken from the
-   * earlier ones in this attempt is rolled back before reporting which
-   * bucket blocked.
-   */
+  /** Takes from every configured bucket as one atomic unit, in `this.buckets`' order. Rolls back whatever was already taken if any bucket lacks capacity. */
   private tryAcquireBuckets;
   /** Drains the queue head first. Stops at the first waiter that still can't proceed, so no one is starved out of turn. */
   private drain;
@@ -498,13 +929,37 @@ declare class RateLimiter {
    * bucket is a real spend that only recovers via its own refill, and the
    * tokens bucket is reconciled against `actualTokens` rather than fully
    * refunded, since real tokens really were spent.
+   *
+   * `success` defaults to `false`: the AIMD ceiling only grows when the
+   * caller explicitly confirms a successful attempt. A failed or
+   * rate-limited attempt still releases its slot (so nothing leaks), but
+   * must not also grow the ceiling right back up after
+   * `signalRateLimit()` just shrank it.
    */
   private makeRelease;
+  /** Shared guard and resize call behind both AIMD halves below; only the arithmetic differs. */
+  private resizeRequestsCeiling;
+  /** AIMD's additive-increase half: grows the ceiling by `aimd.increaseBy` on a clean release. No-op without `aimd`/`requestsPerMinute`. */
+  private growOnSuccess;
+  /**
+   * AIMD's multiplicative-decrease half. Called on a real 429, and,
+   * where an adapter can produce a hint, proactively via
+   * `reactToRateLimitHint`. Never throws or blocks a call itself, only
+   * adjusts the ceiling as a side effect.
+   */
+  signalRateLimit(): void;
+  /**
+   * AIMD's proactive entry point: shrinks via `signalRateLimit()` if
+   * `hint.remainingRequests` is at or below `aimd.proactiveFloor`.
+   */
+  reactToRateLimitHint(hint: ProviderRateLimitHint | undefined): void;
 }
-
+//#endregion
+//#region src/internal/utils/rateLimitAdapter.utils.d.ts
+/** Not exported. Internal shorthand only, so this union isn't duplicated between the public option fields and `buildRateLimit`'s own signature. */
+type RateLimitOption = RateLimitOptions | RateLimiterAdapter;
 //#endregion
 //#region src/types/fallback.d.ts
-//# sourceMappingURL=rateLimit.d.ts.map
 /**
  * One provider to try after the primary (or after an earlier fallback
  * target) fails. Order is the policy: VernLLM never reorders, scores, or
@@ -513,11 +968,11 @@ declare class RateLimiter {
  * Most per-target overrides fall back to the parent `VernLLM` instance's
  * own option when omitted, so a target only needs to specify what's
  * actually different about it (a different client/model is the common
- * case). `circuitBreaker` and `rateLimit` are the exception: they are
- * never inherited from the parent, since a breaker or limiter tuned for
- * the primary provider's limits is rarely right for a fallback's. Leave
- * them unset on a target to run it without one, even if the parent has
- * one configured.
+ * case). `circuitBreaker`, `rateLimit`, and `retryBudget` are the
+ * exception: they are never inherited from the parent, since a breaker,
+ * limiter, or budget tuned for the primary provider's limits is rarely
+ * right for a fallback's. Leave them unset on a target to run it without
+ * one, even if the parent has one configured.
  */
 interface FallbackTarget {
   client: LLMClient;
@@ -536,7 +991,16 @@ interface FallbackTarget {
   /** This target's own circuit breaker, independent of every other target's. Not inherited from the parent's `circuitBreaker`. */
   circuitBreaker?: boolean | CircuitBreakerOptions;
   /** This target's own rate limiter, independent of every other target's. Not inherited from the parent's `rateLimit`. */
-  rateLimit?: RateLimitOptions;
+  rateLimit?: RateLimitOption;
+  /** This target's own retry budget, independent of every other target's. Not inherited from the parent's `retryBudget`. */
+  retryBudget?: RetryBudgetOptions;
+  /**
+   * Reclassifies an otherwise-successful result from this target as a
+   * failure. Falls back to the parent `VernLLM` instance's own
+   * `detectSoftFailure` when omitted, same as most other per-target
+   * options (unlike `circuitBreaker`/`rateLimit`, which never inherit).
+   */
+  detectSoftFailure?: DetectSoftFailure;
 }
 /**
  * Written into `CallParams['meta']` once `call()` resolves, so a caller
@@ -616,10 +1080,21 @@ declare class FallbackExhaustedError extends LLMError {
 }
 /** Narrows `err` to {@link FallbackExhaustedError}, for direct access to its `attempts` (`provider`/`model` per failed target) without a manual `instanceof` check. */
 declare function isFallbackExhaustedError(err: unknown): err is FallbackExhaustedError;
-
+/**
+ * Creates an empty ref box to pass as `CallParams['meta']`, so a caller can
+ * read the `CallMeta` written by `call()` on the same line as the result
+ * instead of pre-declaring a `{ current?: CallMeta }` by hand.
+ *
+ * @example
+ * const meta = metaRef();
+ * const result = await vern.call({ userContent: '...', meta });
+ * meta.current?.provider;
+ */
+declare function metaRef(): {
+  current?: CallMeta;
+};
 //#endregion
 //#region src/types/schema.d.ts
-//# sourceMappingURL=fallback.d.ts.map
 /**
  * Minimal structural type for a Zod-like schema, so this package doesnt need
  * a hard dependency on a specific Zod major version. Any object exposing
@@ -649,10 +1124,8 @@ interface JsonSchemaSpec {
   strict?: boolean;
   description?: string;
 }
-
 //#endregion
 //#region src/types/tools.d.ts
-//# sourceMappingURL=schema.d.ts.map
 /**
  * Describes a capability the model may request, not the capability
  * itself. VernLLM transports this to the provider and parses what comes
@@ -687,7 +1160,7 @@ interface ToolDefinition<Name extends string = string, Args = unknown> {
  * to `string` unless annotated `as const`, which silently defeats
  * `ToolCall` narrowing the moment a second tool is added to the same
  * `tools: [...]` array (single-tool arrays still narrow fine even without
- * this, since there's nothing to discriminate against — but that stops
+ * this, since there's nothing to discriminate against but that stops
  * being true as soon as a second tool shows up). Wrapping the same object
  * in `defineTool()` preserves the literal `name` type without requiring
  * `as const` at every call site.
@@ -704,7 +1177,7 @@ type ToolCallFor<T> = T extends ToolDefinition<infer N, infer A> ? {
  *
  * When `Tools` is a literal tuple (e.g. inferred from `tools: [getWeather,
  * cancelOrder]` at a `call()`/`cachedCall()` site), this is a discriminated
- * union keyed by `name` — checking `call.name === 'get_weather'` narrows
+ * union keyed by `name`. Checking `call.name === 'get_weather'` narrows
  * `call.arguments` to that tool's `Args` with no cast needed. Without a
  * literal `Tools` (the default), this collapses back to today's
  * `{ id: string; name: string; arguments: unknown }`.
@@ -803,7 +1276,6 @@ declare function isToolCallResult<Tools extends readonly ToolDefinition[] | unde
 type ToolChoice = 'auto' | 'none' | 'required' | {
   name: string;
 };
-
 //#endregion
 //#region src/types/usage.d.ts
 type ReserveUsage = (params: {
@@ -869,10 +1341,8 @@ type OnUsage = (usage: TokenUsage) => void;
  * to report.
  */
 type OnUsageFailure = (usage: TokenUsage, error: LLMError) => void;
-
 //#endregion
 //#region src/types/call.d.ts
-//# sourceMappingURL=usage.d.ts.map
 /**
  * Any valid JSON value: a primitive, `null`, or a JSON array/object made
  * of the same. This is what `call()` returns when `jsonMode: true`.
@@ -928,13 +1398,21 @@ interface ImageBlock {
 }
 /** A single segment of multimodal `userContent`. */
 type ContentBlock = TextBlock | ImageBlock;
-interface CallParams<T = unknown, Tools extends readonly ToolDefinition[] = ToolDefinition[]> extends UsageHooks {
+/**
+ * Every field of a call request except the `reserveUsage`/`refundUsage`
+ * hooks from `UsageHooks`. `CallParams` is this plus `UsageHooks`; the
+ * `Cached*` param types below are call sites that want the request shape
+ * without those two hooks (usage is metered once, at the `cachedCall`
+ * level, not per-request), and use this directly instead of re-deriving
+ * it with `Omit<CallParams<T>, 'reserveUsage' | 'refundUsage'>` each time.
+ */
+interface LLMRequestShape<T = unknown, Tools extends readonly ToolDefinition[] = ToolDefinition[]> {
   systemPrompt?: string;
   /** Current user message, as text or multimodal content blocks. */
   userContent: string | ContentBlock[];
   /**
    * Previous conversation turns. Must alternate roles; tool turns must follow
-   * assistant tool calls. Invalid history throws LLMError('validation').
+   * assistant tool calls. Invalid history throws LLMError('invalid_params').
    */
   history?: ConversationTurn[];
   /**
@@ -947,6 +1425,20 @@ interface CallParams<T = unknown, Tools extends readonly ToolDefinition[] = Tool
   maxTokens?: number;
   requestId?: string;
   signal?: AbortSignal;
+  /**
+   * Total time budget in ms for this whole call, across every retry and
+   * every fallback target. Unlike timeoutMs, which resets on each attempt,
+   * this is a single clock starting when call is invoked. The call is
+   * aborted once this elapses, even mid retry or mid fallback, the same
+   * way an aborted signal is today. Omit for no overall deadline, only
+   * the existing per attempt timeoutMs applies.
+   *
+   * Only bounds getting to a final result: choosing a target, retrying,
+   * and opening a stream. It does not extend to the time spent reading a
+   * stream after it has opened. Use chunkIdleTimeoutMs for gaps between
+   * chunks once a stream is open.
+   */
+  deadlineMs?: number;
   /**
    * Per-call override for the instance's `chunkIdleTimeoutMs` (max gap
    * between stream chunks once opened). Only applies when `stream: true`.
@@ -1019,15 +1511,24 @@ interface CallParams<T = unknown, Tools extends readonly ToolDefinition[] = Tool
    * Optional out-parameter for provider identity. Pass `{}` (or any object
    * with a mutable `current` property) and `call()` writes a `CallMeta`
    * into `meta.current` before returning, alongside whatever `onUsage`
-   * already reports. Ignored for `stream: true`, since `call()` returns
-   * before the outcome (and so the target that answered) is known; read
-   * `TokenUsage.provider`/`usedFallback` from `onUsage` for streaming
-   * calls instead.
+   * already reports. This includes `stream: true`: the target is chosen
+   * once the stream opens, which is also the point `call()` itself
+   * returns `{ chunks, finalResult }`, so `meta.current` is already set
+   * by then. `TokenUsage.provider`/`usedFallback` from `onUsage` reports
+   * the same information asynchronously, for both streaming and
+   * non-streaming calls.
+   *
+   * `meta.current` is only written once execution actually reaches and
+   * selects a provider target. A `wrap` middleware that short-circuits
+   * without calling `next()` never reaches that point, so `meta.current`
+   * is left untouched; if the same holder object is reused across calls,
+   * it can still hold a prior call's target.
    */
   meta?: {
     current?: CallMeta;
   };
 }
+interface CallParams<T = unknown, Tools extends readonly ToolDefinition[] = ToolDefinition[]> extends LLMRequestShape<T, Tools>, UsageHooks {}
 /**
  * A `CallParams` variant where tool calling is explicitly enabled.
  *
@@ -1119,7 +1620,7 @@ interface CachedCallInput extends UsageHooks {
  * the caching docs for why.
  */
 type CachedCallParams<T> = CachedCallInput & {
-  call: Omit<CallParams<T>, 'reserveUsage' | 'refundUsage'>;
+  call: LLMRequestShape<T>;
 };
 /**
  * Parameters for a cached LLM call with tool calling enabled.
@@ -1132,7 +1633,9 @@ type CachedCallParams<T> = CachedCallInput & {
  * from `call`'s type here too.
  */
 type CachedToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
-  call: Omit<ToolEnabledCallParams<T, Tools>, 'reserveUsage' | 'refundUsage'>;
+  call: LLMRequestShape<T, Tools> & {
+    tools: NonNullable<LLMRequestShape<T, Tools>['tools']>;
+  };
 };
 /**
  * Parameters for a cached LLM call with `call.tools` set conditionally.
@@ -1141,7 +1644,9 @@ type CachedToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefin
  * `ConditionalToolCallParams` for why this overload exists.
  */
 type CachedConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
-  call: Omit<ConditionalToolCallParams<T, Tools>, 'reserveUsage' | 'refundUsage'>;
+  call: LLMRequestShape<T, Tools> & {
+    tools: Tools | undefined;
+  };
 };
 /** Cached conditional tool-call parameters whose non-tool result is plain text. */
 type CachedConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedConditionalToolCallParams<string, Tools> & {
@@ -1154,19 +1659,41 @@ type CachedConditionalStringToolCallParams<Tools extends readonly ToolDefinition
  * `cachedCall()` overload that returns a plain `string`.
  */
 type CachedJsonModeDisabledCallParams = CachedCallInput & {
-  call: Omit<JsonModeDisabledCallParams, 'reserveUsage' | 'refundUsage'>;
+  call: Omit<LLMRequestShape<unknown>, 'jsonSchema'> & {
+    jsonMode: false;
+    jsonSchema?: never;
+  };
 };
 /**
  * Parameters for a cached LLM call with `jsonMode: true` and no `schema`.
  * Selects the `cachedCall()` overload that returns a `JsonValue`.
  */
 type CachedJsonModeEnabledCallParams = CachedCallInput & {
-  call: Omit<JsonModeEnabledCallParams, 'reserveUsage' | 'refundUsage'>;
+  call: Omit<LLMRequestShape<JsonValue>, 'schema'> & {
+    jsonMode: true;
+    schema?: never;
+  };
 };
-
+/** Context handed to `DetectSoftFailure` alongside the response it's inspecting. */
+interface SoftFailureMeta {
+  requestId: string;
+  model: string;
+  providerName: string;
+  isFallback: boolean;
+  /** 1-based, matching `CallMeta.attempts`. */
+  attempt: number;
+}
+/**
+ * Inspects an otherwise-successful result and optionally reclassifies it
+ * as a failure. Returning `undefined` leaves the result as a success;
+ * returning an `LLMErrorCode` fails the attempt with that code, feeding
+ * the same retry and circuit-breaker paths a thrown error would. A
+ * result that parses fine but is empty, truncated, or a low-confidence
+ * refusal is otherwise invisible to both.
+ */
+type DetectSoftFailure<T = unknown> = (result: T | CallWithToolsResult<T>, meta: SoftFailureMeta) => LLMErrorCode | undefined;
 //#endregion
 //#region src/types/stream.d.ts
-//# sourceMappingURL=call.d.ts.map
 /** One incremental unit of a streaming response, as delivered to the caller. */
 type StreamChunk = {
   type: 'text-delta';
@@ -1271,6 +1798,18 @@ type WireStreamChunk = {
    * Never surfaced to callers as a `StreamChunk`.
    */
   type: 'ping';
+} | {
+  /**
+   * AIMD's proactive rate-limit hint, read off the stream's
+   * response headers (where the adapter/SDK can get at them) and
+   * yielded once, as early as possible. Mirrors `attachRateLimitHint`
+   * for the non-streaming path, just carried as a chunk instead of a
+   * hidden property on a response object, since a stream has no
+   * single response value to attach one to. Never surfaced to
+   * callers as a `StreamChunk`.
+   */
+  type: 'rate_limit_hint';
+  hint: ProviderRateLimitHint;
 };
 /**
  * Parameters for a cached, streaming LLM call without tool calling.
@@ -1282,10 +1821,12 @@ type WireStreamChunk = {
  * like).
  *
  * `reserveUsage`/`refundUsage` are omitted from `call`'s type; see
- * `CachedCallParams` for why — they belong at the top level here too.
+ * `CachedCallParams` for why they belong at the top level here too.
  */
 type CachedStreamCallParams<T> = CachedCallInput & {
-  call: Omit<StreamEnabledCallParams<T>, 'reserveUsage' | 'refundUsage'>;
+  call: LLMRequestShape<T> & {
+    stream: true;
+  };
 };
 /**
  * Parameters for a cached, streaming LLM call with tool calling enabled.
@@ -1295,7 +1836,10 @@ type CachedStreamCallParams<T> = CachedCallInput & {
  * replayed-chunks-on-hit behavior as `CachedStreamCallParams<T>`.
  */
 type CachedStreamToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
-  call: Omit<StreamEnabledCallParams<T, Tools> & ToolEnabledCallParams<T, Tools>, 'reserveUsage' | 'refundUsage'>;
+  call: LLMRequestShape<T, Tools> & {
+    stream: true;
+    tools: NonNullable<LLMRequestShape<T, Tools>['tools']>;
+  };
 };
 /**
  * Parameters for a cached, streaming LLM call with `call.tools` set
@@ -1305,7 +1849,10 @@ type CachedStreamToolCallParams<T, Tools extends readonly ToolDefinition[] = Too
  * `ConditionalToolCallParams` for why this overload exists.
  */
 type CachedStreamConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
-  call: Omit<StreamEnabledCallParams<T, Tools> & ConditionalToolCallParams<T, Tools>, 'reserveUsage' | 'refundUsage'>;
+  call: LLMRequestShape<T, Tools> & {
+    stream: true;
+    tools: Tools | undefined;
+  };
 };
 /** Cached streaming conditional tool-call parameters whose non-tool result is text. */
 type CachedStreamConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedStreamConditionalToolCallParams<string, Tools> & {
@@ -1319,7 +1866,11 @@ type CachedStreamConditionalStringToolCallParams<Tools extends readonly ToolDefi
  * cached value (on a hit) is a plain `string`.
  */
 type CachedStreamJsonModeDisabledCallParams = CachedCallInput & {
-  call: Omit<StreamJsonModeDisabledCallParams, 'reserveUsage' | 'refundUsage'>;
+  call: Omit<LLMRequestShape<unknown>, 'jsonSchema'> & {
+    stream: true;
+    jsonMode: false;
+    jsonSchema?: never;
+  };
 };
 /**
  * Parameters for a cached, streaming LLM call with `jsonMode: true` and no
@@ -1327,12 +1878,14 @@ type CachedStreamJsonModeDisabledCallParams = CachedCallInput & {
  * miss) or cached value (on a hit) is a `JsonValue`.
  */
 type CachedStreamJsonModeEnabledCallParams = CachedCallInput & {
-  call: Omit<StreamJsonModeEnabledCallParams, 'reserveUsage' | 'refundUsage'>;
+  call: Omit<LLMRequestShape<JsonValue>, 'schema'> & {
+    stream: true;
+    jsonMode: true;
+    schema?: never;
+  };
 };
-
 //#endregion
 //#region src/types/client.d.ts
-//# sourceMappingURL=stream.d.ts.map
 /** A tool call as it appears on the wire, OpenAI's `function`-wrapped shape. */
 interface WireToolCall {
   id: string;
@@ -1462,10 +2015,20 @@ interface LLMClient {
     };
   };
 }
-
+//#endregion
+//#region src/internal/utils/cacheAdapter.utils.d.ts
+/**
+ * Not exported. Internal shorthand for `VernLLMOptions.cache`, so the
+ * union isn't duplicated between that field and `buildCache`'s own
+ * signature. A caller never writes this type by name, either a config
+ * object literal or a real `CacheAdapter`.
+ */
+type CacheOption = {
+  maxSize?: number;
+  eviction?: EvictionOption;
+} | CacheAdapter;
 //#endregion
 //#region src/logger.d.ts
-//# sourceMappingURL=client.d.ts.map
 interface Logger {
   debug(message: string): void;
   warn(message: string): void;
@@ -1482,73 +2045,8 @@ declare class ConsoleLogger implements Logger {
   warn(message: string): void;
   error(message: string, meta?: Record<string, unknown>): void;
 }
-
-//#endregion
-//#region src/types/events.d.ts
-//# sourceMappingURL=logger.d.ts.map
-/**
- * Reports what happened during a call. Fire and forget, mirroring
- * `onUsage`: the return value is never read and a throwing handler cannot
- * change what the call does, only what gets reported about it.
- */
-type VernLLMEvent = {
-  kind: 'retry';
-  requestId: string;
-  provider: string;
-  /** The model actually resolved for this call (honors a per-call `model` override). */
-  model: string;
-  /** The 1-based retry ordinal (the 1st retry is `1`, not the overall attempt count). */
-  attempt: number;
-  maxRetries: number;
-  delayMs: number;
-  retryAfterHonored: boolean;
-  error: LLMError;
-} | {
-  kind: 'circuit_state';
-  provider: string;
-  /**
-   * The model of the call that triggered this specific transition
-   * (whatever was passed to the `assertClosed`/`recordSuccess`/
-   * `recordFailure` call that caused it), not a property of the
-   * circuit itself: the breaker still counts failures across every
-   * model together, so a threshold crossing can be the sum of
-   * several different models' failures even though only the
-   * triggering call's `model` is reported here.
-   */
-  model: string;
-  from: CircuitState;
-  to: CircuitState;
-  consecutiveFailures: number;
-} | {
-  kind: 'fallback';
-  requestId: string;
-  /** Provider name of the target that just failed. */
-  from: string;
-  /** Provider name of the target about to be tried next. */
-  to: string;
-  /** `-1` for the primary target, otherwise the index into `fallback`. */
-  fromIndex: number;
-  toIndex: number;
-  /** The normalized error that caused `from` to be abandoned. */
-  error: LLMError;
-  /** Time spent on `from`, including its own retries, before giving up. */
-  elapsedMs: number;
-} | {
-  kind: 'rate_limited';
-  requestId: string;
-  provider: string;
-  /** The model actually resolved for this call (honors a per-call `model` override). */
-  model: string;
-  /** How long this attempt sat queued for capacity before it was let through. */
-  waitedMs: number;
-  /** Which configured bucket was blocking this attempt just before it cleared. */
-  reason: 'concurrency' | 'rpm' | 'tpm';
-};
-type OnEvent = (event: VernLLMEvent) => void;
-
 //#endregion
 //#region src/types/options.d.ts
-//# sourceMappingURL=events.d.ts.map
 interface VernLLMOptions {
   client: LLMClient;
   model: string;
@@ -1617,8 +2115,24 @@ interface VernLLMOptions {
    * (no redaction).
    */
   redact?: (text: string) => string;
-  /** Cache adapter for cachedCall. Defaults to an in-memory adapter */
-  cache?: CacheAdapter;
+  /**
+   * Cache for cachedCall. `{ maxSize, eviction }` configures the
+   * built-in in-memory adapter (`eviction` default `'fifo'`). Pass a
+   * `CacheAdapter` directly for a real backend. Default: in-memory,
+   * maxSize 1000, fifo.
+   */
+  cache?: CacheOption;
+  /**
+   * Reclassifies an otherwise-successful result as a failure, e.g. a
+   * response that parsed fine but came back empty or truncated. Runs
+   * once per attempt, right after a response is validated. Returning
+   * `undefined` leaves the result untouched; returning an
+   * `LLMErrorCode` fails that attempt with it, feeding the same retry
+   * and circuit-breaker paths a thrown error would. A throwing hook is
+   * caught, logged, and treated as no soft failure, so a broken hook
+   * degrades safely instead of failing every call.
+   */
+  detectSoftFailure?: DetectSoftFailure;
   /** HTTP status codes that should fail fast without retrying. Default [400, 401, 403, 404, 422] */
   nonRetryableStatus?: number[];
   /** Custom JSON parser. Must return undefined/null on failure. Default: JSON.parse wrapped in try/catch */
@@ -1657,8 +2171,22 @@ interface VernLLMOptions {
    * letting the provider reject them. Independent of the `Retry-After`
    * handling already applied to a provider 429: this avoids tripping the
    * limit in the first place. Omit for unlimited (the default).
+   *
+   * A plain config object builds an in-process limiter. Pass a
+   * `RateLimiterAdapter` instead for cross-process coordination.
+   */
+  rateLimit?: RateLimitOption;
+  /**
+   * Caps how much of this target's recent traffic is allowed to be
+   * retries, independent of `circuitBreaker`. Once at least `minCalls`
+   * calls have landed in the trailing `windowMs` and the retry ratio
+   * among them reaches `retryRatio`, further retries against this target
+   * throw `LLMError('retry_budget_exhausted')` instead of retrying,
+   * protecting the target's real capacity even while its breaker is
+   * still closed. Omit for no budget (the default). Never inherited by
+   * `fallback` targets, same as `circuitBreaker`/`rateLimit`.
    */
-  rateLimit?: RateLimitOptions;
+  retryBudget?: RetryBudgetOptions;
   /**
    * Ordered targets tried after the primary, in order, once it (and its
    * own retries) is exhausted or abandoned. Order is the policy: VernLLM
@@ -1680,11 +2208,57 @@ interface VernLLMOptions {
    * and moves on for everything else.
    */
   fallbackOn?: FallbackOn;
+  /**
+   * Transforms outgoing requests and/or wraps whole logical calls,
+   * without touching retry, circuit breaker, or fallback internals.
+   * Defaults to an empty array. See `VernLLMMiddleware` for the four
+   * available hooks (`transform`, `wrap`, `onEvent`, `enabled`).
+   */
+  middleware?: VernLLMMiddleware[];
+  /**
+   * Bounds `transform` and a function `enabled`, the same way every
+   * other blocking operation in the package is already bounded.
+   * Overridable per middleware via that entry's own `timeoutMs`.
+   * `<= 0` means unbounded (no timer at all). Default 5000.
+   */
+  middlewareTimeoutMs?: number;
 }
-
+//#endregion
+//#region src/types/createMiddleware.d.ts
+/**
+ * `VernLLMMiddleware` plus `onError`, a convenience for the common "I
+ * only care about failures" case. Everything else is passed through to
+ * the resulting `VernLLMMiddleware` unchanged; setting `wrap` directly
+ * alongside `onError` is an error, since `onError` builds its own `wrap`
+ * under the hood, and building it around a `wrap` you also supplied
+ * would silently drop one of the two.
+ */
+type CreateMiddlewareOptions = Omit<VernLLMMiddleware, 'wrap'> & {
+  wrap?: undefined;
+  /**
+   * Called with this call's terminal error, if it fails: the same error
+   * `wrap`'s own `next()` would reject with. Never called on success,
+   * and never called for a failure some *other* middleware's `wrap`
+   * already swallowed by short-circuiting with its own `CallResult`.
+   * The original error is always rethrown afterward, `onError` only
+   * observes it, exactly like `onUsage`/`onEvent` elsewhere: a throwing
+   * `onError` is discarded (not logged, this helper has no `Logger` of
+   * its own to log through) and otherwise has no effect on the call.
+   * `ctx` is `wrap`'s own pre-dispatch context (`onError` builds a `wrap`
+   * under the hood), so it only describes the primary target.
+   */
+  onError?: (error: LLMError, ctx: PreDispatchContext) => void | Promise<void>;
+};
+/**
+ * Builds a `VernLLMMiddleware` entry. Plain pass-through when `onError`
+ * is omitted; when it's set, wraps it in a `wrap` that calls `next()`,
+ * reports `onError` on a rejection, and always rethrows the original
+ * error afterward, so `onError` never changes what the call itself
+ * returns or throws, only what gets observed about it.
+ */
+declare function createMiddleware(options: CreateMiddlewareOptions): VernLLMMiddleware;
 //#endregion
 //#region src/vernLLM.d.ts
-//# sourceMappingURL=options.d.ts.map
 /**
  * A LLM call framework for resilience, observability and control. This is VernLLM!
  *
@@ -1698,21 +2272,37 @@ declare class VernLLM {
   /**
    * One `CallExecutor` per provider target: index 0 is the primary,
    * everything after it is a `fallback` target, in the order declared.
-   * Each owns its own request building, retry/timeout, circuit breaker,
-   * and rate limiter. `call()` walks this array in `runFallbackChain`,
-   * moving to the next entry only when `fallbackOn` says to.
+   * Walked by `runFallbackChain`, moving to the next entry only when
+   * `fallbackOn` says to.
    */
   private readonly executors;
   /** Decides whether a failed target is followed by the next one or the chain stops. See `VernLLMOptions['fallbackOn']`. */
   private readonly fallbackOn;
   /** Reports a `'fallback'` event when the chain moves to the next target. Shared `onEvent` plumbing, same as every executor's. */
   private readonly reportEvent;
+  /** Owns cache reads/writes and in-flight coalescing for `cachedCall()`. Only calls back into `this.call()` as an opaque function. */
+  private readonly cacheOrchestrator;
+  /** See `VernLLMOptions.middleware`. Sorted once here by `priority`, ascending, ties broken by original array order. */
+  private readonly middleware;
+  /** See `VernLLMOptions.middlewareTimeoutMs`. Bounds `transform` and a function `enabled`; `wrap` itself is never bounded by this. */
+  private readonly middlewareTimeoutMs;
   /**
-   * Owns cache key resolution, cache reads/writes, and in-flight
-   * coalescing for `cachedCall()`. Independent of `executor`: it only
-   * ever calls back into `this.call()` as an opaque function.
+   * Maps `cachedCall()`'s inner `this.call(...)` params to its own
+   * `middlewareState`, so that call's own `runOperation` skips wrapping
+   * again and reuses the same state bag `wrap` just ran with (so a
+   * value `wrap` sets is visible to `transform`, same as a direct
+   * call). Keyed by object identity, not `requestId`, since two
+   * concurrent `cachedCall()`s can share an explicit `requestId`.
    */
-  private readonly cacheOrchestrator;
+  private readonly cachedCallInnerParams;
+  /**
+   * Shares one `CallMeta` holder across every `cachedCall()` in flight
+   * for the same resolved cache key, so a joining invocation (never
+   * calls `call()` itself) reports the trigger's real metadata instead
+   * of `undefined`. A true cache hit never creates an entry, so it
+   * still reports no metadata correctly.
+   */
+  private readonly cachedCallMeta;
   /**
    * @param options Client, model, and tunables. Defaults: `maxRetries` 1,
    * `timeoutMs` 25000, `baseDelayMs` 500, `defaultMaxTokens` 1000,
@@ -1722,72 +2312,23 @@ declare class VernLLM {
   constructor(options: VernLLMOptions);
   /** Logs a failed refundUsage attempt via the configured logger. */
   private logRefundError;
-  /**
-   * Walks `this.executors` in order, running `attempt` against each until
-   * one succeeds or every target has failed. `run` on a lone target
-   * (no `fallback` configured) throws exactly what it throws today: the
-   * loop's single iteration path is unchanged from pre-fallback behavior.
-   *
-   * For streaming, `attempt` is `executor.runStream`, whose own retries
-   * only cover *opening* the stream (see `CallExecutor.runStream`). A
-   * mid-stream failure surfaces through `finalResult` after this function
-   * has already returned, so it's never seen here and never falls over,
-   * per the streaming limitation: splicing a second model's output into a
-   * response the consumer has already partially rendered would corrupt
-   * it.
-   */
-  private runFallbackChain;
+  /** Everything `executeLogicalCall`/`executeLogicalStreamCall` (in `logicalCall.ts`) need from this instance, gathered once so `call()` doesn't rebuild it per invocation. */
+  private get logicalCallDependencies();
+  /** Everything `runOperation` (in `runOperation.ts`) needs from this instance, gathered once so `call()`/`cachedCall()` don't rebuild it per invocation. */
+  private get runOperationDependencies();
   /**
    * Makes a single logical LLM call, retrying on failure per the configured
    * policy. Fails fast if the breaker is open or the signal is already
-   * aborted. Rejects with a normalized LLMError on exhausted retries.
-   *
-   * When `tools` is set, returns a `CallWithToolsResult<T>` instead of `T`:
-   * `{ type: 'content', content }` or `{ type: 'tool_calls', toolCalls,
-   * content? }`. VernLLM never executes tools; run them yourself and
-   * continue via `history` (see `ConversationTurn`). Mutually exclusive
-   * with `jsonSchema`/`schema`.
-   *
-   * TypeScript picks the tools-aware overload (`CallWithToolsResult<T>`)
-   * when `tools` is a literal array on `params`, and the conditional-tools
-   * overload (`T | CallWithToolsResult<T>`, see `ConditionalToolCallParams`)
-   * when `tools` is present but statically `ToolDefinition[] | undefined`,
-   * e.g. `const tools = condition ? [myTool] : undefined`. Either way, use
-   * `isToolCallResult()` to narrow the result once `tools` isn't a literal
-   * array: TypeScript's static type can't know from the `ConditionalToolCallParams`
-   * shape alone whether tools actually ran on a given call. Only omitting
-   * `tools` entirely resolves to the plain `T` overload, since then tools
-   * genuinely cannot have run. See the Tool Calling docs for details.
+   * aborted. Rejects with a normalized `LLMError` on exhausted retries.
    *
-   * The same static-vs-dynamic caveat applies to `stream`: TypeScript only
-   * selects the streaming overload (returning `StreamCallResult<...>`) when
-   * `stream: true` is statically present on `params`. A `stream` value set
-   * conditionally on a plain `CallParams<T>` still resolves to `Promise<T>`
-   * (or `Promise<CallWithToolsResult<T>>`) at the type level even though
-   * the actual runtime result is the `{ chunks, finalResult }` streaming
-   * shape whenever `stream` evaluates to `true`, callers doing this should
-   * narrow/cast accordingly rather than relying on the static return type.
-   *
-   * Pinning `T` explicitly (`call<string>(...)`) alongside a literal
-   * `tools` array loses per-tool `arguments` typing: TypeScript's own
-   * generic inference rules mean providing *any* explicit type argument
-   * suppresses inference for every subsequent type parameter in that call,
-   * `Tools` included, regardless of its `const` modifier or default. This
-   * isn't specific to this overload, it's true of all TypeScript generic
-   * calls with a partial explicit type argument list. Pass `Tools`
-   * explicitly too when pinning `T` this way, e.g. `call<string, typeof
-   * myTools>(...)`, or prefer inferring `T` from `schema`/`jsonSchema`
-   * instead (which doesn't touch the type argument list, so `Tools` still
-   * infers normally).
+   * Supports `tools`, `stream`, and JSON mode/schema, in any combination.
+   * See the Tool Calling and Streaming docs for return-shape details and
+   * the TypeScript overloads that select between them.
    *
    * @param params System/user content plus per-call overrides. See `CallParams`.
-   * @returns Without `tools` or `stream`: the parsed response, or raw
-   * string if `jsonMode` is false. With `tools`: a `CallWithToolsResult<T>`,
-   * narrowed to `ContentResult<T>` when `toolChoice: 'none'` is set, since
-   * the model is then structurally barred from returning a `tool_calls`
-   * result. With `stream: true` (statically): a `{ chunks, finalResult }`
-   * `StreamCallResult`, `finalResult` resolving to whichever of the above
-   * shapes applies once the stream completes. See `StreamCallResult`.
+   * @returns The parsed response (or raw string if `jsonMode` is false), a
+   * `CallWithToolsResult<T>` when `tools` is set, or a `{ chunks,
+   * finalResult }` `StreamCallResult` when `stream: true`. See `StreamCallResult`.
    */
   call<T = unknown>(params: StreamEnabledCallParams<T> & ToolsDisabledCallParams<T>): Promise<StreamCallResult<ContentResult<T>>>;
   call<T = unknown, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: StreamEnabledCallParams<T, Tools> & ToolEnabledCallParams<T, Tools>): Promise<StreamCallResult<CallWithToolsResult<T, Tools>>>;
@@ -1821,35 +2362,19 @@ declare class VernLLM {
   deleteCache(key: string): Promise<void>;
   /**
    * Cache wrapper composing `call` + caching, so cached LLM calls
-   * automatically get retry/timeout/circuit-breaker behavior. `reserveUsage`/
-   * `refundUsage` are read from the top-level params only. Concurrent misses
-   * for the same `cacheKey` share a single in-flight call, avoiding cache
-   * stampedes. Supports `stream: true` and `tools` in any combination.
-   *
-   * When `call.tools` is set, this caches the whole `CallWithToolsResult`,
-   * including `tool_calls` results, not just final answers. Whether
-   * that's appropriate depends on the tool: caching "the model decided to
-   * call get_weather" is usually fine to reuse briefly, but caching a
-   * decision made under permissions or account state that can change
-   * between calls is not. Use a short `ttl` or a separate `cacheKey` for
-   * such tools if this distinction matters.
+   * automatically get retry/timeout/circuit-breaker behavior. Concurrent
+   * misses for the same `cacheKey` share a single in-flight call, avoiding
+   * cache stampedes. Supports `stream: true` and `tools` in any combination.
    *
-   * There is no public way to cache an arbitrary non-LLM function through
-   * `VernLLM`. This method always composes with `call()`. For
-   * general-purpose caching unrelated to an LLM call, use a dedicated
-   * caching library at the application level instead.
+   * When `call.tools` is set, this caches the whole result including any
+   * `tool_calls` decision, not just final answers; use a short `ttl` or a
+   * separate `cacheKey` if a tool's result shouldn't be reused across calls.
    *
-   * The same `T`-vs-`Tools` inference caveat documented on `call()` applies
-   * here too: pinning `T` explicitly (`cachedCall<string>(...)`) alongside
-   * a literal `call.tools` array loses per-tool `arguments` typing, pass
-   * `Tools` explicitly too in that case.
-   *
-   * @param params `cacheKey`, `ttl`, and optional
+   * @param params `cacheKey`, `ttl`, optional
    * `reserveUsage`/`refundUsage`/`signal`, plus `call`, the `CallParams`
-   * (optionally with `tools` and/or `stream`) to pass through to
-   * `this.call(...)`. The top-level `signal` governs the cached operation
-   * and its usage hooks only; to also abort the underlying provider
-   * request, set `signal` inside `call`.
+   * to pass through to `this.call(...)`. The top-level `signal` governs
+   * the cached operation and its usage hooks only; to also abort the
+   * underlying provider request, set `signal` inside `call`.
    * @returns The cached value on a hit, or the freshly-called result on a miss.
    */
   cachedCall<T, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedStreamToolCallParams<T, Tools>): Promise<StreamCallResult<CallWithToolsResult<T, Tools>>>;
@@ -1873,6 +2398,26 @@ declare class VernLLM {
    * target that doesn't exist.
    */
   getCircuitState(target?: CircuitTarget): CircuitState | undefined;
+  /**
+   * @param target.index Which target to read. Defaults to the primary.
+   * @param target.model Which model bucket to read, if the target isolates by model.
+   * @returns Failure counts by `LLMErrorCode`, `'unknown'` for a missing
+   * code, or `undefined` if that target has no breaker.
+   * @throws {RangeError} If `target.index` names no target.
+   */
+  getFailureBreakdown(target?: CircuitTarget): Partial<Record<LLMErrorCode | 'unknown', number>> | undefined;
+  /**
+   * @param target.index Which target to read. Defaults to the primary.
+   * @returns This target's current retry traffic/ratio in the trailing
+   * window, or `undefined` if that target has no retry budget
+   * configured. A budget is target-scoped, not model-scoped, so unlike
+   * `getFailureBreakdown` there's no `target.model` to pass.
+   * @throws {RangeError} If `target.index` names no target.
+   */
+  getRetryBudgetState(target?: Pick<CircuitTarget, 'index'>): {
+    attempts: number;
+    retryRatio: number;
+  } | undefined;
   /**
    * @param model Which model bucket to read, for targets that isolate by model.
    * @returns Every target's state, in chain order.
@@ -1896,11 +2441,9 @@ declare class VernLLM {
    * @throws {RangeError} If `target.index` names no target.
    */
   closeCircuit(target?: CircuitTarget): void;
-  /** Resolves a target index so every circuit-breaker method agrees on what counts as valid. */
-  private resolveExecutor;
-  /** Warns when `model` can't do anything on this target, so it's never silently ignored. */
-  private warnIfModelUnsupported;
 }
+//#endregion
+//#region src/paramsHelpers.d.ts
 /**
  * Identity function preserving `params`'s own precise type, unlike a `:
  * CallParams<T>` annotation, which would widen `tools` away and break the
@@ -1936,10 +2479,8 @@ declare function defineCallParams<P extends CallParams<unknown>>(params: P): P;
  * ```
  */
 declare function defineCachedCallParams<P extends CachedCallParams<unknown>>(params: P): P;
-
 //#endregion
 //#region src/adapters/internal/sse.d.ts
-//# sourceMappingURL=vernLLM.d.ts.map
 /**
  * Parses a Server-Sent-Events byte/text stream into the JSON payload of
  * each `data:` frame, in arrival order. Generic over transport: works with
@@ -1975,33 +2516,22 @@ declare function parseSseStream(source: AsyncIterable<Uint8Array | string>): Asy
  * alive" separately from a genuinely empty frame (`NO_DATA`, kept internal).
  */
 declare const SSE_PING: unique symbol;
-
 //#endregion
 //#region src/adapters/internal/imageFormat.d.ts
-//# sourceMappingURL=sse.d.ts.map
 /**
  * MIME types accepted for `ImageBlock.mimeType` across all adapters. This is
  * the intersection of what Anthropic, Gemini, OpenAI-compatible, and Bedrock
  * Converse all natively support, so a `ContentBlock[]` that validates for
  * one provider validates for all of them.
  */
-declare const SUPPORTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+declare const SUPPORTED_IMAGE_MIME_TYPES: readonly ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
 type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
-
 //#endregion
 //#region src/adapters/internal/nativeStructuredOutput.d.ts
-/**
- * Validates an `ImageBlock.mimeType` against the shared supported set.
- * Throws a non-retryable `LLMError('invalid_params')`, since an unsupported
- * mimeType is a bug in the caller's own input, deterministic before any
- * request is built, the same class of failure as every other check in
- * `RequestBuilder`.
- */
-
 /**
  * A static allow-list or predicate naming which models support native,
- * schema-constrained output as its own request field — Anthropic's
- * `output_config.format`, Bedrock's `outputConfig.textFormat` — separate
+ * schema-constrained output as its own request field. Anthropic's
+ * `output_config.format` and Bedrock's `outputConfig.textFormat` separate
  * from `tools`/`tool_choice`, so it can be combined with real,
  * caller-supplied `tools` in the same request.
  *
@@ -2018,10 +2548,8 @@ type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
  * exactly this package's behavior before native support was added.
  */
 type ModelCapabilityOverride = string[] | ((model: string) => boolean);
-
 //#endregion
 //#region src/adapters/internal/reasoningBudget.utils.d.ts
-/** Resolves whether `model` is covered by a caller-supplied allow-list/predicate. */
 /**
  * Shared conversion between the two reasoning controls VernLLM exposes:
  * `reasoningEffort` (a tier string, OpenAI's native shape) and
@@ -2042,7 +2570,6 @@ type ModelCapabilityOverride = string[] | ((model: string) => boolean);
  * doesn't match these numbers.
  */
 type EffortTokenTable = Record<'minimal' | 'low' | 'medium' | 'high', number>;
-
 //#endregion
 //#region src/adapters/anthropic.d.ts
 /** Anthropic's native per-block content shape for a message. */
@@ -2196,6 +2723,13 @@ interface AnthropicAdapterOptions {
    * predicate.
    */
   adaptiveOnlyModels?: ModelCapabilityOverride;
+  /**
+   * Whether the client's `messages.create` supports `.withResponse()`
+   * (needed for AIMD's proactive path). Default `false`, since
+   * `AnthropicClient` is structural and a test fake or thin wrapper
+   * won't implement it.
+   */
+  supportsWithResponse?: boolean;
 }
 /**
  * Wraps an Anthropic SDK client so it satisfies the same `LLMClient`
@@ -2229,7 +2763,6 @@ interface AnthropicAdapterOptions {
  * `output_config.format` or a forced tool call).
  */
 declare function fromAnthropic(anthropicClient: AnthropicClient, options?: AnthropicAdapterOptions): LLMClient;
-
 //#endregion
 //#region src/adapters/gemini.d.ts
 /**
@@ -2442,7 +2975,6 @@ interface GeminiAdapterOptions {
   thinkingLevelModels?: ModelCapabilityOverride;
 }
 declare function fromGemini(client: GeminiClient, options?: GeminiAdapterOptions): LLMClient;
-
 //#endregion
 //#region src/adapters/bedrock.d.ts
 /** Bedrock Converse's supported inline image formats. */
@@ -2677,7 +3209,7 @@ type BedrockConverseStreamEvent = {
 interface BedrockAdapterOptions {
   /**
    * Optional preflight check for tool-use support, needed whenever a
-   * `jsonSchema` call ends up sending Converse `toolConfig` — either the
+   * `jsonSchema` call ends up sending Converse `toolConfig`, either the
    * legacy forced-single-tool-call emulation, or real `tools` sent
    * alongside native structured output (`outputConfig`). VernLLM never
    * guesses capability from a failed call's error message (AWS's error
@@ -2802,7 +3334,6 @@ interface AwsSendClient {
  * `create` branch above unwraps it.
  */
 declare function fromBedrock(bedrockClient: BedrockConverseClient | AwsSendClient, options?: BedrockAdapterOptions): LLMClient;
-
 //#endregion
 //#region src/adapters/fetch.d.ts
 /** The chat-completion-shaped request VernLLM builds internally */
@@ -2920,6 +3451,11 @@ interface FetchAdapterConfig {
    * silently empty stream.
    */
   mapStreamEvent?: (event: unknown) => WireStreamChunk | WireStreamChunk[] | undefined;
+  /**
+   * Optional. How to read AIMD's proactive rate limit hint off a
+   * successful response. Defaults to OpenAI's header set.
+   */
+  parseRateLimitHint?: (headers: ResponseLike['headers']) => ProviderRateLimitHint;
 }
 /**
  * A fetch-based escape hatch for providers with no SDK, or where pulling one
@@ -2944,7 +3480,6 @@ interface FetchAdapterConfig {
  * `mapStreamEvent` seam via `WireStreamChunk`'s `tool_call_delta` variant,
  * no separate config is needed for streaming vs non-streaming tool calls.
  *
-
  * `createStream` requires `mapStreamEvent` (there's no non-streaming
  * response to fall back on, unlike the other three optional streaming
  * seams). It opens the request via `requestStream` (defaults to native
@@ -2961,7 +3496,6 @@ interface FetchAdapterConfig {
  * `fetch`.
  */
 declare function fromFetch(config: FetchAdapterConfig): LLMClient;
-
 //#endregion
 //#region src/adapters/openaiCompatible.d.ts
 /**
@@ -3021,6 +3555,12 @@ interface OpenAICompatibleAdapterOptions {
    * effect when `reasoningEffort` is set directly.
    */
   reasoningEffortTokens?: Partial<EffortTokenTable>;
+  /**
+   * Whether the client's request builder supports `.withResponse()`
+   * (needed for AIMD's proactive path). Default `false`, since not
+   * every "OpenAI-compatible" client is confirmed to support it.
+   */
+  supportsWithResponse?: boolean;
 }
 declare function fromOpenAICompatible(client: unknown, options?: OpenAICompatibleAdapterOptions): LLMClient;
 /**
@@ -3030,11 +3570,15 @@ declare function fromOpenAICompatible(client: unknown, options?: OpenAICompatibl
  * variant) in ways that no longer structurally satisfy VernLLM's
  * provider-agnostic `ContentBlock[]` on `userContent`, so passing the SDK
  * instance directly can fail to typecheck depending on the installed
- * `openai` version. Wrapping with `fromOpenAI()` (a plain alias of
- * `fromOpenAICompatible()`) sidesteps that by translating through
- * `unknown` at the boundary, and also picks up multimodal image
- * translation and `createStream` wiring that a raw client doesn't have.
- * See Migration Notes for details.
+ * `openai` version. Wrapping with `fromOpenAI()` sidesteps that by
+ * translating through `unknown` at the boundary, and also picks up
+ * multimodal image translation and `createStream` wiring that a raw
+ * client doesn't have. See Migration Notes for details.
+ *
+ * `supportsWithResponse` defaults to `false` here too:
+ * `client` is `unknown`, so there's no way to verify it's really the
+ * official `openai` package's client versus a fake or a test double.
+ * Pass `supportsWithResponse: true` once you've confirmed it.
  */
 declare const fromOpenAI: typeof fromOpenAICompatible;
 /** Groqs SDK matches the OpenAI wire format */
@@ -3128,9 +3672,6 @@ declare const fromInfermatic: typeof fromOpenAICompatible;
 declare const fromAtlasCloud: typeof fromOpenAICompatible;
 /** 01.AI's (Yi models) API is OpenAI-compatible */
 declare const from01AI: typeof fromOpenAICompatible;
-
 //#endregion
-//# sourceMappingURL=openaiCompatible.d.ts.map
-
-export { AnthropicClient, AssistantContent, BedrockConverseClient, CacheAdapter, CachedCallParams, CachedConditionalToolCallParams, CachedJsonModeDisabledCallParams, CachedJsonModeEnabledCallParams, CachedStreamCallParams, CachedStreamConditionalToolCallParams, CachedStreamJsonModeDisabledCallParams, CachedStreamJsonModeEnabledCallParams, CachedStreamToolCallParams, CachedToolCallParams, CallMeta, CallParams, CallWithToolsResult, CircuitBreaker, CircuitBreakerOptions, CircuitState, CircuitTarget, ConditionalToolCallParams, ConsoleLogger, ContentBlock, ContentResult, ConversationTurn, DuplicateToolNamesIssue, FallbackAttempt, FallbackExhaustedError, FallbackOn, FallbackTarget, FetchAdapterConfig, GeminiClient, HistoryToolResultIssue, ImageBlock, InMemoryCacheAdapter, JsonModeDisabledCallParams, JsonModeEnabledCallParams, JsonSchemaSpec, JsonValue, LLMClient, LLMError, LLMErrorCode, LLMErrorIssuesByCode, LLMErrorSnapshot, LLMErrorType, LLMRequestSnapshot, Logger, NormalizedCacheAdapter, OnEvent, OnUsage, RateLimitAcquireResult, RateLimitOptions, RateLimitReason, RateLimiter, RefundUsage, ReserveUsage, RetryAttempt, SSE_PING, SchemaLike, StreamCallResult, StreamChunk, StreamEnabledCallParams, StreamJsonModeDisabledCallParams, StreamJsonModeEnabledCallParams, TargetCircuitState, TextBlock, TieredCacheAdapter, TokenUsage, ToolCall, ToolCallResult, ToolChoice, ToolDefinition, ToolEnabledCallParams, ToolIssue, ToolResult, ToolsDisabledCallParams, UnknownToolChoiceIssue, UnsupportedCapabilityIssue, VernLLM, VernLLMEvent, VernLLMOptions, WireMessage, WireRequest, WireStreamChunk, WireToolCall, WireToolChoice, defaultEstimateTokens, defaultFallbackOn, defineCachedCallParams, defineCallParams, defineTool, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAI, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, hasIssues, isFallbackExhaustedError, isLLMError, isToolCallResult, parseSseStream };
-//# sourceMappingURL=index.d.ts.map
+export { type AnthropicClient, type AssistantContent, type AttemptContext, type BedrockConverseClient, type CacheAdapter, type CachedCallParams, type CachedConditionalToolCallParams, type CachedJsonModeDisabledCallParams, type CachedJsonModeEnabledCallParams, type CachedStreamCallParams, type CachedStreamConditionalToolCallParams, type CachedStreamJsonModeDisabledCallParams, type CachedStreamJsonModeEnabledCallParams, type CachedStreamToolCallParams, type CachedToolCallParams, type CallMeta, type CallParams, type CallResult, type CallWithToolsResult, CircuitBreaker, type CircuitBreakerOptions, type CircuitState, type CircuitTarget, type ConditionalToolCallParams, ConsecutiveTripping, ConsoleLogger, type ContentBlock, type ContentResult, type ConversationTurn, type CooldownBackoff, type CreateMiddlewareOptions, type DuplicateToolNamesIssue, type EvictionOption, type ExponentialBackoffOptions, type FallbackAttempt, FallbackExhaustedError, type FallbackOn, type FallbackTarget, type FetchAdapterConfig, type GeminiClient, type HistoryToolResultIssue, type ImageBlock, InMemoryCacheAdapter, type JsonModeDisabledCallParams, type JsonModeEnabledCallParams, type JsonSchemaSpec, type JsonValue, type LLMClient, LLMError, type LLMErrorCode, type LLMErrorIssuesByCode, type LLMErrorSnapshot, type LLMErrorType, type LLMRequestShape, type LLMRequestSnapshot, type Logger, type MiddlewareCapabilities, type MiddlewareContext, type MiddlewareContextBase, type MiddlewareStateBag, type MiddlewareStateKey, NormalizedCacheAdapter, type OnEvent, type OnUsage, type PreDispatchContext, type RateLimitAcquireResult, type RateLimitOptions, type RateLimitReason, RateLimiter, type RateLimiterAdapter, type RefundUsage, type ReserveUsage, type RetryAttempt, RetryBudget, type RetryBudgetOptions, RollingTripping, SSE_PING, type SchemaLike, type StreamCallResult, type StreamChunk, type StreamEnabledCallParams, type StreamJsonModeDisabledCallParams, type StreamJsonModeEnabledCallParams, type TargetCircuitState, type TextBlock, TieredCacheAdapter, type TokenUsage, type ToolCall, type ToolCallResult, type ToolChoice, type ToolDefinition, type ToolEnabledCallParams, type ToolIssue, type ToolResult, type ToolsDisabledCallParams, type TrippingPolicy, type UnknownToolChoiceIssue, type UnsupportedCapabilityIssue, VernLLM, type VernLLMEvent, type VernLLMMiddleware, type VernLLMOptions, type WireCallRequest, type WireCallRequestPatch, type WireMessage, type WireRequest, type WireResponseFormat, type WireStreamChunk, type WireTool, type WireToolCall, type WireToolChoice, createMiddleware, createMiddlewareStateBag, createStateKey, defaultEstimateTokens, defaultFallbackOn, defineCachedCallParams, defineCallParams, defineTool, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAI, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, hasIssues, isFallbackExhaustedError, isLLMError, isToolCallResult, metaRef, parseSseStream };
+//# sourceMappingURL=index.d.mts.map