vern-llm 1.7.1 → 2.1.0

package/dist/index.d.cts

@@ -1,14 +1,109 @@
+//#region src/circuitBreaker.d.ts
+interface CircuitBreakerOptions {
+  /** Consecutive failures before the circuit opens, default 5 */
+  threshold?: number;
+  /** How long the circuit stays open before allowing a trial request, in ms. Default 30000 */
+  cooldownMs?: number;
+  /**
+   * Called after every real state change, never for a no-op transition
+   * (e.g. open to open). `model` is the resolved model of whichever call
+   * triggered this specific transition (the `model` passed to whichever
+   * of `assertClosed`/`recordSuccess`/`recordFailure` caused it).
+   *
+   * With `isolateByModel` off (the default), this is a label only: the
+   * breaker still counts failures across every model together, so a
+   * threshold crossing can be the sum of several different models'
+   * failures even though only the triggering call's `model` is reported
+   * here. With `isolateByModel` on, it's exact: each model has its own
+   * counter, so the transition really was caused solely by that model.
+   */
+  onStateChange?: (from: CircuitState, to: CircuitState, consecutiveFailures: number, model?: string) => void;
+  /**
+   * Track a separate circuit per resolved model instead of one shared
+   * circuit for the whole instance. A failure on one model then never
+   * opens another model's circuit, at the cost of slower detection for
+   * an outage spread across many distinct models (each model's counter
+   * must independently cross `threshold`). Default false: one shared
+   * circuit, matching every version before this option existed.
+   *
+   * A call that omits `model` (only possible calling `CircuitBreaker`
+   * directly, `VernLLM` always passes one) falls into one shared bucket
+   * alongside every other call that also omits it.
+   */
+  isolateByModel?: boolean;
+}
+type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Per retry VernLLM-instance circuit breaker. Tracks consecutive failures across
+ * calls. Once the threshold is hit, short-circuits new calls with an
+ * LLMError('circuit_open') instead of hitting the provider, until the
+ * cooldown elapses and a single trial call is allowed through
+ */
+declare class CircuitBreaker {
+  private readonly threshold;
+  private readonly cooldownMs;
+  private readonly onStateChange?;
+  private readonly isolateByModel;
+  private readonly sharedBucket;
+  private readonly bucketsByModel;
+  constructor(options?: CircuitBreakerOptions);
+  /** Returns the bucket for a model if one already exists, without allocating. */
+  private lookupBucket;
+  /** Creates and stores a bucket for a model when the first mutation needs one. */
+  private ensureBucketFor;
+  /** Every state mutation routes through here, so `onStateChange` fires exactly once per real change. */
+  private transition;
+  /**
+   * Throws if the circuit is open and the cooldown hasn't elapsed, or if
+   * the circuit is half-open and a trial call is already in flight.
+   * Otherwise, if the circuit just became eligible for a trial (cooldown
+   * elapsed, or half-open with no trial currently running), this call
+   * becomes that trial
+   */
+  assertClosed(model?: string): void;
+  recordSuccess(model?: string): void;
+  recordFailure(model?: string): void;
+  /**
+   * With `isolateByModel` off (the default), `model` is ignored and the
+   * one shared circuit's state is returned, unchanged from every version
+   * before this option existed. With `isolateByModel` on, returns that
+   * model's own state, `'closed'` for a model never seen yet, same as a
+   * fresh breaker.
+   */
+  getState(model?: string): CircuitState;
+} //#endregion
 //#region src/types/errors.d.ts
+
+//# sourceMappingURL=circuitBreaker.d.ts.map
 type LLMErrorType = 'timeout' | 'api' | 'parse' | 'validation' | 'circuit_open' | 'quota_exceeded' | 'unknown' | 'aborted';
+/**
+ * Machine readable discriminator within a `type`, for cases where `type`
+ * alone is too coarse to act on. Optional and additive: errors thrown
+ * before a given code existed simply omit it.
+ */
+type LLMErrorCode = 'unknown_tool' | 'duplicate_tool_call_id' | 'local_rate_limit' | 'provider_rate_limited' | 'fallback_exhausted';
+/** One tool call's contract failure, used to report every bad call in a response at once. */
+interface ToolIssue {
+  name: string;
+  toolCallId: string;
+  code: LLMErrorCode;
+  detail?: unknown;
+}
 declare class LLMError extends Error {
   type: LLMErrorType;
   status?: number | undefined;
   issues?: unknown | undefined;
   cause?: unknown | undefined;
   retryAfterMs?: number | undefined;
-  constructor(message: string, type: LLMErrorType, status?: number | undefined, issues?: unknown | undefined, cause?: unknown | undefined, retryAfterMs?: number | undefined);
+  /** Stable discriminator within `type`. Absent on errors predating it. */
+  code?: LLMErrorCode | undefined;
+  constructor(message: string, type: LLMErrorType, status?: number | undefined, issues?: unknown | undefined, cause?: unknown | undefined, retryAfterMs?: number | undefined, /** Stable discriminator within `type`. Absent on errors predating it. */
+  code?: LLMErrorCode | undefined);
+  /** Every tool contract failure in one response, when there is more than one. */
+  toolIssues?: ToolIssue[];
 }
 declare function isLLMError(err: unknown): err is LLMError;
+
 //#endregion
 //#region src/types/cache.d.ts
 //# sourceMappingURL=errors.d.ts.map
@@ -77,8 +172,206 @@ declare class TieredCacheAdapter<T = unknown> implements CacheAdapter<T> {
 }
 
 //#endregion
-//#region src/types/schema.d.ts
+//#region src/rateLimit.d.ts
 //# sourceMappingURL=cache.d.ts.map
