vern-llm 2.0.0 → 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
@@ -213,6 +506,20 @@ 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;
 /**
@@ -316,10 +623,18 @@ interface CallParams<T = unknown> extends UsageHooks {
    * (see `CallWithToolsResult`), a breaking-change point: omitting `tools`
    * keeps `call()`'s old `Promise<T>` behavior exactly.
    *
-   * Mutually exclusive with `jsonSchema`/`schema`: on Anthropic and
-   * Bedrock, `jsonSchema` is implemented internally as a forced single-tool
-   * call, which would collide with real tools. Setting both throws
-   * `LLMError('validation')`.
+   * 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. */
@@ -338,6 +653,18 @@ interface CallParams<T = unknown> extends UsageHooks {
    * `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;
+  };
 }
 /**
  * A `CallParams` variant where tool calling is explicitly enabled.
@@ -609,50 +936,9 @@ interface LLMClient {
   };
 }
 
-//#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;
@@ -671,11 +957,79 @@ 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 */
@@ -700,9 +1054,28 @@ interface VernLLMOptions {
    * 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). Off by default */
+  /**
+   * 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] */
@@ -731,6 +1104,41 @@ 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
@@ -745,22 +1153,25 @@ interface VernLLMOptions {
  * beyond sensible defaults.
  */
 declare class VernLLM {
-  private readonly client;
-  private readonly model;
-  private readonly maxRetries;
-  private readonly timeoutMs;
-  private readonly chunkIdleTimeoutMs;
-  private readonly baseDelayMs;
-  private readonly defaultMaxTokens;
-  private readonly defaultTemperature;
-  private readonly cache;
-  private readonly nonRetryableStatus;
-  private readonly inFlight;
-  private readonly parseJson;
-  private readonly onUsage?;
-  private readonly onUsageFailure?;
   private readonly logger;
-  private readonly breaker?;
+  /**
+   * 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.
+   */
+  private readonly executors;
+  /** Decides whether a failed target is followed by the next one or the chain stops. See `VernLLMOptions['fallbackOn']`. */
+  private readonly fallbackOn;
+  /** Reports a `'fallback'` event when the chain moves to the next target. Shared `onEvent` plumbing, same as every executor's. */
+  private readonly reportEvent;
+  /**
+   * Owns cache 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.
+   */
+  private readonly cacheOrchestrator;
   /**
    * @param options Client, model, and tunables. Defaults: `maxRetries` 1,
    * `timeoutMs` 25000, `baseDelayMs` 500, `defaultMaxTokens` 1000,
@@ -768,8 +1179,23 @@ declare class VernLLM {
    * `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
    */
   constructor(options: VernLLMOptions);
-  /** Resolves a cache key through the adapter when it supports normalization. */
-  private resolveCacheKey;
+  /** Logs a failed refundUsage attempt via the configured logger. */
+  private logRefundError;
+  /**
+   * Walks `this.executors` in order, running `attempt` against each until
+   * one succeeds or every target has failed. `run` on a lone target
+   * (no `fallback` configured) throws exactly what it throws today: the
+   * loop's single iteration path is unchanged from pre-fallback behavior.
+   *
+   * For streaming, `attempt` is `executor.runStream`, whose own retries
+   * only cover *opening* the stream (see `CallExecutor.runStream`). A
+   * mid-stream failure surfaces through `finalResult` after this function
+   * has already returned, so it's never seen here and never falls over,
+   * per the streaming limitation: splicing a second model's output into a
+   * response the consumer has already partially rendered would corrupt
+   * it.
+   */
+  private runFallbackChain;
   /**
    * 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
@@ -807,121 +1233,12 @@ declare class VernLLM {
   call<T = unknown>(params: ToolEnabledCallParams<T>): Promise<CallWithToolsResult<T>>;
   call<T = unknown>(params: CallParams<T>): Promise<T>;
   /**
-   * Performs a single attempt: builds the request (translating `tools` to
-   * wire shape when present), dispatches it with a timeout, and shapes the
-   * response into `T` or a `CallWithToolsResult<T>` when `params.tools` was
-   * set. Throws on an empty response (no text and no tool_calls) so the
-   * retry loop treats it like any other transient failure.
+   * 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 executeCall;
-  /**
-   * Shapes a fully-arrived response (content and/or tool_calls, already
-   * extracted from the provider's payload) into `T` or a
-   * `CallWithToolsResult<T>`. Reused by the streaming path once it has
-   * buffered the full text/tool-call deltas, so there's no separate
-   * parsing/validation logic for streaming.
-   *
-   * Normalizes and reports usage failure on error itself, so every caller
-   * gets identical error handling without duplicating it.
-   */
-  private finalizeResponse;
-  /**
-   * Opens a stream for a single attempt: builds the request exactly like
-   * `executeCall`, then requires `createStream` on the client (a clear
-   * `validation` error if the adapter doesn't support it). The timeout
-   * wraps stream construction and the first `.next()` together, not just
-   * construction: calling an `async function*` returns an iterator
-   * synchronously without running its body until `.next()` is first
-   * invoked, so timing only construction would time an operation that's
-   * always instant, not the actual connection. Both are folded into a
-   * single `withTimeout` so the same abort signal reaches whatever the
-   * adapter's `createStream` uses internally for its first network
-   * round-trip.
-   *
-   * Circuit-breaker success is recorded once the stream fully completes,
-   * not on the first chunk arriving, so a connection that opens but then
-   * dies mid-stream isn't masked as a success (see `buildStreamResult`).
-   */
-  private executeStreamCall;
-  /**
-   * The streaming accumulator: wraps the raw `WireStreamChunk` iterator in
-   * an async generator that yields translated `StreamChunk`s to the caller
-   * live, as they arrive, with no per-chunk timeout and no bound on total
-   * duration, and accumulates text/tool-call deltas internally so that
-   * `finalizeResponse` can produce `finalResult` once the stream completes.
-   *
-   * Two separate try/catches: the iteration loop's catch handles errors
-   * the transport itself throws, which aren't normalized yet, so that
-   * happens here along with the one `reportUsageFailure` call for them.
-   * The second catch, around `finalizeResponse`, does not re-normalize or
-   * re-report since `finalizeResponse` already does both internally.
-   * Circuit-breaker success is only recorded once the stream fully
-   * completes, not when the first chunk arrives, so a connection that
-   * opens and then dies mid-way still counts as a failure below instead
-   * of masking it.
-   */
-  private buildStreamResult;
-  /**
-   * Checks every `ToolCall` against the `tools` that were offered, catching
-   * a hallucinated tool name early instead of letting it reach the
-   * application's dispatch table. Then runs each tool's `argumentsSchema`,
-   * if present, throwing `LLMError('validation')` on failure.
-   */
-  private validateToolCallArguments;
-  /** Runs `fn`, retrying with backoff according to `shouldRetry`. */
-  private retryWithBackoff;
-  /**
-   * Validates `history` alternates user/assistant turns, since providers
-   * like Anthropic/Gemini reject or mishandle consecutive same-role turns.
-   */
-  private validateHistory;
-  /** Applies per-call defaults and shapes params into the client's request object. */
-  private buildRequestPayload;
-  /** Maps VernLLM's app-facing `ToolChoice` onto the OpenAI-shaped wire `tool_choice`. */
-  private buildWireToolChoice;
-  /**
-   * Expands one `ConversationTurn` into one or more wire messages. Plain
-   * user/assistant turns map 1:1. An assistant turn with `toolCalls` maps
-   * to an assistant message carrying wire-shaped `tool_calls`. A `'tool'`
-   * turn expands into one wire `tool` message per `toolResult`, since
-   * OpenAI-shaped wire format wants one message per tool_call_id.
-   */
-  private turnToWireMessages;
-  /**
-   * 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.
-   */
-  private buildResponseFormat;
-  /**
-   * Pulls `TokenUsage` out of a raw response, if the provider reported it.
-   * Extraction doesn't depend on what happens to the response afterward, so
-   * a malformed body can still yield usage if the provider's usage block
-   * itself came through intact.
-   */
-  private extractUsage;
-  /** Reports token usage for a successful call, swallowing and logging any error `onUsage` throws. */
-  private reportUsage;
-  /**
-   * Reports token usage spent on an attempt that then failed, so it isn't
-   * dropped alongside the error. Covers any error thrown after usage
-   * extraction, since all of them happen only after a response (real
-   * spend) already arrived. Swallows and logs any error `onUsageFailure`
-   * itself throws.
-   */
-  private reportUsageFailure;
-  /** Parses response content as JSON and validates it against `schema` when supplied. */
-  private parseAndValidate;
-  /**
-   * 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`).
-   */
-  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;
@@ -931,61 +1248,6 @@ declare class VernLLM {
    * `resolveKey`, if any, before deletion).
    */
   deleteCache(key: string): Promise<void>;
-  /**
-   * Internal cache primitive around caller-supplied logic. Concurrent misses
-   * for the same `cacheKey` share a single in-flight call, avoiding cache
-   * stampedes.
-   *
-   * Not part of the public API. Backs the public `cachedCall()`, which
-   * always composes this with `call()` so cached results get the same
-   * retry/timeout/circuit-breaker guarantees as any other LLM call.
-   *
-   * @param params `cacheKey`, `ttl`, `fn` (the work to run on a cache
-   * miss, typically `() => this.call(...)`), and optional
-   * `reserveUsage`/`refundUsage`/`signal`. See `InternalCacheParams`.
-   * @returns The cached value on a hit, or the result of `fn()` on a miss.
-   */
-  private runCached;
-  /** 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;
-  /**
-   * Streaming counterpart to `runCached`. Three cases:
-   *
-   * - Hit: no live generation to relay. Returns immediately with
-   *   `finalResult` resolved to the cached value and a one-shot `chunks`
-   *   replay built from it, so `for await (const c of chunks)` call sites
-   *   work identically on a hit or a miss. No usage hooks fire, since
-   *   nothing was actually spent.
-   * - Miss, nothing else in flight for this key: delegates to
-   *   `registerStreamTrigger`, which opens the stream and relays its
-   *   `chunks` live.
-   * - Miss, but another call for the same key is already in flight: this
-   *   call has no live chunks of its own to relay, so it's treated like a
-   *   delayed hit. `finalResult` shares the trigger's in-flight promise
-   *   (the same `this.inFlight` map non-streaming `runCached` uses, so
-   *   streaming and non-streaming `cachedCall`s for the same key coalesce
-   *   against each other too), and `chunks` is a one-shot replay built
-   *   once that promise resolves.
-   */
-  private runCachedStream;
-  /**
-   * Opens the shared stream for a cache miss and tracks its settled value
-   * in `this.inFlight` until it resolves or rejects. Writes to the cache
-   * on success only, matching `runAndCache`.
-   *
-   * Registers the in-flight promise synchronously, before anything async
-   * runs, so a concurrent `cachedCall` for the same key always sees it in
-   * time to join instead of triggering its own stream. Settlement is
-   * wired onto the whole `withReservedUsageForStream` call rather than a
-   * line inside its callback, so any failure point (reserving usage,
-   * opening the stream, or the stream itself) reliably settles the
-   * in-flight entry instead of leaving it stuck.
-   */
-  private registerStreamTrigger;
-  /** Logs a failed refundUsage attempt via the configured logger. */
-  private logRefundError;
   /**
    * Cache wrapper composing `call` + caching, so cached LLM calls
    * automatically get retry/timeout/circuit-breaker behavior. `reserveUsage`/
@@ -1019,14 +1281,30 @@ declare class VernLLM {
   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/internal/sse.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
@@ -1065,7 +1343,7 @@ declare function parseSseStream(source: AsyncIterable<Uint8Array | string>): Asy
 declare const SSE_PING: unique symbol;
 
 //#endregion
-//#region src/internal/imageFormat.d.ts
+//#region src/adapters/internal/imageFormat.d.ts
 //# sourceMappingURL=sse.d.ts.map
 /**
  * MIME types accepted for `ImageBlock.mimeType` across all adapters. This is
@@ -1077,13 +1355,38 @@ declare const SUPPORTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "
 type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
 
 //#endregion
-//#region src/adapters/anthropic.d.ts
+//#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';
@@ -1137,6 +1440,28 @@ interface AnthropicClient {
         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<{
@@ -1154,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
@@ -1294,10 +1648,10 @@ interface GeminiClient {
  * Anthropic.
  *
  * `tools` maps to Gemini's native `functionDeclarations`/`functionCall`;
- * `tool_choice` maps to `toolConfig.functionCallingConfig`. `jsonSchema`
- * and `tools` are mutually exclusive by the time a call reaches here
- * (enforced in vernLLM.ts), so `responseSchema` and `tools` never
- * both apply.
+ * `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
@@ -1394,6 +1748,34 @@ interface BedrockConverseClient {
         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: {
     signal: AbortSignal;
   }): Promise<{
@@ -1503,18 +1885,34 @@ type BedrockConverseStreamEvent = {
  */
 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`
@@ -1524,22 +1922,36 @@ 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` maps to Converse's native `toolConfig`/`toolUse`/`toolResult`;
- * `tool_choice` maps to `toolConfig.toolChoice`. Mutually exclusive with
- * `jsonSchema` by the time a call reaches here (enforced in vernLLM.ts).
+ * `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
@@ -1865,5 +2277,5 @@ declare const from01AI: typeof fromOpenAICompatible;
 //#endregion
 //# sourceMappingURL=openaiCompatible.d.ts.map
 
-export { AnthropicClient, BedrockConverseClient, CacheAdapter, CachedCallParams, CachedStreamCallParams, CachedStreamToolCallParams, CachedToolCallParams, CallParams, CallWithToolsResult, CircuitBreaker, CircuitBreakerOptions, ConsoleLogger, ContentBlock, ContentResult, ConversationTurn, FetchAdapterConfig, GeminiClient, ImageBlock, InMemoryCacheAdapter, JsonSchemaSpec, LLMClient, LLMError, LLMErrorType, Logger, NormalizedCacheAdapter, OnUsage, RefundUsage, ReserveUsage, SSE_PING, SchemaLike, StreamCallResult, StreamChunk, StreamEnabledCallParams, TextBlock, TieredCacheAdapter, TokenUsage, ToolCall, ToolCallResult, ToolChoice, ToolDefinition, ToolEnabledCallParams, ToolResult, VernLLM, VernLLMOptions, WireMessage, WireStreamChunk, WireToolCall, WireToolChoice, 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 };
+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