vern-llm 2.4.2 → 2.5.0

package/dist/index.d.ts

@@ -7,7 +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';
+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' | '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';
 /**
  * Tool contract codes: a model or provider response defect, not a
  * transient provider fault. Deterministic on the wire request, so
@@ -187,9 +187,10 @@ 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;
   /**
@@ -303,8 +304,303 @@ declare class TieredCacheAdapter<T = unknown> implements CacheAdapter<T> {
 }
 
 //#endregion
-//#region src/circuitBreaker.d.ts
+//#region src/types/events.d.ts
 //# sourceMappingURL=cache.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';
+} | {
+  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
+//# sourceMappingURL=events.d.ts.map
+/** 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=middleware.d.ts.map
+/** The call this mutation happened as part of, forwarded to `onStateChange` untouched. `CircuitBreaker` never inspects it. */
+interface CircuitBreakerCallContext {
+  requestId: string;
+  state: MiddlewareStateBag;
+  signal?: AbortSignal;
+  /**
+   * The real, current attempt number for this dispatch, when the call
+   * site actually has one in scope (i.e. after a dispatch was made or
+   * failed). Omitted for calls that happen before any attempt exists,
+   * like `assertClosed`'s pre-dispatch check.
+   */
+  attempt?: number;
+}
 interface CircuitBreakerOptions {
   /** Consecutive failures before the circuit opens, default 5 */
   threshold?: number;
@@ -323,7 +619,8 @@ interface CircuitBreakerOptions {
    * here. With `isolateByModel` on, it's exact: each model has its own
    * counter, so the transition really was caused solely by that model.
    */
-  onStateChange?: (from: CircuitState, to: CircuitState, consecutiveFailures: number, model?: string) => void;
+  onStateChange?: (from: CircuitState, to: CircuitState, consecutiveFailures: number, model?: string, /** See `CircuitBreakerCallContext`. */
+  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
@@ -367,9 +664,9 @@ declare class CircuitBreaker {
    * 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;
+  assertClosed(model?: string, context?: CircuitBreakerCallContext): void;
+  recordSuccess(model?: string, context?: CircuitBreakerCallContext): void;
+  recordFailure(model?: string, context?: CircuitBreakerCallContext): void;
   /**
    * With `isolateByModel` off (the default), `model` is ignored and the
    * one shared circuit's state is returned, unchanged from every version
@@ -385,7 +682,7 @@ declare class CircuitBreaker {
    * 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;
+  open(model?: string, context?: CircuitBreakerCallContext): void;
   /**
    * Manually closes the circuit and resets its failure count, e.g. once a
    * provider is confirmed healthy again without waiting out the cooldown.
@@ -393,7 +690,7 @@ declare class CircuitBreaker {
    * per-model bucket under `isolateByModel`, once idle) but without
    * requiring an actual successful call first.
    */
-  close(model?: string): void;
+  close(model?: string, context?: CircuitBreakerCallContext): void;
 }
 
 //#endregion
@@ -616,6 +913,19 @@ 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
@@ -687,7 +997,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 +1014,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 }`.
@@ -928,13 +1238,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 +1265,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 +1351,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 +1460,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 +1473,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 +1484,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,14 +1499,20 @@ 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;
+  };
 };
 
 //#endregion
@@ -1282,10 +1633,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 +1648,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 +1661,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 +1678,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,7 +1690,11 @@ 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
@@ -1483,72 +1850,9 @@ declare class ConsoleLogger implements Logger {
   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
+//# sourceMappingURL=logger.d.ts.map
 interface VernLLMOptions {
   client: LLMClient;
   model: string;
@@ -1680,11 +1984,61 @@ 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/vernLLM.d.ts
+//#region src/types/createMiddleware.d.ts
 //# sourceMappingURL=options.d.ts.map
+/**
+ * `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=createMiddleware.d.ts.map
 /**
  * A LLM call framework for resilience, observability and control. This is VernLLM!
  *
@@ -1698,21 +2052,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 +2092,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 +2142,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>>>;
@@ -1896,11 +2201,11 @@ 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
+//# sourceMappingURL=vernLLM.d.ts.map
 /**
  * Identity function preserving `params`'s own precise type, unlike a `:
  * CallParams<T>` annotation, which would widen `tools` away and break the
@@ -1939,7 +2244,7 @@ declare function defineCachedCallParams<P extends CachedCallParams<unknown>>(par
 
 //#endregion
 //#region src/adapters/internal/sse.d.ts
-//# sourceMappingURL=vernLLM.d.ts.map
+//# sourceMappingURL=paramsHelpers.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
@@ -2000,8 +2305,8 @@ type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
 
 /**
  * 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.
  *
@@ -2677,7 +2982,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
@@ -3132,5 +3437,5 @@ 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 };
+export { AnthropicClient, AssistantContent, AttemptContext, BedrockConverseClient, CacheAdapter, CachedCallParams, CachedConditionalToolCallParams, CachedJsonModeDisabledCallParams, CachedJsonModeEnabledCallParams, CachedStreamCallParams, CachedStreamConditionalToolCallParams, CachedStreamJsonModeDisabledCallParams, CachedStreamJsonModeEnabledCallParams, CachedStreamToolCallParams, CachedToolCallParams, CallMeta, CallParams, CallResult, CallWithToolsResult, CircuitBreaker, CircuitBreakerOptions, CircuitState, CircuitTarget, ConditionalToolCallParams, ConsoleLogger, ContentBlock, ContentResult, ConversationTurn, CreateMiddlewareOptions, DuplicateToolNamesIssue, FallbackAttempt, FallbackExhaustedError, FallbackOn, FallbackTarget, FetchAdapterConfig, GeminiClient, HistoryToolResultIssue, ImageBlock, InMemoryCacheAdapter, JsonModeDisabledCallParams, JsonModeEnabledCallParams, JsonSchemaSpec, JsonValue, LLMClient, LLMError, LLMErrorCode, LLMErrorIssuesByCode, LLMErrorSnapshot, LLMErrorType, LLMRequestShape, LLMRequestSnapshot, Logger, MiddlewareCapabilities, MiddlewareContext, MiddlewareContextBase, MiddlewareStateBag, MiddlewareStateKey, NormalizedCacheAdapter, OnEvent, OnUsage, PreDispatchContext, 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, VernLLMMiddleware, VernLLMOptions, WireCallRequest, WireCallRequestPatch, WireMessage, WireRequest, WireResponseFormat, WireStreamChunk, WireTool, WireToolCall, 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.ts.map