+/** The request shape sent to `LLMClient['chat']['completions']['create']`, used for token estimation. */
+type WireRequest = Parameters<LLMClient['chat']['completions']['create']>[0];
+/** Which configured bucket is currently blocking a call. */
+type RateLimitReason = 'concurrency' | 'rpm' | 'tpm';
+interface RateLimitOptions {
+  /** Max requests per minute. Omit for unlimited. */
+  requestsPerMinute?: number;
+  /**
+   * Max tokens per minute. Enforced against a pre-flight estimate, then
+   * reconciled against reported usage once the call completes. Omit for
+   * unlimited.
+   */
+  tokensPerMinute?: number;
+  /** Max requests in flight at once. Default 0, meaning unlimited. */
+  maxConcurrent?: number;
+  /**
+   * Max time a call may sit queued waiting for capacity, in ms. Exceeding
+   * it throws rather than hanging forever. Default 30000. Pass 0 to wait
+   * indefinitely.
+   */
+  maxQueueMs?: number;
+  /** Max queued calls before new ones reject immediately instead of queueing. Default 0, unbounded. */
+  maxQueueSize?: number;
+  /**
+   * Pre-flight token estimate for `tokensPerMinute`. Defaults to a
+   * chars/4 heuristic over message content plus `max_tokens`.
+   */
+  estimateTokens?: (request: WireRequest) => number;
+}
+interface RateLimitAcquireResult {
+  /**
+   * Releases the concurrency slot this attempt held and reconciles the
+   * token bucket against real usage, when `actualTokens` is supplied.
+   * Idempotent: only the first call does anything. Must run in a
+   * `finally` block so a slot is never leaked on a failed attempt.
+   */
+  release: (actualTokens?: number) => void;
+  /** How long this attempt waited in queue before capacity was available. */
+  waitedMs: number;
+  /** Which bucket was blocking this attempt just before it cleared, if any wait happened. */
+  reason?: RateLimitReason;
+}
+/** Default `estimateTokens`: chars/4 over every message's content, plus the requested `max_tokens`. */
+declare function defaultEstimateTokens(request: WireRequest): number;
+/**
+ * Per-target rate limiter. Up to three buckets (requests/min, tokens/min,
+ * concurrency) behind one FIFO queue, so a large call isn't starved by a
+ * stream of small ones. Any bucket omitted from `options` has infinite
+ * capacity and never blocks.
+ */
+declare class RateLimiter {
+  private readonly requests?;
+  private readonly tokens?;
+  private readonly concurrency?;
+  private readonly maxQueueMs;
+  private readonly maxQueueSize;
+  private readonly estimateTokensFn;
+  private readonly queue;
+  /**
+   * A single scheduled re-check for the head of the queue when it's
+   * blocked on a bucket that refills on its own clock (rpm/tpm), so a
+   * queue that nobody calls `acquire`/`release` on again isn't stuck
+   * forever waiting for an external trigger to re-drain it. Not needed
+   * for a concurrency block, which only clears via `release`.
+   */
+  private wakeTimer?;
+  constructor(options: RateLimitOptions);
+  /** Pre-flight token estimate for a request, per the configured (or default) heuristic. */
+  estimate(request: WireRequest): number;
+  /**
+   * Waits for capacity in every configured bucket, then takes from each.
+   * The returned `release` gives the concurrency slot back and reconciles
+   * the token bucket against real usage; it must run in a `finally` block.
+   */
+  acquire(estimatedTokens: number, signal?: AbortSignal): Promise<RateLimitAcquireResult>;
+  private queueFullError;
+  private enqueue;
+  /**
+   * Checks and takes from every configured bucket as one atomic unit: if
+   * any bucket lacks capacity, whatever was already taken from the
+   * earlier ones in this attempt is rolled back before reporting which
+   * bucket blocked.
+   */
+  private tryAcquireBuckets;
+  /** Drains the queue head first. Stops at the first waiter that still can't proceed, so no one is starved out of turn. */
+  private drain;
+  /**
+   * Schedules a one-shot re-check of the queue for whenever the bucket
+   * that's currently blocking the head waiter should next have enough
+   * capacity. A no-op for a concurrency block (only `release` can clear
+   * that) or while a wake is already pending.
+   */
+  private scheduleWake;
+  /**
+   * Builds the one-shot release closure for an acquired slot. Only the
+   * concurrency bucket is given back on release; the requests-per-minute
+   * bucket is a real spend that only recovers via its own refill, and the
+   * tokens bucket is reconciled against `actualTokens` rather than fully
+   * refunded, since real tokens really were spent.
+   */
+  private makeRelease;
+}
+
+//#endregion
+//#region src/types/fallback.d.ts
+//# sourceMappingURL=rateLimit.d.ts.map
+/**
+ * One provider to try after the primary (or after an earlier fallback
+ * target) fails. Order is the policy: VernLLM never reorders, scores, or
+ * selects a target, it only walks the list as given.
+ *
+ * Most per-target overrides fall back to the parent `VernLLM` instance's
+ * own option when omitted, so a target only needs to specify what's
+ * actually different about it (a different client/model is the common
+ * case). `circuitBreaker` and `rateLimit` are the exception: they are
+ * never inherited from the parent, since a breaker or limiter tuned for
+ * the primary provider's limits is rarely right for a fallback's. Leave
+ * them unset on a target to run it without one, even if the parent has
+ * one configured.
+ */
+interface FallbackTarget {
+  client: LLMClient;
+  model: string;
+  /** Label for events, errors, and `TokenUsage.provider`. Default `` `fallback[${index}]` ``. */
+  name?: string;
+  maxRetries?: number;
+  timeoutMs?: number;
+  chunkIdleTimeoutMs?: number;
+  baseDelayMs?: number;
+  defaultMaxTokens?: number;
+  defaultTemperature?: number | null;
+  nonRetryableStatus?: number[];
+  /** This target's own circuit breaker, independent of every other target's. Not inherited from the parent's `circuitBreaker`. */
+  circuitBreaker?: boolean | CircuitBreakerOptions;
+  /** This target's own rate limiter, independent of every other target's. Not inherited from the parent's `rateLimit`. */
+  rateLimit?: RateLimitOptions;
+}
+/**
+ * Written into `CallParams['meta']` once `call()` resolves, so a caller
+ * who wants provider identity on the same line as the result doesn't need
+ * to read it back out of `onUsage`.
+ */
+interface CallMeta {
+  provider: string;
+  model: string;
+  /** `-1` if the primary target answered, otherwise the index into `fallback`. */
+  fallbackIndex: number;
+  usedFallback: boolean;
+  /** Attempts made against the target that ultimately answered, including the successful one. */
+  attempts: number;
+}
+/** One target's circuit state, as returned by `VernLLM.getCircuitStates()`. */
+interface TargetCircuitState {
+  provider: string;
+  /** Position in the chain: `0` for the primary, `1`+ for fallback targets. */
+  index: number;
+  isFallback: boolean;
+  /** `undefined` if that target has no circuit breaker configured. */
+  state: CircuitState | undefined;
+}
+/** One target's failure, recorded on the way to either the next target or `FallbackExhaustedError`. */
+interface FallbackAttempt {
+  /** `-1` for the primary target. */
+  index: number;
+  provider: string;
+  model: string;
+  error: LLMError;
+}
+/**
+ * Decides what happens after a target's own retries are exhausted or
+ * abandoned early. Called once per failed target. `'retry'` is not a
+ * valid return here: retrying already happened inside the target, this
+ * only decides whether to move on to the next one or stop.
+ */
+type FallbackOn = (error: LLMError, context: {
+  isLastTarget: boolean;
+}) => 'next' | 'stop';
+/**
+ * The default `fallbackOn` policy. Exported so a caller can wrap rather
+ * than replace it, e.g. `fallbackOn: (e, ctx) => myCheck(e) ? 'stop' : defaultFallbackOn(e, ctx)`.
+ */
+declare const defaultFallbackOn: FallbackOn;
+/**
+ * Thrown when the chain gives up, whether because the last target failed
+ * or `fallbackOn` chose to stop early. Carries each attempt in order so
+ * an outage across providers stays debuggable without reproducing it.
+ * Extends `LLMError` so `isLLMError` and any `instanceof LLMError` check
+ * still passes, inheriting the last failure's `type` so existing
+ * type-based handling keeps working on a fallback-exhausted error too.
+ */
+declare class FallbackExhaustedError extends LLMError {
+  readonly attempts: FallbackAttempt[];
+  constructor(attempts: FallbackAttempt[]);
+}
+
+//#endregion
+//#region src/types/schema.d.ts
+//# sourceMappingURL=fallback.d.ts.map
 /**
  * Minimal structural type for a Zod-like schema, so this package doesnt need
  * a hard dependency on a specific Zod major version. Any object exposing
@@ -110,8 +403,79 @@ interface JsonSchemaSpec {
 }
 
 //#endregion
-//#region src/types/usage.d.ts
+//#region src/types/tools.d.ts
 //# sourceMappingURL=schema.d.ts.map
+/**
+ * Describes a capability the model may request, not the capability
+ * itself. VernLLM transports this to the provider and parses what comes
+ * back; it never executes anything.
+ */
+interface ToolDefinition {
+  name: string;
+  description: string;
+  /** JSON Schema for the tool's input. */
+  parameters: Record<string, unknown>;
+  /**
+   * Optional client-side validator run on the parsed `arguments` before
+   * they're handed back to the caller, mirroring the `schema: SchemaLike<T>`
+   * pattern already used for response validation (see `types/schema.ts`).
+   * Reuses that zero-dependency, `safeParse`-compatible shape instead of
+   * 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.
+   */
+  argumentsSchema?: SchemaLike<unknown>;
+}
+/** A single tool invocation requested by the model. */
+interface ToolCall {
+  id: string;
+  name: string;
+  /** Parsed JSON arguments (and validated, if `argumentsSchema` was set). */
+  arguments: unknown;
+}
+/** The application's result of executing a `ToolCall`, sent back to the model. */
+interface ToolResult {
+  toolCallId: string;
+  content: unknown;
+  /**
+   * Signals a failed tool execution back to the model (matches Anthropic's
+   * native `is_error` on tool_result blocks). Only `fromAnthropic` honors
+   * this today, Gemini and Bedrock have no equivalent wire concept, so
+   * other adapters ignore it silently.
+   */
+  isError?: boolean;
+}
+/** `call()` result when `tools` was set and the model produced a normal answer. */
+interface ContentResult<T> {
+  type: 'content';
+  content: T;
+}
+/** `call()` result when `tools` was set and the model requested one or more tools. */
+interface ToolCallResult {
+  type: 'tool_calls';
+  toolCalls: ToolCall[];
+  /** Any text the model produced alongside the tool request, if present. */
+  content?: string;
+}
+type CallWithToolsResult<T> = ContentResult<T> | ToolCallResult;
+/**
+ * Runtime-safe check for whether a `call()` result is a `tool_calls`
+ * result. Prefer this over relying on TypeScript's static narrowing
+ * whenever `params` passed to `call()` wasn't a literal with `tools`
+ * inlined (see the "note on the overload" in `VernLLM.call`'s docs), in
+ * 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.
+ */
+declare function isToolCallResult(result: unknown): result is ToolCallResult;
+/** What the model should do about tools on a given call. */
+type ToolChoice = 'auto' | 'none' | 'required' | {
+  name: string;
+};
+
+//#endregion
+//#region src/types/usage.d.ts
+//# sourceMappingURL=tools.d.ts.map
 type ReserveUsage = (params: {
   coalesced: boolean;
   signal?: AbortSignal;
@@ -142,17 +506,55 @@ interface TokenUsage {
   totalTokens: number;
   requestId: string;
   model: string;
+  /**
+   * The provider target that produced this usage. See `VernLLMOptions['name']`,
+   * default `'primary'`. Optional so consumers constructing a `TokenUsage`
+   * themselves (e.g. in tests) aren't forced to supply it; `VernLLM` always
+   * populates it. Absent means the same as `'primary'` if you need a value.
+   */
+  provider?: string;
+  /**
+   * Whether this usage came from a fallback target rather than the
+   * primary. Optional for the same reason `provider` is: `VernLLM`
+   * always populates it, a hand-constructed `TokenUsage` (e.g. in tests)
+   * isn't forced to.
+   */
+  usedFallback?: boolean;
 }
 type OnUsage = (usage: TokenUsage) => void;
+/**
+ * Called when a provider response arrives but VernLLM's own post-processing
+ * then fails, after usage data was already present in that response. Covers
+ * any error thrown after usage extraction, not just parse/validation, since
+ * everything in that path only runs once a response, and real spend, has
+ * already arrived. Fires once per failed attempt with extractable usage,
+ * never for transport failures, where no response means no honest number
+ * to report.
+ */
+type OnUsageFailure = (usage: TokenUsage, error: LLMError) => void;
 
 //#endregion
 //#region src/types/call.d.ts
 //# sourceMappingURL=usage.d.ts.map
-/** A single prior turn in a multi-turn conversation, passed via `history`. */
-interface ConversationTurn {
-  role: 'user' | 'assistant';
+/**
+ * A single prior turn in a multi-turn conversation, passed via `history`.
+ *
+ * Supports normal user/assistant messages and tool continuations: an assistant
+ * turn may include `toolCalls`, and a tool turn carries the matching
+ * `toolResults`. A tool turn must immediately follow an assistant tool call
+ * turn, and every requested tool call must have a result.
+ */
+type ConversationTurn = {
+  role: 'user';
   content: string;
-}
+} | {
+  role: 'assistant';
+  content?: string;
+  toolCalls?: ToolCall[];
+} | {
+  role: 'tool';
+  toolResults: ToolResult[];
+};
 /** A plain text segment of a multimodal `userContent` array. */
 interface TextBlock {
   type: 'text';
@@ -180,15 +582,28 @@ interface CallParams<T = unknown> extends UsageHooks {
   /** Current user message, as text or multimodal content blocks. */
   userContent: string | ContentBlock[];
   /**
-   * Previous conversation turns. Must alternate user/assistant and end with
-   * an assistant turn; invalid history throws LLMError('validation').
+   * Previous conversation turns. Must alternate roles; tool turns must follow
+   * assistant tool calls. Invalid history throws LLMError('validation').
    */
   history?: ConversationTurn[];
-  temperature?: number;
+  /**
+   * Generation temperature. Default 0.2, not the provider's own default.
+   * Pass `null` to omit `temperature` from the request entirely, so the
+   * provider applies its own default instead.
+   */
+  temperature?: number | null;
   jsonMode?: boolean;
   maxTokens?: number;
   requestId?: string;
   signal?: AbortSignal;
+  /**
+   * Per-call override for the instance's `chunkIdleTimeoutMs` (max gap
+   * between stream chunks once opened). Only applies when `stream: true`.
+   * Useful for routes using reasoning-heavy models with documented long
+   * silent gaps mid-stream. Pass 0 to disable the idle timeout for this
+   * call.
+   */
+  chunkIdleTimeoutMs?: number;
   /** Overrides the instance model for this call. */
   model?: string;
   /** Reasoning effort for supported reasoning models. */
@@ -202,17 +617,253 @@ interface CallParams<T = unknown> extends UsageHooks {
    * Implies jsonMode: true.
    */
   schema?: SchemaLike<T>;
+  /**
+   * Tools the model may call. When set, `call()` always returns a
+   * `CallWithToolsResult<T>` discriminated union instead of `T` directly
+   * (see `CallWithToolsResult`), a breaking-change point: omitting `tools`
+   * keeps `call()`'s old `Promise<T>` behavior exactly.
+   *
+   * Can be combined with `jsonSchema` on Gemini and OpenAI-compatible
+   * clients unconditionally (neither ever restricted the combination:
+   * Gemini builds `responseSchema`/`tools` as independent fields, OpenAI-
+   * compatible clients pass both straight through). On Anthropic and
+   * Bedrock, combining the two is opt-in per call site, via each
+   * adapter's `nativeStructuredOutputModels` option: models not covered
+   * by it still throw `LLMError('validation')`, since `jsonSchema` falls
+   * back to a forced single-tool call there, which would collide with
+   * real tools. See `fromAnthropic`/`fromBedrock`.
+   *
+   * `schema` (client-side validation, distinct from `jsonSchema`) was
+   * never restricted from combining with `tools` on any provider.
+   */
+  tools?: ToolDefinition[];
+  /** Defaults to `'auto'` when `tools` is set. */
+  toolChoice?: ToolChoice;
+  /**
+   * Streams the response incrementally instead of resolving once. Default:
+   * false. Requires a client/adapter that implements `createStream`.
+   * Retry/timeout/circuit-breaker guarantees apply only to opening the
+   * stream (through the first chunk); a failure after that point rejects
+   * `finalResult` directly and is not retried, since a mid-stream failure
+   * isn't connection-time evidence for the circuit breaker, the attempt
+   * already counted as a success once the first chunk arrived. Once the
+   * stream opens successfully, `finalResult` still resolves to the same
+   * validated `T`/`CallWithToolsResult<T>` shape `call()` would have
+   * returned for the same params with `stream` omitted. See
+   * `StreamCallResult`.
+   */
+  stream?: boolean;
+  /**
+   * 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.
+   */
+  meta?: {
+    current?: CallMeta;
+  };
 }
-interface CachedCallParams<T> extends UsageHooks {
+/**
+ * A `CallParams` variant where tool calling is explicitly enabled.
+ *
+ * Requiring `tools` to be present allows TypeScript to select the
+ * 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']>;
+};
+/** Shared cache-configuration fields, minus the internal `fn` primitive. */
+interface CachedCallInput extends UsageHooks {
   cacheKey: string;
   ttl: number;
-  fn: () => Promise<T>;
   signal?: AbortSignal;
 }
+/**
+ * Parameters for a cached LLM call without tool calling.
+ *
+ * Combines the cache configuration with the `CallParams` passed to
+ * `VernLLM.call()`. The cached value is the normal LLM response type `T`.
+ */
+type CachedCallParams<T> = CachedCallInput & {
+  call: CallParams<T>;
+};
+/**
+ * Parameters for a cached LLM call with tool calling enabled.
+ *
+ * The cached value includes the full `CallWithToolsResult<T>`, meaning
+ * tool requests and normal content responses are cached exactly as returned
+ * by the model.
+ */
+type CachedToolCallParams<T> = CachedCallInput & {
+  call: ToolEnabledCallParams<T>;
+};
 
 //#endregion
-//#region src/types/client.d.ts
+//#region src/types/stream.d.ts
 //# sourceMappingURL=call.d.ts.map
+/** One incremental unit of a streaming response, as delivered to the caller. */
+type StreamChunk = {
+  type: 'text-delta';
+  delta: string;
+} | {
+  type: 'tool_call_delta';
+  index: number;
+  id?: string;
+  name?: string;
+  argsDelta?: string;
+  /**
+   * True when `argsDelta` is the whole set of arguments, not a
+   * fragment. Set for Gemini (its API returns function-call args
+   * whole in one chunk) and for cache/replay chunks, which are
+   * one-shot too. Omitted or `false` for a genuine fragment from
+   * providers that do stream incrementally (OpenAI-compatible,
+   * Anthropic, Bedrock).
+   */
+  complete?: boolean;
+} | {
+  type: 'usage';
+  usage: TokenUsage;
+};
+/**
+ * What `call()` returns when `stream: true`. `chunks` is for live rendering;
+ * `finalResult` resolves to the same validated `T`/`CallWithToolsResult<T>`
+ * shape `call()` would have returned had `stream` been omitted, once the
+ * stream completes successfully.
+ *
+ * `chunks` is single-use and supports only one consumer: iterating it more
+ * than once, or from more than one place concurrently, shares the same
+ * underlying buffered stream rather than replaying or forking it, which can
+ * split chunks unpredictably between consumers. Stopping iteration early
+ * (e.g. `break`ing out of a `for await`) does not cancel or otherwise
+ * signal the underlying stream, the background pump keeps running to
+ * completion regardless, buffering any chunks emitted after that point, so
+ * `finalResult` still settles normally even if `chunks` is abandoned or
+ * never read at all.
+ *
+ * Unread chunks are buffered internally for the duration of one stream,
+ * this is what lets a caller start iterating `chunks` after the stream has
+ * already progressed (or finished) and still see everything. That backlog
+ * is capped: an unusually large stream whose `chunks` is never read at all
+ * has its oldest buffered chunks dropped once the backlog grows past
+ * roughly twice a fixed internal limit, trimmed back down to that limit in
+ * one batch rather than one-at-a-time, bounding both peak memory and the
+ * eviction work itself for that pathological case instead of the array
+ * growing (or being trimmed) proportional to the whole stream's output.
+ * Ordinary consumption, even started somewhat late, stays far under the
+ * limit and is unaffected.
+ */
+interface StreamCallResult<R> {
+  chunks: AsyncIterable<StreamChunk>;
+  finalResult: Promise<R>;
+}
+/**
+ * A `CallParams` variant where streaming is explicitly enabled.
+ *
+ * Requiring `stream: true` to be statically present allows TypeScript to
+ * select the streaming `call()` overload and return `StreamCallResult<...>`
+ * instead of the normal, single-shot response type.
+ */
+type StreamEnabledCallParams<T> = CallParams<T> & {
+  stream: true;
+};
+/**
+ * The adapter-facing, pre-normalization shape a `createStream` client
+ * implementation emits, analogous to how `WireMessage`/`WireToolCall`
+ * already sit between `CallParams` and each provider's own wire format.
+ */
+type WireStreamChunk = {
+  type: 'text-delta';
+  delta: string;
+} | {
+  type: 'tool_call_delta';
+  index: number;
+  id?: string;
+  name?: string;
+  argumentsDelta?: string;
+  /** Same meaning as `StreamChunk`'s `tool_call_delta.complete`. */
+  complete?: boolean;
+} | {
+  type: 'usage';
+  usage: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+} | {
+  /**
+   * A provider keep-alive signal with no content of its own (e.g.
+   * Anthropic's `ping` events, an SSE comment-line heartbeat).
+   * Adapters yield this so the stream loop resets its idle timeout.
+   * Never surfaced to callers as a `StreamChunk`.
+   */
+  type: 'ping';
+};
+/**
+ * Parameters for a cached, streaming LLM call without tool calling.
+ *
+ * The cached value is `T`, same as `CachedCallParams<T>`, but a miss
+ * relays live `chunks` to the caller while the result is being generated,
+ * and a hit synthesizes a one-shot `chunks` replay from the cached value
+ * (see `VernLLM.cachedCall`'s docs for exactly what that replay looks
+ * like).
+ */
+type CachedStreamCallParams<T> = CachedCallInput & {
+  call: StreamEnabledCallParams<T>;
+};
+/**
+ * Parameters for a cached, streaming LLM call with tool calling enabled.
+ *
+ * The cached value is the full `CallWithToolsResult<T>`, same as
+ * `CachedToolCallParams<T>`, with the same live-chunks-on-miss,
+ * replayed-chunks-on-hit behavior as `CachedStreamCallParams<T>`.
+ */
+type CachedStreamToolCallParams<T> = CachedCallInput & {
+  call: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>;
+};
+
+//#endregion
+//#region src/types/client.d.ts
+//# sourceMappingURL=stream.d.ts.map
+/** A tool call as it appears on the wire, OpenAI's `function`-wrapped shape. */
+interface WireToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    /** JSON-encoded arguments, matching every OpenAI-compatible provider's wire format. */
+    arguments: string;
+  };
+}
+/** One entry of `LLMClient`'s `messages` array, named so callers building it can annotate against it. */
+type WireMessage = {
+  role: 'system';
+  content: string;
+} | {
+  role: 'user';
+  content: string | ContentBlock[];
+} | {
+  role: 'assistant';
+  /** Optional: an assistant turn that only requested tools has no text. */
+  content?: string;
+  tool_calls?: WireToolCall[];
+} | {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+  /** Only honored by `fromAnthropic` today (maps to `tool_result.is_error`); other adapters ignore it. */
+  is_error?: boolean;
+};
+/** The OpenAI-shaped wire `tool_choice`. */
+type WireToolChoice = 'auto' | 'none' | 'required' | {
+  type: 'function';
+  function: {
+    name: string;
+  };
+};
 /**
  * Minimal shape compatible with the OpenAI SDKs chat.completions.create,
  * so consumers can pass an OpenAI client directly
@@ -226,7 +877,7 @@ interface LLMClient {
     completions: {
       create(params: {
         model: string;
-        temperature: number;
+        temperature?: number;
         max_tokens: number;
         response_format?: {
           type: 'json_object';
@@ -241,19 +892,29 @@ interface LLMClient {
         };
         /** OpenAI reasoning-model param (o-series, gpt-5), ignored by providers that don't support it */
         reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
-        messages: Array<{
-          role: 'system' | 'assistant';
-          content: string;
-        } | {
-          role: 'user';
-          content: string | ContentBlock[];
+        /** Tools the model may call, OpenAI's `function`-wrapped shape. */
+        tools?: Array<{
+          type: 'function';
+          function: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+          };
         }>;
+        tool_choice?: WireToolChoice;
+        /**
+         * Wire-format messages. Breaking change for custom adapters:
+         * implementations must handle tool messages and assistant tool_calls.
+         * Exhaustive switches over only system/user/assistant roles may no longer compile.
+         */
+        messages: WireMessage[];
       }, options: {
         signal: AbortSignal;
       }): Promise<{
         choices?: Array<{
           message?: {
             content?: string | null;
+            tool_calls?: WireToolCall[];
           };
         }>;
         usage?: {
@@ -262,54 +923,22 @@ interface LLMClient {
           total_tokens?: number;
         };
       }>;
+      /**
+       * Optional. Required only for `stream: true` calls. Adapters/clients
+       * that don't implement this make `stream: true` throw a clear
+       * `LLMError('validation')` rather than a confusing runtime failure.
+       * Takes the same request shape as `create`, minus the response type.
+       */
+      createStream?(params: Parameters<LLMClient['chat']['completions']['create']>[0], options: {
+        signal: AbortSignal;
+      }): AsyncIterable<WireStreamChunk>;
     };
   };
 }
 
