vern-llm 2.4.1 → 2.5.0

package/dist/index.d.cts

@@ -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
@@ -658,8 +968,8 @@ interface JsonSchemaSpec {
  * itself. VernLLM transports this to the provider and parses what comes
  * back; it never executes anything.
  */
-interface ToolDefinition {
-  name: string;
+interface ToolDefinition<Name extends string = string, Args = unknown> {
+  name: Name;
   description: string;
   /** JSON Schema for the tool's input. */
   parameters: Record<string, unknown>;
@@ -671,16 +981,45 @@ interface ToolDefinition {
    * requiring a JSON Schema validator (e.g. ajv) as a new dependency.
    * Failed validation throws `LLMError('validation')`. If omitted, VernLLM
    * parses arguments as JSON but does not validate them further.
+   *
+   * When set, `Args` (and therefore `Name`) flow into the `ToolCall`s
+   * returned by `call()`/`cachedCall()`, provided the tool was declared
+   * with `defineTool()` or otherwise has a literal `name`; see
+   * `defineTool()` below for why a plain object literal often doesn't.
    */
-  argumentsSchema?: SchemaLike<unknown>;
+  argumentsSchema?: SchemaLike<Args>;
 }
-/** A single tool invocation requested by the model. */
-interface ToolCall {
+/**
+ * Preserves a tool definition's literal `name` (and its `argumentsSchema`'s
+ * inferred `Args`) so it can discriminate a `ToolCall` union later.
+ *
+ * A plain object literal like `{ name: 'get_weather', ... }` widens `name`
+ * 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
+ * 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.
+ */
+declare function defineTool<const Name extends string, Args = unknown>(tool: ToolDefinition<Name, Args>): ToolDefinition<Name, Args>;
+/** Maps a single `ToolDefinition` to its matching `ToolCall` shape. */
+type ToolCallFor<T> = T extends ToolDefinition<infer N, infer A> ? {
   id: string;
-  name: string;
-  /** Parsed JSON arguments (and validated, if `argumentsSchema` was set). */
-  arguments: unknown;
-}
+  name: N;
+  arguments: A;
+} : never;
+/**
+ * A single tool invocation requested by the model.
+ *
+ * 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
+ * `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 }`.
+ */
+type ToolCall<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = ToolCallFor<Tools[number]>;
 /** The application's result of executing a `ToolCall`, sent back to the model. */
 interface ToolResult {
   toolCallId: string;
@@ -699,13 +1038,33 @@ interface ContentResult<T> {
   content: T;
 }
 /** `call()` result when `tools` was set and the model requested one or more tools. */
-interface ToolCallResult {
+interface ToolCallResult<Tools extends readonly ToolDefinition[] = ToolDefinition[]> {
   type: 'tool_calls';
-  toolCalls: ToolCall[];
+  toolCalls: ToolCall<Tools>[];
   /** Any text the model produced alongside the tool request, if present. */
   content?: string;
 }
-type CallWithToolsResult<T> = ContentResult<T> | ToolCallResult;
+type CallWithToolsResult<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = ContentResult<T> | ToolCallResult<Tools>;
+/**
+ * Pulls `Tools` out of a `result` value's own static type, when that type
+ * is already `ContentResult<T> | ToolCallResult<Tools>` (or a superset
+ * including it) rather than plain `unknown`. `Extract` isolates just the
+ * `ToolCallResult<...>` member(s) of a union before inferring, so this
+ * degrades to the default cleanly when `result` doesn't carry a
+ * `ToolCallResult` shape at all (e.g. `unknown`, or a `call()` result that
+ * TypeScript could only type as plain `T`, see `isToolCallResult`'s docs).
+ */
+type ExtractTools<R> = Extract<R, ToolCallResult<ToolDefinition[]>> extends ToolCallResult<infer Tools> ? Tools : ToolDefinition[];
+/**
+ * Resolves the `Tools` `isToolCallResult` actually narrows with: the
+ * explicit `Tools` type argument if one was given, otherwise whatever
+ * `ExtractTools` can infer from `R` (the `result` argument's own type).
+ * `Tools` defaults to `never` as an "unset" sentinel, not a real tools
+ * list, so this can tell "caller passed nothing" apart from "caller
+ * genuinely passed `never`" (which would be an unusual thing to write on
+ * purpose, and isn't a meaningful `Tools` value regardless).
+ */
+type ResolvedTools<Tools, R> = [Tools] extends [never] ? ExtractTools<R> : Tools;
 /**
  * Runtime-safe check for whether a `call()` result is a `tool_calls`
  * result. Prefer this over relying on TypeScript's static narrowing
@@ -714,8 +1073,42 @@ type CallWithToolsResult<T> = ContentResult<T> | ToolCallResult;
  * that case TS may have typed the result as plain `T` even though it's
  * actually a `CallWithToolsResult<T>` at runtime, and this check works
  * either way.
+ *
+ * Generic over `Tools`, same as `ToolCallResult` itself, so narrowing a
+ * conditional-tools result (`tools: someCondition ? [myTool] : undefined`)
+ * through this check doesn't erase the per-tool `arguments` typing that
+ * `ConditionalToolCallParams` already captured. `Tools` is inferred
+ * automatically from `result`'s own static type whenever that's already
+ * `T | CallWithToolsResult<T, Tools>` (which it is whenever `call()`'s
+ * overload resolution succeeded, the common case), no type argument
+ * needed:
+ *
+ * ```ts
+ * const tools = someCondition ? [myTool] : undefined;
+ * const result = await llm.call({ userContent: '...', tools });
+ * if (isToolCallResult(result)) {
+ *   // result.toolCalls[number].arguments is typed per tool, inferred
+ *   // automatically, not `unknown`
+ * }
+ * ```
+ *
+ * If `result`'s static type is plain `unknown` (or otherwise doesn't
+ * carry `Tools`, e.g. a variable annotated `: CallParams<T>` upstream
+ * widened it away, see the overload note), there's nothing to infer from
+ * and this falls back to the default `ToolCallResult` with `arguments:
+ * unknown`, same as before `isToolCallResult` became generic. Pass
+ * `Tools` explicitly as the first type argument to override the inferred
+ * (or defaulted) type in either case; the second type argument (`R`, the
+ * `result` value's own type) is always inferred from the argument itself
+ * and should not be set manually:
+ *
+ * ```ts
+ * if (isToolCallResult<typeof tools>(result)) {
+ *   // arguments typed per tool via the explicit override
+ * }
+ * ```
  */
-declare function isToolCallResult(result: unknown): result is ToolCallResult;
+declare function isToolCallResult<Tools extends readonly ToolDefinition[] | undefined = never, R = unknown>(result: R): result is R & ToolCallResult<NonNullable<ResolvedTools<Tools, R>>>;
 /** What the model should do about tools on a given call. */
 type ToolChoice = 'auto' | 'none' | 'required' | {
   name: string;
@@ -723,7 +1116,6 @@ type ToolChoice = 'auto' | 'none' | 'required' | {
 
 //#endregion
 //#region src/types/usage.d.ts
-//# sourceMappingURL=tools.d.ts.map
 type ReserveUsage = (params: {
   coalesced: boolean;
   signal?: AbortSignal;
@@ -846,13 +1238,21 @@ interface ImageBlock {
 }
 /** A single segment of multimodal `userContent`. */
 type ContentBlock = TextBlock | ImageBlock;
-interface CallParams<T = unknown> 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[];
   /**
@@ -865,6 +1265,20 @@ interface CallParams<T = unknown> extends UsageHooks {
   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`.
@@ -911,8 +1325,12 @@ interface CallParams<T = unknown> extends UsageHooks {
    * Tools the model may call. When set, `call()` returns a
    * `CallWithToolsResult<T>` union instead of `T` directly. Combining with
    * `jsonSchema` is provider-dependent; see the Tool Calling docs.
+   *
+   * Passed as a literal array (or via `defineTool()`-wrapped entries, see
+   * `types/tools.ts`), this also drives the `Tools` type parameter, which
+   * narrows `CallWithToolsResult`'s `toolCalls[number].arguments` per tool.
    */
-  tools?: ToolDefinition[];
+  tools?: Tools;
   /** Defaults to `'auto'` when `tools` is set. */
   toolChoice?: ToolChoice;
   /**
@@ -933,15 +1351,24 @@ interface CallParams<T = unknown> extends UsageHooks {
    * 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.
  *
@@ -949,22 +1376,33 @@ interface CallParams<T = unknown> extends UsageHooks {
  * tool-aware `call()` overload and return `CallWithToolsResult<T>` instead
  * of the normal `T` response type.
  */
-type ToolEnabledCallParams<T> = CallParams<T> & {
-  tools: NonNullable<CallParams<T>['tools']>;
+type ToolEnabledCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  tools: NonNullable<CallParams<T, Tools>['tools']>;
 };
 /**
  * A `CallParams` variant for tools set conditionally, e.g. `tools:
  * someCondition ? [myTool] : undefined`. Selects the `call()` overload
- * returning the honest union `T | CallWithToolsResult<T>` instead of
+ * returning the honest union `T | CallWithToolsResult<T, Tools>` instead of
  * falling through to plain `T` (which is what happened before this type
  * existed, since `ToolDefinition[] | undefined` matched neither
  * `ToolEnabledCallParams` nor `ToolsDisabledCallParams`). Forces an
  * `isToolCallResult()` check before treating the result as plain
  * content. Omitting `tools` entirely still resolves to plain `T`, since
  * tools genuinely cannot have run there.
- */
-type ConditionalToolCallParams<T> = CallParams<T> & {
-  tools: ToolDefinition[] | undefined;
+ *
+ * `Tools` still can't reliably infer a literal tuple here the way
+ * `ToolEnabledCallParams` does for an inline array (a ternary/variable
+ * expression doesn't carry the same `const`-literal preservation), so
+ * getting typed `arguments` out of a conditional-tools result also needs
+ * an explicit `Tools` type argument on `isToolCallResult<Tools>()` when
+ * narrowing, see its docs.
+ */
+type ConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  tools: Tools | undefined;
+};
+/** Conditional tool-call parameters whose non-tool result is plain text. */
+type ConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = ConditionalToolCallParams<string, Tools> & {
+  jsonMode: false;
 };
 /**
  * A `CallParams` variant where tools are offered but the model is barred
@@ -976,8 +1414,8 @@ type ConditionalToolCallParams<T> = CallParams<T> & {
  * on the wrapper object silently produces `"[object Object]"` instead of
  * throwing. The type itself rules that shape out.
  */
-type ToolsDisabledCallParams<T> = CallParams<T> & {
-  tools: NonNullable<CallParams<T>['tools']>;
+type ToolsDisabledCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  tools: NonNullable<CallParams<T, Tools>['tools']>;
   toolChoice: 'none';
 };
 /**
@@ -1022,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.
@@ -1034,8 +1472,10 @@ type CachedCallParams<T> = CachedCallInput & {
  * See `CachedCallParams` for why `reserveUsage`/`refundUsage` are omitted
  * from `call`'s type here too.
  */
-type CachedToolCallParams<T> = CachedCallInput & {
-  call: Omit<ToolEnabledCallParams<T>, 'reserveUsage' | 'refundUsage'>;
+type CachedToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  call: LLMRequestShape<T, Tools> & {
+    tools: NonNullable<LLMRequestShape<T, Tools>['tools']>;
+  };
 };
 /**
  * Parameters for a cached LLM call with `call.tools` set conditionally.
@@ -1043,22 +1483,36 @@ type CachedToolCallParams<T> = CachedCallInput & {
  * `T | CallWithToolsResult<T>` instead of narrowing to plain `T`. See
  * `ConditionalToolCallParams` for why this overload exists.
  */
-type CachedConditionalToolCallParams<T> = CachedCallInput & {
-  call: Omit<ConditionalToolCallParams<T>, 'reserveUsage' | 'refundUsage'>;
+type CachedConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  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> & {
+  call: {
+    jsonMode: false;
+  };
 };
 /**
  * Parameters for a cached LLM call with `jsonMode: false`. Selects the
  * `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
@@ -1104,9 +1558,11 @@ interface StreamCallResult<R> {
  * select the streaming `call()` overload and return `StreamCallResult<...>`
  * instead of the normal, single-shot response type.
  */
-type StreamEnabledCallParams<T> = CallParams<T> & {
+type StreamEnabledCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
   stream: true;
 };
+/** Streaming conditional tool-call parameters whose non-tool result is text. */
+type StreamConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = StreamEnabledCallParams<string, Tools> & ConditionalStringToolCallParams<Tools>;
 /**
  * `StreamEnabledCallParams` with `jsonMode: false`. Selects the streaming
  * `call()` overload whose `finalResult` resolves to a plain `string`.
@@ -1177,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.
@@ -1189,8 +1647,11 @@ type CachedStreamCallParams<T> = CachedCallInput & {
  * `CachedToolCallParams<T>`, with the same live-chunks-on-miss,
  * replayed-chunks-on-hit behavior as `CachedStreamCallParams<T>`.
  */
-type CachedStreamToolCallParams<T> = CachedCallInput & {
-  call: Omit<StreamEnabledCallParams<T> & ToolEnabledCallParams<T>, 'reserveUsage' | 'refundUsage'>;
+type CachedStreamToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  call: LLMRequestShape<T, Tools> & {
+    stream: true;
+    tools: NonNullable<LLMRequestShape<T, Tools>['tools']>;
+  };
 };
 /**
  * Parameters for a cached, streaming LLM call with `call.tools` set
@@ -1199,8 +1660,17 @@ type CachedStreamToolCallParams<T> = CachedCallInput & {
  * `T | CallWithToolsResult<T>` instead of narrowing to plain `T`. See
  * `ConditionalToolCallParams` for why this overload exists.
  */
-type CachedStreamConditionalToolCallParams<T> = CachedCallInput & {
-  call: Omit<StreamEnabledCallParams<T> & ConditionalToolCallParams<T>, 'reserveUsage' | 'refundUsage'>;
+type CachedStreamConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  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> & {
+  call: {
+    jsonMode: false;
+  };
 };
 /**
  * Parameters for a cached, streaming LLM call with `jsonMode: false`.
@@ -1208,7 +1678,11 @@ type CachedStreamConditionalToolCallParams<T> = CachedCallInput & {
  * 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
@@ -1216,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
@@ -1372,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;
@@ -1569,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!
  *
@@ -1587,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,
@@ -1611,70 +2092,35 @@ 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`.
+   * aborted. Rejects with a normalized `LLMError` on exhausted retries.
    *
-   * 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.
-   *
-   * 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.
+   * 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>(params: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
-  call<T = unknown>(params: StreamEnabledCallParams<T> & ConditionalToolCallParams<T>): Promise<StreamCallResult<T | CallWithToolsResult<T>>>;
+  call<T = unknown, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: StreamEnabledCallParams<T, Tools> & ToolEnabledCallParams<T, Tools>): Promise<StreamCallResult<CallWithToolsResult<T, Tools>>>;
+  call<const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: StreamConditionalStringToolCallParams<Tools>): Promise<StreamCallResult<string | CallWithToolsResult<string, Tools>>>;
+  call<T = unknown, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: StreamEnabledCallParams<T, Tools> & ConditionalToolCallParams<T, Tools>): Promise<StreamCallResult<T | CallWithToolsResult<T, Tools>>>;
   call(params: StreamJsonModeDisabledCallParams): Promise<StreamCallResult<string>>;
   call(params: StreamJsonModeEnabledCallParams): Promise<StreamCallResult<JsonValue>>;
   call<T = unknown>(params: StreamEnabledCallParams<T>): Promise<StreamCallResult<T>>;
   call<T = unknown>(params: ToolsDisabledCallParams<T>): Promise<ContentResult<T>>;
-  call<T = unknown>(params: ToolEnabledCallParams<T>): Promise<CallWithToolsResult<T>>;
-  call<T = unknown>(params: ConditionalToolCallParams<T>): Promise<T | CallWithToolsResult<T>>;
+  call<T = unknown, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: ToolEnabledCallParams<T, Tools>): Promise<CallWithToolsResult<T, Tools>>;
+  call<const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: ConditionalStringToolCallParams<Tools>): Promise<string | CallWithToolsResult<string, Tools>>;
+  call<T = unknown, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: ConditionalToolCallParams<T, Tools>): Promise<T | CallWithToolsResult<T, Tools>>;
   call(params: JsonModeDisabledCallParams): Promise<string>;
   call(params: JsonModeEnabledCallParams): Promise<JsonValue>;
   call<T = unknown>(params: CallParams<T>): Promise<T>;
@@ -1696,39 +2142,30 @@ 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.
    *
-   * @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>(params: CachedStreamToolCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
-  cachedCall<T>(params: CachedStreamConditionalToolCallParams<T>): Promise<StreamCallResult<T | CallWithToolsResult<T>>>;
+  cachedCall<T, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedStreamToolCallParams<T, Tools>): Promise<StreamCallResult<CallWithToolsResult<T, Tools>>>;
+  cachedCall<const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedStreamConditionalStringToolCallParams<Tools>): Promise<StreamCallResult<string | CallWithToolsResult<string, Tools>>>;
+  cachedCall<T, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedStreamConditionalToolCallParams<T, Tools>): Promise<StreamCallResult<T | CallWithToolsResult<T, Tools>>>;
   cachedCall(params: CachedStreamJsonModeDisabledCallParams): Promise<StreamCallResult<string>>;
   cachedCall(params: CachedStreamJsonModeEnabledCallParams): Promise<StreamCallResult<JsonValue>>;
   cachedCall<T>(params: CachedStreamCallParams<T>): Promise<StreamCallResult<T>>;
-  cachedCall<T>(params: CachedToolCallParams<T>): Promise<CallWithToolsResult<T>>;
-  cachedCall<T>(params: CachedConditionalToolCallParams<T>): Promise<T | CallWithToolsResult<T>>;
+  cachedCall<T, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedToolCallParams<T, Tools>): Promise<CallWithToolsResult<T, Tools>>;
+  cachedCall<const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedConditionalStringToolCallParams<Tools>): Promise<string | CallWithToolsResult<string, Tools>>;
+  cachedCall<T, const Tools extends readonly ToolDefinition[] = ToolDefinition[]>(params: CachedConditionalToolCallParams<T, Tools>): Promise<T | CallWithToolsResult<T, Tools>>;
   cachedCall(params: CachedJsonModeDisabledCallParams): Promise<string>;
   cachedCall(params: CachedJsonModeEnabledCallParams): Promise<JsonValue>;
   cachedCall<T>(params: CachedCallParams<T>): Promise<T>;
@@ -1764,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
@@ -1807,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
@@ -1868,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.
  *
@@ -1877,13 +2314,13 @@ type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
  * Anthropic's and Bedrock's call to make, not this package's, and it
  * changes over time; hardcoding a guessed list would risk silently
  * routing a request onto a field a given model doesn't actually support,
- * trading a clear `LLMError('validation')` for a confusing error from the
- * provider instead. So this is opt-in: pass the model IDs you've verified
- * against the provider's own docs (or a predicate). Left unset, no model
- * is treated as native-capable, `jsonSchema` keeps using the older
- * forced-single-tool-call emulation, and `tools` + `jsonSchema` together
- * is rejected, exactly this package's behavior before native support was
- * added.
+ * trading a clear `LLMError('invalid_params')` with
+ * `code: 'unsupported_capability'` for a confusing error from the provider
+ * instead. So this is opt-in: pass the model IDs you've verified against the
+ * provider's own docs (or a predicate). Left unset, no model is treated as
+ * native-capable, `jsonSchema` keeps using the older forced-single-tool-call
+ * emulation, and combining it with `tools` throws the coded capability error,
+ * exactly this package's behavior before native support was added.
  */
 type ModelCapabilityOverride = string[] | ((model: string) => boolean);
 
@@ -2083,7 +2520,8 @@ interface AnthropicAdapterOptions {
  * forwarded when set, and `tool_choice` forces the model to call it. This
  * legacy path cannot be combined with real `tools` (both would need the
  * same `tools`/`tool_choice` field), and a call that tries throws
- * `LLMError('validation')` before reaching the API. Provider-constrained
+ * `LLMError('invalid_params')` with `code: 'unsupported_capability'` and
+ * `issues: { capability: 'tools_with_json_schema' }` before reaching the API. Provider-constrained
  * schema matching applies only when `strict: true` is forwarded and
  * supported.
  *
@@ -2115,11 +2553,13 @@ type GeminiPart = {
   };
 } | {
   functionCall: {
+    id?: string;
     name: string;
     args: Record<string, unknown>;
   };
 } | {
   functionResponse: {
+    id?: string;
     name: string;
     response: Record<string, unknown>;
   };
@@ -2204,6 +2644,7 @@ interface GeminiClient {
         parts?: Array<{
           text?: string;
           functionCall?: {
+            id?: string;
             name?: string;
             args?: unknown;
           };
@@ -2231,6 +2672,7 @@ interface GeminiClient {
         parts?: Array<{
           text?: string;
           functionCall?: {
+            id?: string;
             name?: string;
             args?: unknown;
           };
@@ -2540,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
@@ -2631,7 +3073,8 @@ interface AwsSendClient {
  * the schema, description, and strictness settings, and `toolChoice`
  * forces the model to call it. This legacy path cannot be combined with
  * real `tools` (both would need the same `toolConfig`), and a call that
- * tries throws `LLMError('validation')` before reaching the API.
+ * tries throws `LLMError('invalid_params')` with `code: 'unsupported_capability'`
+ * and `issues: { capability: 'tools_with_json_schema' }` before reaching the API.
  * Provider-constrained schema matching applies only when `strict: true` is
  * forwarded and supported. Native tool support varies by model family;
  * pass `toolUseSupportedModels` to preflight-check it (see
@@ -2994,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, 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.cts.map