-//#endregion
-//#region src/circuitBreaker.d.ts
-//# sourceMappingURL=client.d.ts.map
-interface CircuitBreakerOptions {
-  /** Consecutive failures before the circuit opens, default 5 */
-  threshold?: number;
-  /** How long the circuit stays open before allowing a trial request, in ms. Default 30000 */
-  cooldownMs?: number;
-}
-type CircuitState = 'closed' | 'open' | 'half-open';
-/**
- * Per retry VernLLM-instance circuit breaker. Tracks consecutive failures across
- * calls. Once the threshold is hit, short-circuits new calls with an
- * LLMError('circuit_open') instead of hitting the provider, until the
- * cooldown elapses and a single trial call is allowed through
- */
-declare class CircuitBreaker {
-  private state;
-  private consecutiveFailures;
-  private openedAt;
-  private threshold;
-  private cooldownMs;
-  /**
-   * True while a single half-open trial call is in flight. Guards against
-   * multiple concurrent callers all treating themselves as "the" trial once
-   * the cooldown elapses
-   */
-  private trialInFlight;
-  constructor(options?: CircuitBreakerOptions);
-  /**
-   * Throws if the circuit is open and the cooldown hasn't elapsed, or if
-   * the circuit is half-open and a trial call is already in flight.
-   * Otherwise, if the circuit just became eligible for a trial (cooldown
-   * elapsed, or half-open with no trial currently running), this call
-   * becomes that trial
-   */
-  assertClosed(): void;
-  recordSuccess(): void;
-  recordFailure(): void;
-  getState(): CircuitState;
-}
-
 //#endregion
 //#region src/logger.d.ts
+//# sourceMappingURL=client.d.ts.map
 interface Logger {
   debug(message: string): void;
   warn(message: string): void;
@@ -328,22 +957,125 @@ declare class ConsoleLogger implements Logger {
 }
 
 //#endregion
-//#region src/types/options.d.ts
+//#region src/types/events.d.ts
 //# sourceMappingURL=logger.d.ts.map
+/**
+ * Reports what happened during a call. Fire and forget, mirroring
+ * `onUsage`: the return value is never read and a throwing handler cannot
+ * change what the call does, only what gets reported about it.
+ */
+type VernLLMEvent = {
+  kind: 'retry';
+  requestId: string;
+  provider: string;
+  /** The model actually resolved for this call (honors a per-call `model` override). */
+  model: string;
+  /** The 1-based retry ordinal (the 1st retry is `1`, not the overall attempt count). */
+  attempt: number;
+  maxRetries: number;
+  delayMs: number;
+  retryAfterHonored: boolean;
+  error: LLMError;
+} | {
+  kind: 'circuit_state';
+  provider: string;
+  /**
+   * The model of the call that triggered this specific transition
+   * (whatever was passed to the `assertClosed`/`recordSuccess`/
+   * `recordFailure` call that caused it), not a property of the
+   * circuit itself: the breaker still counts failures across every
+   * model together, so a threshold crossing can be the sum of
+   * several different models' failures even though only the
+   * triggering call's `model` is reported here.
+   */
+  model: string;
+  from: CircuitState;
+  to: CircuitState;
+  consecutiveFailures: number;
+} | {
+  kind: 'fallback';
+  requestId: string;
+  /** Provider name of the target that just failed. */
+  from: string;
+  /** Provider name of the target about to be tried next. */
+  to: string;
+  /** `-1` for the primary target, otherwise the index into `fallback`. */
+  fromIndex: number;
+  toIndex: number;
+  /** The normalized error that caused `from` to be abandoned. */
+  error: LLMError;
+  /** Time spent on `from`, including its own retries, before giving up. */
+  elapsedMs: number;
+} | {
+  kind: 'rate_limited';
+  requestId: string;
+  provider: string;
+  /** The model actually resolved for this call (honors a per-call `model` override). */
+  model: string;
+  /** How long this attempt sat queued for capacity before it was let through. */
+  waitedMs: number;
+  /** Which configured bucket was blocking this attempt just before it cleared. */
+  reason: 'concurrency' | 'rpm' | 'tpm';
+};
+type OnEvent = (event: VernLLMEvent) => void;
+
+//#endregion
+//#region src/types/options.d.ts
+//# sourceMappingURL=events.d.ts.map
 interface VernLLMOptions {
   client: LLMClient;
   model: string;
+  /**
+   * Label for this provider in usage (`TokenUsage.provider`) and events.
+   * Default `'primary'`.
+   */
+  name?: string;
   /** Max retries after the first attempt. Default 1 (2 attempts total) */
   maxRetries?: number;
   /** Per-attempt timeout in ms. Default 25000 */
   timeoutMs?: number;
+  /**
+   * For `stream: true` calls: max gap allowed between chunks once the
+   * stream has opened, in ms. Resets on every chunk, including keep-alive
+   * pings. `timeoutMs` only covers opening the stream and its first
+   * chunk; this covers every gap after that. Also counts as a
+   * circuit-breaker failure, unlike other mid-stream errors, since a
+   * provider that streams one chunk then stalls should still trip it.
+   * Default 30000. Pass 0 or negative to disable.
+   */
+  chunkIdleTimeoutMs?: number;
   /** Base delay for exponential backoff in ms. Default 500 */
   baseDelayMs?: number;
   /** Default max_tokens for calls that don't override it. Default 1000 */
   defaultMaxTokens?: number;
-  /** Enables debug logging of raw model output (logs up to 800 chars of each
-   * response). Off by default */
+  /**
+   * Default temperature for calls that don't override it. Default 0.2, not
+   * the provider's own default. Pass `null` to omit `temperature` from the
+   * request entirely, so the provider applies its own default instead.
+   */
+  defaultTemperature?: number | null;
+  /**
+   * Enables debug logging of raw model output (logs up to 800 chars of each
+   * response) and provider errors. Off by default. Only controls the
+   * default `ConsoleLogger`: when a custom `logger` is supplied instead,
+   * that logger's own `debug()` implementation decides whether messages
+   * are emitted, and this option has no effect on it.
+   */
   debug?: boolean;
+  /**
+   * Applied before every internal `logger.debug()` call: the raw output
+   * logged on success, and the provider error logged on a failed call or
+   * a failed stream open. This is the one piece of logging an app can't
+   * intercept itself, since it's a direct call into `logger.debug`
+   * rather than something routed through `onEvent`/`onUsage`; anything
+   * caught elsewhere (events, `LLMError.cause`) already passes through
+   * the app's own callback and can be redacted there instead. Runs
+   * before `logger.debug()` regardless of whether that call ends up
+   * emitting anything, so with a custom `logger`, `redact` still applies
+   * even without `debug: true`; see `debug` for why. Default: identity
+   * (no redaction).
+   */
+  redact?: (text: string) => string;
   /** Cache adapter for cachedCall. Defaults to an in-memory adapter */
   cache?: CacheAdapter;
   /** HTTP status codes that should fail fast without retrying. Default [400, 401, 403, 404, 422] */
@@ -352,6 +1084,18 @@ interface VernLLMOptions {
   parseJson?: (content: string) => unknown;
   /** Called after every successful call with token usage, if the provider reports it */
   onUsage?: OnUsage;
+  /**
+   * Called when a provider response arrives but VernLLM's own post-processing
+   * then fails, after usage data was already present in that response.
+   * Separate from `onUsage`, which only fires on full success.
+   *
+   * For non-streaming calls, never fires for transport failures (timeout,
+   * network error, non-retryable status), since no response means no usage
+   * to report. For streaming calls, this is not guaranteed: a stream can
+   * deliver a usage chunk and then fail later (e.g. an idle timeout waiting
+   * for the final close), in which case this does fire.
+   */
+  onUsageFailure?: OnUsageFailure;
   /** Injectable logger. Defaults to a console-based logger gated by `debug` */
   logger?: Logger;
   /**
@@ -360,136 +1104,289 @@ interface VernLLMOptions {
    * Pass `true` for defaults, or an options object to tune threshold/cooldown
    */
   circuitBreaker?: boolean | CircuitBreakerOptions;
+  /**
+   * Reports retries and circuit-breaker state transitions as they happen.
+   * Fire and forget: a throwing handler is caught and logged, and its
+   * return value is never read, so it cannot influence the call.
+   */
+  onEvent?: OnEvent;
+  /**
+   * Client-side rate limiting. Queues calls locally to stay under the
+   * configured requests/tokens-per-minute or concurrency caps, instead of
+   * letting the provider reject them. Independent of the `Retry-After`
+   * handling already applied to a provider 429: this avoids tripping the
+   * limit in the first place. Omit for unlimited (the default).
+   */
+  rateLimit?: RateLimitOptions;
+  /**
+   * Ordered targets tried after the primary, in order, once it (and its
+   * own retries) is exhausted or abandoned. Order is the policy: VernLLM
+   * never reorders, scores, or selects between targets. Each target keeps
+   * its own retry state, circuit breaker, and rate limiter, independent
+   * of every other target's. A single `FallbackTarget` is equivalent to
+   * `[target]`.
+   */
+  fallback?: FallbackTarget | FallbackTarget[];
+  /**
+   * Decides what happens after a target fails: `'next'` to move on to
+   * the following target (or throw, if it was the last one), `'stop'` to
+   * give up immediately without trying any remaining targets. Called
+   * once per failed target, after that target's own retries are
+   * exhausted or abandoned early, so `'retry'` is never a valid return
+   * here. Defaults to `defaultFallbackOn`, which stops on
+   * parse/validation/aborted/quota errors and on tool-contract failures
+   * (the model ignoring the request, not the provider being unhealthy),
+   * and moves on for everything else.
+   */
+  fallbackOn?: FallbackOn;
 }
 
 //#endregion
 //#region src/vernLLM.d.ts
 //# sourceMappingURL=options.d.ts.map
 /**
- * A resilient layer around an LLM chat completions client, this is VernLLM!
+ * A resilient layer around an LLM chat completions client. This is VernLLM!
  *
- * Adds retry with backoff/jitter, per-attempt timeouts, an optional circuit breaker,
- * JSON parsing with optional schema validation, usage tracking, and an
- * optional response cache, all configurable, all opt-in beyond sensible
- * defaults.
+ * Adds retry with backoff and jitter, per-attempt timeouts, an optional
+ * circuit breaker, JSON parsing with optional schema validation, usage
+ * tracking, and an optional response cache. All configurable, all opt-in
+ * beyond sensible defaults.
  */
 declare class VernLLM {
-  private readonly client;
-  private readonly model;
-  private readonly maxRetries;
-  private readonly timeoutMs;
-  private readonly baseDelayMs;
-  private readonly defaultMaxTokens;
-  private readonly cache;
-  private readonly nonRetryableStatus;
-  private readonly inFlight;
-  private readonly parseJson;
-  private readonly onUsage?;
   private readonly logger;
-  private readonly breaker?;
   /**
-   * @param options - Client, model, and tunables. Notable defaults:
-   * `maxRetries` 1, `timeoutMs` 25000, `baseDelayMs` 500 (exponential backoff
-   * base), `defaultMaxTokens` 1000, `cache` an in-memory adapter,
-   * `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
+   * 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.
    */
-  constructor(options: VernLLMOptions);
-  /** Resolves a cache key through the adapter when it supports normalization. */
-  private resolveCacheKey;
+  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;
   /**
-   * 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. On exhausting retries, records a breaker failure and rejects
-   * with a normalized LLMError.
-   *
-   * @param params - System/user content plus per-call overrides (model,
-   * temperature, jsonMode, schema, signal, etc). See `CallParams`.
-   * @returns The parsed (and optionally schema-validated) response, or the
-   * raw string content when `jsonMode` is false and no `jsonSchema` is set.
+   * 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.
    */
-  call<T = unknown>(params: CallParams<T>): Promise<T>;
-  /** Runs `fn`, retrying with backoff according to `shouldRetry`. */
-  private retryWithBackoff;
+  private readonly cacheOrchestrator;
   /**
-   * Performs a single attempt: builds the request, dispatches it with a
-   * timeout, and shapes the response. Throws on an empty response so the
-   * retry loop treats it like any other transient failure.
+   * @param options Client, model, and tunables. Defaults: `maxRetries` 1,
+   * `timeoutMs` 25000, `baseDelayMs` 500, `defaultMaxTokens` 1000,
+   * `defaultTemperature` 0.2, `cache` an in-memory adapter,
+   * `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
    */
-  private executeCall;
+  constructor(options: VernLLMOptions);
+  /** Logs a failed refundUsage attempt via the configured logger. */
+  private logRefundError;
   /**
-   * Validates `history` alternates user/assistant turns, since providers
-   * like Anthropic/Gemini reject or mishandle consecutive same-role turns.
+   * 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 validateHistory;
-  /** Applies per-call defaults and shapes params into the client's request object. */
-  private buildRequestPayload;
+  private runFallbackChain;
   /**
-   * Chooses the response format: a provider-native `jsonSchema` takes
-   * priority when supplied (constrains generation directly), otherwise
-   * falls back to the looser `json_object` mode when JSON output is
-   * requested, or no format at all for plain text responses.
+   * 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 only picks the tools-aware overload when `tools` is
+   * statically present on `params`. If set conditionally on a plain
+   * `CallParams<T>`, use `isToolCallResult()` to check the shape at
+   * runtime instead. 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.
+   *
+   * @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>`.
+   * With `stream: true` (statically): a `{ chunks, finalResult }`
+   * `StreamCallResult`, `finalResult` resolving to whichever of the above
+   * shapes applies once the stream completes. See `StreamCallResult`.
    */
-  private buildResponseFormat;
-  /** Reports token usage to `onUsage`, swallowing and logging any error it throws. */
-  private recordUsage;
-  /** Parses response content as JSON and validates it against `schema` when supplied. */
-  private parseAndValidate;
+  call<T = unknown>(params: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
+  call<T = unknown>(params: StreamEnabledCallParams<T>): Promise<StreamCallResult<T>>;
+  call<T = unknown>(params: ToolEnabledCallParams<T>): Promise<CallWithToolsResult<T>>;
+  call<T = unknown>(params: CallParams<T>): Promise<T>;
   /**
-   * Waits out the backoff delay for a retry attempt, honoring a
-   * Retry-After header on the failed attempt's error when present.
-   * Both Retry-After and plain exponential backoff are capped at the same
-   * max delay (see `DEFAULT_MAX_DELAY_MS` in `vernLLM.utils.ts`).
+   * Thin delegator kept private on `VernLLM` (rather than only existing on
+   * `CacheOrchestrator`) since it's the one caching primitive exercised
+   * directly by white-box tests, independent of the public `cachedCall()`
+   * surface.
    */
-  private recoverDelay;
-  /** Decides whether a failed attempt is worth retrying. */
-  private shouldRetry;
+  private runCached;
   /**
    * Removes a cached response by key when the configured cache adapter
    * supports deletion. Cache invalidation is the caller's responsibility;
    * only the application knows when cached data is stale.
    *
-   * @param key - The raw cache key (resolved through the adapter's
+   * @param key The raw cache key (resolved through the adapter's
    * `resolveKey`, if any, before deletion).
    */
   deleteCache(key: string): Promise<void>;
   /**
-   * Cache wrapper around caller-supplied logic. Concurrent misses for the
-   * same `cacheKey` share a single in-flight call, avoiding cache stampedes.
-   *
-   * @param params - `cacheKey`, `ttl`, `fn` (the work to run on a cache
-   * miss, typically `() => this.call(...)`), and optional
-   * `reserveUsage`/`refundUsage`/`signal`. See `CachedCallParams`.
-   * @returns The cached value on a hit, or the result of `fn()` on a miss.
-   */
-  cachedCall<T>(params: CachedCallParams<T>): Promise<T>;
-  /** Starts the shared fn() call for a cache miss and tracks it in the in-flight map until it settles. */
-  private registerTrigger;
-  /** Runs `fn` and writes its result to the cache. */
-  private runAndCache;
-  /** Logs a failed refundUsage attempt via the configured logger. */
-  private logRefundError;
-  /**
-   * Convenience wrapper composing `call` + `cachedCall`, so cached LLM calls
+   * 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.
+   * `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.
    *
-   * @param params - `cachedCall` params (`cacheKey`, `ttl`, etc, minus `fn`)
-   * plus `call`, the `CallParams` to pass through to `this.call(...)`.
+   * 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.
+   *
+   * 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.
+   *
+   * @param params `cacheKey`, `ttl`, and 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`.
    * @returns The cached value on a hit, or the freshly-called result on a miss.
    */
-  cachedLLMCall<T>(params: Omit<CachedCallParams<T>, 'fn'> & {
-    call: CallParams<T>;
-  }): Promise<T>;
+  cachedCall<T>(params: CachedStreamToolCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
+  cachedCall<T>(params: CachedStreamCallParams<T>): Promise<StreamCallResult<T>>;
+  cachedCall<T>(params: CachedToolCallParams<T>): Promise<CallWithToolsResult<T>>;
+  cachedCall<T>(params: CachedCallParams<T>): Promise<T>;
   /**
+   * @param model With `circuitBreaker.isolateByModel` on, returns that
+   * model's own circuit state instead of the shared one. Ignored
+   * otherwise. Omit for the shared circuit (the default) or, under
+   * isolation, the state of calls that didn't resolve a model.
    * @returns The current circuit breaker state (`'closed' | 'open' |
    * 'half-open'`), or undefined if no circuit breaker was configured.
    */
-  getCircuitState(): ("closed" | "open" | "half-open") | undefined;
+  getCircuitState(model?: string): CircuitState | undefined;
+  /**
+   * @param model With `circuitBreaker.isolateByModel` on, returns each
+   * target's circuit state for that model instead of its shared state.
+   * Ignored otherwise. Omit for the shared circuit (the default) or, under
+   * isolation, the state of calls that didn't resolve a model.
+   * @returns The current circuit state for every target in declaration
+   * order, including the primary and all fallback targets. Each entry
+   * includes the target's provider name, chain index, whether it is a
+   * fallback, and its circuit state, or undefined if that target has no
+   * circuit breaker configured.
+   */
+  getCircuitStates(model?: string): TargetCircuitState[];
 }
 
 //#endregion
-//#region src/adapters/anthropic.d.ts
+//#region src/adapters/internal/sse.d.ts
 //# sourceMappingURL=vernLLM.d.ts.map
+/**
+ * Parses a Server-Sent-Events byte/text stream into the JSON payload of
+ * each `data:` frame, in arrival order. Generic over transport: works with
+ * anything that hands back progressively-arriving `Uint8Array` or `string`
+ * chunks via async iteration: native `fetch`'s `response.body` (wrapped
+ * to be iterable, see `webStreamToAsyncIterable` in `fetch.ts`), axios's
+ * Node `Readable` (already async-iterable, no wrapping needed), etc, so
+ * this framing layer doesn't care which transport produced the bytes.
+ *
+ * Follows the SSE spec's frame-delimiting rules closely enough for LLM
+ * streaming responses: frames are separated by a blank line, each frame
+ * may carry one or more `data:` lines (joined with `\n` per spec when
+ * there's more than one), `:`-prefixed lines are comments and ignored, and
+ * other SSE fields (`event:`, `id:`, `retry:`) are ignored since VernLLM
+ * only needs the payload. A frame whose data is exactly `[DONE]` (the
+ * sentinel several providers, notably OpenAI, send to mark stream end)
+ * ends iteration without yielding it.
+ *
+ * Line endings: `\r\n` and bare `\r` (both legal per the SSE spec, alongside `\n`) are normalized
+ * to `\n` before frame splitting. A `\r` at the very end of the currently-buffered text is left
+ * alone until either more text arrives (in case it's the first half of a split `\r\n` pair) or the
+ * stream ends, so a `\r\n` pair split across two transport chunks is never misread as two blank
+ * lines.
+ *
+ * Malformed JSON in a frame throws `LLMError('parse')`, consistent with
+ * how malformed JSON is handled elsewhere in VernLLM.
+ */
+declare function parseSseStream(source: AsyncIterable<Uint8Array | string>): AsyncGenerator<unknown>;
+/**
+ * Sentinel yielded by `parseSseStream` for a comment-only frame (no
+ * `data:` payload), the mechanism providers use for SSE keep-alive
+ * pings. Exported so a consumer (e.g. `fromFetch`) can react to "still
+ * alive" separately from a genuinely empty frame (`NO_DATA`, kept internal).
+ */
+declare const SSE_PING: unique symbol;
+
+//#endregion
+//#region src/adapters/internal/imageFormat.d.ts
+//# sourceMappingURL=sse.d.ts.map
+/**
+ * MIME types accepted for `ImageBlock.mimeType` across all adapters. This is
+ * the intersection of what Anthropic, Gemini, OpenAI-compatible, and Bedrock
+ * Converse all natively support, so a `ContentBlock[]` that validates for
+ * one provider validates for all of them.
+ */
+declare const SUPPORTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
+
+//#endregion
+//#region src/adapters/internal/nativeStructuredOutput.d.ts
+/**
+ * Validates an `ImageBlock.mimeType` against the shared supported set.
+ * Throws a non-retryable `LLMError('validation')`, since an unsupported
+ * mimeType is a permanent failure, retrying the same input can't fix it,
+ * the same way a schema-validation or JSON-parse failure isn't retried.
+ */
+
+/**
+ * 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
+ * from `tools`/`tool_choice`, so it can be combined with real,
+ * caller-supplied `tools` in the same request.
+ *
+ * There is no built-in default list here. Which models support this is
+ * 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.
+ */
+type ModelCapabilityOverride = string[] | ((model: string) => boolean);
+
+//#endregion
+//#region src/adapters/anthropic.d.ts
+/** Resolves whether `model` is covered by a caller-supplied allow-list/predicate. */
 /** Anthropic's native per-block content shape for a message. */
 type AnthropicContentBlock = {
   type: 'text';
@@ -498,9 +1395,19 @@ type AnthropicContentBlock = {
   type: 'image';
   source: {
     type: 'base64';
-    media_type: string;
+    media_type: SupportedImageMimeType;
     data: string;
   };
+} | {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: unknown;
+} | {
+  type: 'tool_result';
+  tool_use_id: string;
+  content: string;
+  is_error?: boolean;
 };
 /** Minimal structural type for the Anthropic SDK's `messages.create` */
 interface AnthropicClient {
@@ -517,19 +1424,51 @@ interface AnthropicClient {
       tools?: Array<{
         name: string;
         description?: string;
-        input_schema: Record<string, unknown>;
+        input_schema: {
+          type: 'object';
+          [key: string]: unknown;
+        };
         strict?: boolean;
       }>;
       tool_choice?: {
+        type: 'auto';
+      } | {
+        type: 'any';
+      } | {
+        type: 'none';
+      } | {
         type: 'tool';
         name: string;
       };
+      /**
+       * Native, schema-constrained output: a separate request field from
+       * `tools`/`tool_choice`, so it can be sent alongside real tool
+       * calls. Only built by this adapter for models covered by
+       * `nativeStructuredOutputModels` (opt-in, see
+       * `AnthropicAdapterOptions`); other models keep getting
+       * `jsonSchema` emulated as a forced single tool call, the
+       * pre-existing behavior.
+       *
+       * Matches the real Anthropic API's `output_config.format` shape
+       * exactly: just `type` and `schema`, no `name`/`description`/
+       * `strict`. Those three exist on VernLLM's own `jsonSchema` API
+       * (and are still forwarded on the legacy forced-tool-call path,
+       * where they're real `Tool` fields), but the native structured-
+       * output endpoint has no equivalent for any of them.
+       */
+      output_config?: {
+        format: {
+          type: 'json_schema';
+          schema: Record<string, unknown>;
+        };
+      };
     }, options: {
       signal: AbortSignal;
     }): Promise<{
       content: Array<{
         type: string;
         text?: string;
+        id?: string;
         name?: string;
         input?: unknown;
       }>;
@@ -540,21 +1479,50 @@ interface AnthropicClient {
     }>;
   };
 }
+/** Optional configuration for `fromAnthropic`. */
+interface AnthropicAdapterOptions {
+  /**
+   * Which models support native, schema-constrained output
+   * (`output_config.format`), independent of `tools`/`tool_choice`, so it
+   * can be combined with real `tools` in one request. Pass a static list
+   * of model IDs (verified against Anthropic's own docs) or a predicate.
+   *
+   * There is no built-in default here (see `supportsNativeStructuredOutput`
+   * for why). Left unset, every model uses the older forced-single-tool-
+   * call emulation, and `tools` + `jsonSchema` together is rejected,
+   * exactly this adapter's behavior before native support was added.
+   */
+  nativeStructuredOutputModels?: ModelCapabilityOverride;
+}
 /**
  * Wraps an Anthropic SDK client so it satisfies the same `LLMClient`
  * interface VernLLM uses for OpenAI/Groq.
  *
- * `response_format: json_schema` is mapped to Anthropic's forced tool-use:
- * a single tool is defined with `input_schema` set to the caller's schema,
- * `description` forwarded when provided, and `strict` forwarded when set.
- * `tool_choice` forces the model to call it. Provider-constrained schema
- * matching applies only when `strict: true` is forwarded and supported.
+ * `response_format: json_schema`, on a model covered by
+ * `options.nativeStructuredOutputModels`, is sent as `output_config.format`,
+ * its own request field, independent of `tools`/`tool_choice`, so it can be
+ * combined with real, caller-supplied `tools` in the same request. Only
+ * `type` and `schema` are sent on this path, the real Anthropic API's
+ * `output_config.format` has no `name`/`description`/`strict` fields.
+ *
+ * On any other model (the default, since `nativeStructuredOutputModels` is
+ * opt-in), `response_format: json_schema` is mapped to Anthropic's forced
+ * tool-use instead: a single tool is defined with `input_schema` set to
+ * the caller's schema, `description` forwarded when provided, and `strict`
+ * 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
+ * schema matching applies only when `strict: true` is forwarded and
+ * supported.
  *
  * `response_format: json_object` (no schema to build a tool from) falls
  * back to a system-prompt instruction, since there's nothing to constrain
- * generation against.
+ * generation against. Unlike `jsonSchema`, this combines with real `tools`
+ * freely on every model: it's a prompt nudge, not a request field, so
+ * there's nothing for it to collide with.
  */
-declare function fromAnthropic(anthropicClient: AnthropicClient): LLMClient;
+declare function fromAnthropic(anthropicClient: AnthropicClient, options?: AnthropicAdapterOptions): LLMClient;
 
 //#endregion
 //#region src/adapters/gemini.d.ts
@@ -566,13 +1534,30 @@ type GeminiPart = {
     mimeType: string;
     data: string;
   };
+} | {
+  functionCall: {
+    name: string;
+    args: unknown;
+  };
+} | {
+  functionResponse: {
+    name: string;
+    response: unknown;
+  };
 };
 /**
- * Minimal structural type for VernLLM's two-argument wrapper around Gemini
- * `generateContent`. The wrapper exposes a request shape aligned with the
- * adapter interface, with top-level `systemInstruction` and
- * `generationConfig` fields, while transport options (such as `AbortSignal`)
- * are passed separately as the second argument.
+ * Structural type matching the real `@google/genai` SDK's `ai.models`
+ * object: `generateContent`/`generateContentStream` both take a single
+ * `{ model, contents, config }` argument (config carries
+ * `systemInstruction`, `tools`, `toolConfig`, generation settings, and
+ * `abortSignal` all together), matching the real SDK closely enough that
+ * `fromGemini(ai.models)` works directly, e.g:
+ *
+ * ```ts
+ * import { GoogleGenAI } from '@google/genai';
+ * const ai = new GoogleGenAI({ apiKey: '...' });
+ * const llm = new VernLLM({ client: fromGemini(ai.models), model: 'gemini-2.5-flash' });
+ * ```
  */
 interface GeminiClient {
   generateContent(params: {
@@ -581,24 +1566,40 @@ interface GeminiClient {
       role: 'user' | 'model';
       parts: GeminiPart[];
     }>;
-    systemInstruction?: {
-      parts: Array<{
-        text: string;
-      }>;
-    };
-    generationConfig?: {
+    config?: {
+      systemInstruction?: {
+        parts: Array<{
+          text: string;
+        }>;
+      };
       temperature?: number;
       maxOutputTokens?: number;
       responseMimeType?: string;
       responseSchema?: Record<string, unknown>;
+      tools?: Array<{
+        functionDeclarations: Array<{
+          name: string;
+          description?: string;
+          parameters: Record<string, unknown>;
+        }>;
+      }>;
+      toolConfig?: {
+        functionCallingConfig: {
+          mode: 'AUTO' | 'ANY' | 'NONE';
+          allowedFunctionNames?: string[];
+        };
+      };
+      abortSignal?: AbortSignal;
     };
-  }, options: {
-    signal: AbortSignal;
   }): Promise<{
     candidates?: Array<{
       content?: {
         parts?: Array<{
           text?: string;
+          functionCall?: {
+            name: string;
+            args: unknown;
+          };
         }>;
       };
     }>;
@@ -608,6 +1609,32 @@ interface GeminiClient {
       totalTokenCount?: number;
     };
   }>;
+  /**
+   * Optional. Required only for `stream: true` calls. Takes the same
+   * request shape as `generateContent`. Matching the real SDK's own
+   * `generateContentStream`, this resolves to an `AsyncIterable` (rather
+   * than returning one synchronously) of partial responses, each chunk
+   * holding the same `candidates[].content.parts[]` structure as
+   * `generateContent`'s response, just incremental.
+   */
+  generateContentStream?(params: Parameters<GeminiClient['generateContent']>[0]): Promise<AsyncIterable<{
+    candidates?: Array<{
+      content?: {
+        parts?: Array<{
+          text?: string;
+          functionCall?: {
+            name: string;
+            args: unknown;
+          };
+        }>;
+      };
+    }>;
+    usageMetadata?: {
+      promptTokenCount?: number;
+      candidatesTokenCount?: number;
+      totalTokenCount?: number;
+    };
+  }>>;
 }
 /**
  * Wraps a Gemini client so it satisfies the `LLMClient` interface VernLLM
@@ -619,6 +1646,25 @@ interface GeminiClient {
  * `responseSchema`. `reasoning_effort` has no equivalent. Gemini's thinking
  * models use a token budget, not an effort tier, so it's dropped, same as
  * Anthropic.
+ *
+ * `tools` maps to Gemini's native `functionDeclarations`/`functionCall`;
+ * `tool_choice` maps to `toolConfig.functionCallingConfig`. Gemini accepts
+ * `responseSchema` and `tools` in the same request natively, so both are
+ * set independently here and no special-casing is needed for the
+ * combination, unlike `fromAnthropic`/`fromBedrock`.
+ *
+ * `createStream` calls `generateContentStream` (optional on `GeminiClient`
+ *, required only if the caller sets `stream: true`) and translates each
+ * partial response into `WireStreamChunk`s. Unlike OpenAI/Anthropic,
+ * Gemini's own function-calling API doesn't stream tool-call arguments
+ * incrementally: a `functionCall` part always arrives whole in one chunk,
+ * so each one is emitted as a single, complete `tool_call_delta` (a
+ * one-shot "delta" containing the full arguments) rather than accumulated
+ * fragments, that's a real difference in the underlying API, not
+ * something this adapter can smooth over. `usageMetadata` is (per Gemini's
+ * own behavior) only reliably present on the last chunk, so the `usage`
+ * `WireStreamChunk` is emitted once, after the stream completes, from
+ * whichever chunk's `usageMetadata` was seen last.
  */
 declare function fromGemini(geminiClient: GeminiClient): LLMClient;
 
@@ -636,6 +1682,20 @@ type BedrockContentBlock = {
       bytes: Uint8Array;
     };
   };
+} | {
+  toolUse: {
+    toolUseId: string;
+    name: string;
+    input: unknown;
+  };
+} | {
+  toolResult: {
+    toolUseId: string;
+    content: Array<{
+      text: string;
+    }>;
+    status?: 'success' | 'error';
+  };
 };
 /**
  * Minimal structural type matching AWS Bedrock's Converse API. This is
@@ -682,6 +1742,38 @@ interface BedrockConverseClient {
         tool: {
           name: string;
         };
+      } | {
+        auto: Record<string, never>;
+      } | {
+        any: Record<string, never>;
+      };
+    };
+    /**
+     * Native, schema-constrained output: a separate request field from
+     * `toolConfig`, so it can be sent alongside real tool calls. Only
+     * built by this adapter for models covered by
+     * `nativeStructuredOutputModels` (opt-in, see
+     * `BedrockAdapterOptions`); other models keep getting `jsonSchema`
+     * emulated as a forced single tool call via `toolConfig`, the
+     * pre-existing behavior.
+     *
+     * Matches the real Bedrock Converse API's `outputConfig.textFormat`
+     * shape exactly: the schema itself is nested one level deeper, under
+     * `structure.jsonSchema`, not flat on `textFormat`, and `schema` is
+     * a JSON-encoded *string*, not a parsed object, unlike every other
+     * schema field this adapter builds (`toolSpec.inputSchema.json`
+     * included). There is no `strict` field here, unlike `toolSpec`.
+     */
+    outputConfig?: {
+      textFormat: {
+        type: 'json_schema';
+        structure: {
+          jsonSchema: {
+            schema: string;
+            name?: string;
+            description?: string;
+          };
+        };
       };
     };
   }, options: {
@@ -692,6 +1784,7 @@ interface BedrockConverseClient {
         content?: Array<{
           text?: string;
           toolUse?: {
+            toolUseId?: string;
             name?: string;
             input?: unknown;
           };
@@ -704,24 +1797,122 @@ interface BedrockConverseClient {
       totalTokens?: number;
     };
   }>;
+  /**
+   * Optional. Required only for `stream: true` calls. Takes the same
+   * request shape `converse` does, returning `{ stream }`, matching
+   * `ConverseStreamCommand`'s real AWS SDK v3 output shape, an
+   * `AsyncIterable` of incremental events under a `stream` property,
+   * rather than the whole response being the iterable directly.
+   */
+  converseStream?(params: Parameters<BedrockConverseClient['converse']>[0], options: {
+    signal: AbortSignal;
+  }): Promise<{
+    stream: AsyncIterable<BedrockConverseStreamEvent>;
+  }>;
 }
+/**
+ * One event of a Bedrock `ConverseStreamCommand` response's `stream`.
+ * Content blocks (text or toolUse) are identified by `contentBlockIndex`,
+ * Converse's own convention for correlating start/delta/stop events across
+ * possibly-interleaved blocks, mirrored directly by VernLLM's
+ * `tool_call_delta.index`.
+ */
+type BedrockConverseStreamEvent = {
+  messageStart: {
+    role: 'assistant';
+  };
+} | {
+  contentBlockStart: {
+    contentBlockIndex: number;
+    start?: {
+      toolUse?: {
+        toolUseId?: string;
+        name?: string;
+      };
+    };
+  };
+} | {
+  contentBlockDelta: {
+    contentBlockIndex: number;
+    delta?: {
+      text?: string;
+    } | {
+      toolUse?: {
+        input?: string;
+      };
+    };
+  };
+} | {
+  contentBlockStop: {
+    contentBlockIndex: number;
+  };
+} | {
+  messageStop: {
+    stopReason?: string;
+  };
+} | {
+  metadata: {
+    usage?: {
+      inputTokens?: number;
+      outputTokens?: number;
+      totalTokens?: number;
+    };
+  };
+} | {
+  internalServerException: {
+    message?: string;
+  };
+} | {
+  modelStreamErrorException: {
+    message?: string;
+    originalStatusCode?: number;
+  };
+} | {
+  validationException: {
+    message?: string;
+  };
+} | {
+  throttlingException: {
+    message?: string;
+  };
+} | {
+  serviceUnavailableException: {
+    message?: string;
+  };
+};
 /**
  * Optional configuration for `fromBedrock`.
  */
 interface BedrockAdapterOptions {
   /**
-   * Optional preflight check for tool-use support, needed for `jsonSchema`
-   * structured output. VernLLM never guesses capability from a failed
-   * call's error message (AWS's error text isn't a documented, stable
-   * contract), so this is opt-in: pass either a static list of tool-use
-   * -capable model IDs, or a predicate function, and VernLLM will reject
-   * unsupported models with a clear `LLMError('validation')` *before*
-   * dispatching the request, instead of on the wire.
+   * Optional preflight check for tool-use support, needed whenever a
+   * `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
+   * text isn't a documented, stable contract), so this is opt-in: pass
+   * either a static list of tool-use-capable model IDs, or a predicate
+   * function, and VernLLM will reject unsupported models with a clear
+   * `LLMError('validation')` *before* dispatching the request, instead of
+   * on the wire.
    *
    * Left unset (default), no preflight check runs, and a `jsonSchema` call
    * to an unsupported model surfaces Bedrock's raw `converse` error as-is.
    */
   toolUseSupportedModels?: string[] | ((modelId: string) => boolean);
+  /**
+   * Which models support native, schema-constrained output
+   * (`outputConfig.textFormat`), independent of `toolConfig`, so it can be
+   * combined with real `tools` in one request. Pass a static list of
+   * model IDs (verified against Bedrock's own docs) or a predicate.
+   *
+   * There is no built-in default here (see `supportsNativeStructuredOutput`
+   * for why). Left unset, every model uses the older forced-single-tool-
+   * call emulation via `toolConfig`, and `tools` + `jsonSchema` together is
+   * rejected, exactly this adapter's behavior before native support was
+   * added.
+   */
+  nativeStructuredOutputModels?: ModelCapabilityOverride;
 }
 /**
  * Wraps a Bedrock Converse-API client so it satisfies the `LLMClient`
@@ -731,18 +1922,48 @@ interface BedrockAdapterOptions {
  * regardless of which underlying model `modelId` points at, as long as
  * that model supports Converse (most current-generation ones do)
  *
- * `response_format: json_schema` is mapped to Converse's `toolConfig`: a
- * single tool is defined from the schema, description, and strictness settings,
- * and `toolChoice` forces the model to call it. 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
+ * `response_format: json_schema`, on a model covered by
+ * `options.nativeStructuredOutputModels` (opt-in, unset by default), is
+ * sent as `outputConfig.textFormat`, its own request field, independent of
+ * `toolConfig`, so it can be combined with real, caller-supplied `tools`
+ * in the same request. Matches the real Converse API's shape exactly: the
+ * schema is nested under `structure.jsonSchema` and JSON-encoded as a
+ * string, not the parsed object `toolConfig`'s tool schemas use, and there
+ * is no `strict` field on this path.
+ *
+ * On any other model (the default), `response_format: json_schema` is
+ * mapped to Converse's `toolConfig` instead: a single tool is defined from
+ * 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.
+ * 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
  * `BedrockAdapterOptions`), otherwise a `jsonSchema` call to an
  * unsupported model surfaces Bedrock's raw error unchanged.
  *
  * `response_format: json_object` (no schema to build a tool from) and
  * `reasoning_effort` (no Converse equivalent) fall back to a system-prompt
- * instruction and are dropped respectively.
+ * instruction and are dropped respectively. Unlike `jsonSchema`,
+ * `json_object` combines with real `tools` freely on every model: it's a
+ * prompt nudge, not a request field, so there's nothing for it to collide
+ * with.
+ *
+ * `tools` alone maps to Converse's native `toolConfig`/`toolUse`/
+ * `toolResult`; `tool_choice` maps to `toolConfig.toolChoice`.
+ *
+ * `createStream` calls `converseStream` (optional on `BedrockConverseClient`
+ *, required only if the caller sets `stream: true`) and translates its
+ * `contentBlockStart`/`contentBlockDelta`/`metadata` events into
+ * `WireStreamChunk`s. Content blocks are tracked by `contentBlockIndex`,
+ * same as `fromAnthropic`'s block-index tracking (Converse's streaming
+ * shape is structurally close to Anthropic's own, both being tool-use-aware
+ * content-block streams), including the same `json-tool` unwrapping: a
+ * `jsonSchema`-forced tool's `toolUse.input` deltas are re-emitted as
+ * `text-delta`, not `tool_call_delta`, so the accumulated result lands in
+ * `finalizeResponse`'s `content` path exactly like the non-streaming
+ * `create` branch above unwraps it.
  */
 declare function fromBedrock(bedrockClient: BedrockConverseClient, options?: BedrockAdapterOptions): LLMClient;
 
@@ -772,6 +1993,22 @@ type RequestLike = (url: string, init: {
   body?: string;
   signal?: AbortSignal;
 }) => Promise<ResponseLike>;
+/**
+ * A streaming-capable request function. Unlike `RequestLike`, which returns
+ * a fully-buffered `ResponseLike`, this resolves to an `AsyncIterable` of
+ * progressively-arriving chunks, the common ground across transports:
+ * native `fetch`'s `response.body` (wrapped to be iterable; see
+ * `webStreamToAsyncIterable` below), axios's Node `Readable` in
+ * `responseType: 'stream'` mode (already async-iterable, no wrapping
+ * needed), `node-fetch`, `undici`, etc, all satisfy this with little or no
+ * glue code. Defaults to native `fetch`.
+ */
+type StreamRequestLike = (url: string, init: {
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  signal?: AbortSignal;
+}) => Promise<AsyncIterable<Uint8Array | string>>;
 interface FetchAdapterConfig {
   /** Endpoint URL, or a function of the request in case it depends on model/params */
   url: string | ((params: ChatRequest) => string);
@@ -788,17 +2025,65 @@ interface FetchAdapterConfig {
   /** Maps VernLLMs internal chat-completion request into the providers raw request body */
   mapRequest: (params: ChatRequest) => unknown;
   /**
-   * Maps the providers raw JSON response into `{ content, usage? }`
-   * `content` is the assistants text (JSON string when JSON mode was requested)
+   * Maps the providers raw JSON response into `{ content, usage?, toolCalls? }`
+   * `content` is the assistants text (JSON string when JSON mode was requested).
+   * `content` may be empty/omitted when the model responded with only tool
+   * calls and no text.
+   *
+   * `toolCalls`, when the model requested one or more tools, is the list of
+   * calls as flat `{ id, name, arguments }` entries (matching this config's
+   * own `toolCalls?: Array<{ id: string; name: string; arguments: string }>`
+   * return type below), each entry's `arguments` already JSON-*encoded* as a
+   * string (not the parsed object), mirroring the wire format every
+   * OpenAI-compatible provider uses. `fromFetch` itself converts these into
+   * `WireToolCall`'s `type`/`function`-wrapped shape before returning them
+   * from `create`. VernLLM parses (and validates, if `argumentsSchema` was
+   * set) the arguments string internally, mapResponse doesn't need to do
+   * that itself.
    */
   mapResponse: (json: unknown) => {
-    content: string;
+    content?: string;
     usage?: {
       promptTokens?: number;
       completionTokens?: number;
       totalTokens?: number;
     };
+    toolCalls?: Array<{
+      id: string;
+      name: string;
+      arguments: string;
+    }>;
   };
+  /**
+   * Optional. Required only for `stream: true` calls. The function used to
+   * open a streaming HTTP request. Takes the same request shape as
+   * `request`, but resolves to an `AsyncIterable` of progressively-arriving
+   * `Uint8Array` or `string` chunks instead of a buffered `ResponseLike`.
+   * Defaults to native `fetch`.
+   */
+  requestStream?: StreamRequestLike;
+  /**
+   * Optional. How the raw stream bytes are split into individual event
+   * payloads. Defaults to Server-Sent Events framing (`data: ...` blocks
+   * separated by a blank line, `[DONE]` sentinel honored, see
+   * `parseSseStream`), which covers the large majority of LLM providers'
+   * streaming HTTP endpoints. Override this for a provider that frames its
+   * stream differently, e.g. newline-delimited JSON (NDJSON) with no SSE
+   * envelope.
+   */
+  parseStreamFrames?: (chunks: AsyncIterable<Uint8Array | string>) => AsyncIterable<unknown>;
+  /**
+   * Optional. Required only for `stream: true` calls. Maps one parsed
+   * stream event (already extracted from its frame by `parseStreamFrames`)
+   * into zero, one, or more `WireStreamChunk`s, mirrors `mapResponse`'s
+   * role for the non-streaming path, just per-event instead of once for
+   * the whole body. Return `undefined` to skip an event that carries
+   * nothing VernLLM needs (e.g. a provider's keep-alive ping). Configs
+   * that don't implement this make `stream: true` throw a clear
+   * `LLMError('validation')` rather than a confusing runtime failure or a
+   * silently empty stream.
+   */
+  mapStreamEvent?: (event: unknown) => WireStreamChunk | WireStreamChunk[] | undefined;
 }
 /**
  * A fetch-based escape hatch for providers with no SDK, or where pulling one
@@ -810,6 +2095,34 @@ interface FetchAdapterConfig {
  * Non-2xx responses throw an error with `.status` set to the HTTP status
  * code, so VernLLMs `nonRetryableStatus` handling (e.g. failing fast on
  * 401/403) applies here too
+ *
+ * Tool calling works the same way as every other adapter: `mapRequest`
+ * receives the full `ChatRequest`, including `tools`/`toolChoice`, so it can
+ * translate them into whatever shape the provider's wire format expects
+ * (typically an OpenAI-`function`-wrapped `tools` array plus a `tool_choice`
+ * field). On the way back, `mapResponse` may return a `toolCalls` array
+ * (id/name/JSON-encoded-arguments-string per call) alongside or instead of
+ * `content`; VernLLM parses and (if `argumentsSchema` was set) validates
+ * those arguments the same way it does for every other adapter. For
+ * `stream: true`, tool-call deltas go through the existing
+ * `mapStreamEvent` seam via `WireStreamChunk`'s `tool_call_delta` variant,
+ * no separate config is needed for streaming vs non-streaming tool calls.
+ *
+
+ * `createStream` requires `mapStreamEvent` (there's no non-streaming
+ * response to fall back on, unlike the other three optional streaming
+ * seams). It opens the request via `requestStream` (defaults to native
+ * `fetch`), splits the raw bytes into individual events via
+ * `parseStreamFrames` (defaults to SSE framing, see `parseSseStream`),
+ * and translates each event into `WireStreamChunk`(s) via
+ * `mapStreamEvent`. Both seams are overridable per-config for providers
+ * that don't fit the SSE-over-fetch default. If a custom `request`
+ * transport is configured, `requestStream` must be configured too,
+ * `requestStream` never silently falls back to `request` (see
+ * `createStream`'s own comment for why), so a `stream: true` call with
+ * `request` set but no `requestStream` throws a clear
+ * `LLMError('validation')` instead of quietly using unrelated native
+ * `fetch`.
  */
 declare function fromFetch(config: FetchAdapterConfig): LLMClient;
 
@@ -834,11 +2147,46 @@ declare function fromFetch(config: FetchAdapterConfig): LLMClient;
  * (extra fields, stricter unions, etc.), so this takes `unknown` and casts:
  * the actual compatibility contract is the JSON each provider sends and
  * receives over the wire, not the SDKs TS types.
+ *
+ * `createStream` is implemented by calling the same underlying
+ * `chat.completions.create` with `stream: true` (and, for providers that
+ * support it, `stream_options: { include_usage: true }`, so a final usage
+ * block arrives), the OpenAI SDK, and every OpenAI-compatible client
+ * modeled on it, returns an `AsyncIterable` of SSE chunks instead of a
+ * single completion object when `stream: true` is set. Each chunk is
+ * translated into `WireStreamChunk`(s) via `toWireStreamChunks`.
+ *
+ * Note on long-running reasoning models: this adapter consumes the
+ * underlying SDK's already-parsed stream rather than raw SSE bytes, so
+ * unlike `fromFetch`/`fromAnthropic` it cannot see comment-only keep-alive
+ * ping frames. Combined with `chunkIdleTimeoutMs`'s 30 second default and
+ * `reasoningEffort` (documented to have long silent gaps for o-series and
+ * similar models), a long-running reasoning call on this adapter can trip
+ * the idle timeout even though the provider is still working. Raise or
+ * disable `chunkIdleTimeoutMs` per call for those routes, see `CallParams`.
  */
-declare function fromOpenAICompatible(client: unknown): LLMClient;
+interface OpenAICompatibleAdapterOptions {
+  /**
+   * Whether the provider supports `stream_options.include_usage`. Not
+   * every "OpenAI-compatible" provider is guaranteed to, so this defaults
+   * to `true` (matching OpenAI, Groq, Mistral, and most others observed)
+   * and should be set to `false` for a provider verified not to support
+   * it. When `false`, `stream_options` is omitted entirely and no usage
+   * block will arrive on the stream; callers relying on streamed `usage`
+   * with such a provider won't get one.
+   */
+  supportsStreamUsage?: boolean;
+}
+declare function fromOpenAICompatible(client: unknown, options?: OpenAICompatibleAdapterOptions): LLMClient;
 /** Groqs SDK matches the OpenAI wire format */
 declare const fromGroq: typeof fromOpenAICompatible;
-/** Mistrals `chat.completions`-shaped client (or their OpenAI-compat endpoint) */
+/**
+ * Mistrals `chat.completions`-shaped client (or their OpenAI-compat
+ * endpoint). Mistral supports `stream_options.include_usage` (added after
+ * an earlier period where it returned a 422 for unrecognized fields, per
+ * Mistral's changelog and streaming docs), so this is a plain alias like
+ * the others, `supportsStreamUsage` defaults to `true`.
+ */
 declare const fromMistral: typeof fromOpenAICompatible;
 /** DeepSeeks API is OpenAI-compatible */
 declare const fromDeepSeek: typeof fromOpenAICompatible;
@@ -929,5 +2277,5 @@ declare const from01AI: typeof fromOpenAICompatible;
 //#endregion
 //# sourceMappingURL=openaiCompatible.d.ts.map
 
-export { AnthropicClient, BedrockConverseClient, CacheAdapter, CachedCallParams, CallParams, CircuitBreaker, CircuitBreakerOptions, ConsoleLogger, ContentBlock, ConversationTurn, FetchAdapterConfig, GeminiClient, ImageBlock, InMemoryCacheAdapter, JsonSchemaSpec, LLMClient, LLMError, LLMErrorType, Logger, NormalizedCacheAdapter, OnUsage, RefundUsage, ReserveUsage, SchemaLike, TextBlock, TieredCacheAdapter, TokenUsage, VernLLM, VernLLMOptions, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGitHubModels, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromKlusterAI, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, isLLMError };
+export { AnthropicClient, BedrockConverseClient, CacheAdapter, CachedCallParams, CachedStreamCallParams, CachedStreamToolCallParams, CachedToolCallParams, CallMeta, CallParams, CallWithToolsResult, CircuitBreaker, CircuitBreakerOptions, CircuitState, ConsoleLogger, ContentBlock, ContentResult, ConversationTurn, FallbackAttempt, FallbackExhaustedError, FallbackOn, FallbackTarget, FetchAdapterConfig, GeminiClient, ImageBlock, InMemoryCacheAdapter, JsonSchemaSpec, LLMClient, LLMError, LLMErrorCode, LLMErrorType, Logger, NormalizedCacheAdapter, OnEvent, OnUsage, RateLimitAcquireResult, RateLimitOptions, RateLimitReason, RateLimiter, RefundUsage, ReserveUsage, SSE_PING, SchemaLike, StreamCallResult, StreamChunk, StreamEnabledCallParams, TargetCircuitState, TextBlock, TieredCacheAdapter, TokenUsage, ToolCall, ToolCallResult, ToolChoice, ToolDefinition, ToolEnabledCallParams, ToolIssue, ToolResult, VernLLM, VernLLMEvent, VernLLMOptions, WireMessage, WireRequest, WireStreamChunk, WireToolCall, WireToolChoice, defaultEstimateTokens, defaultFallbackOn, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGitHubModels, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromKlusterAI, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, isLLMError, isToolCallResult, parseSseStream };
 //# sourceMappingURL=index.d.cts.map