vern-llm 2.9.1 → 3.0.0

package/dist/client-HWxkwVvj.d.cts

@@ -0,0 +1,1871 @@
+//#region src/types/errors.d.ts
+type LLMErrorType = 'timeout' | 'api' | 'network' | 'parse' | 'validation' | 'invalid_params' | 'rate_limited' | 'quota_exceeded' | 'circuit_open' | 'fallback_exhausted' | 'aborted' | 'unknown';
+/**
+ * Machine readable detail within a `type`, for when `type` alone is too coarse to act on. Optional:
+ * errors from before a code existed omit it.
+ */
+type LLMErrorCode = 'unknown_tool' | 'duplicate_tool_call_id' | 'tool_choice_none_violated' | 'unexpected_tool_calls' | 'unsupported_capability' | 'duplicate_tool_names' | 'unknown_tool_choice' | 'duplicate_tool_result_ids' | 'unknown_tool_result_ids' | 'missing_tool_results' | 'invalid_context' | 'unknown_target' | 'no_eligible_targets' | 'middleware_threw' | 'rate_limit_queue_full' | 'rate_limit_queue_timeout' | 'rate_limit_capacity_exceeded' | 'provider_rate_limited' | 'retry_budget_exhausted' | 'request_timeout' | 'idle_timeout' | 'reader_stall_timeout' | 'middleware_timeout' | 'deadline_exceeded' | 'authentication' | 'authorization' | 'not_found' | 'payload_too_large' | 'server_error' | 'empty_response' | 'connection_failed' | 'circuit_cooling_down' | 'circuit_trial_in_flight' | 'fallback_exhausted' | 'tool_arguments_parse_failed' | 'stream_frame_invalid' | 'response_truncated' | 'soft_failure_detected';
+/** 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;
+}
+/**
+ * The specific values behind a `duplicate_tool_names` failure: the
+ * offending call's `tools` array had more than one entry sharing a name.
+ */
+interface DuplicateToolNamesIssue {
+  names: string[];
+}
+/**
+ * The specific values behind an `unknown_tool_choice` failure: `toolChoice`
+ * named a tool that wasn't in the call's own `tools` array.
+ */
+interface UnknownToolChoiceIssue {
+  requested: string;
+  available: string[];
+}
+/**
+ * The specific values behind a `duplicate_tool_result_ids` /
+ * `unknown_tool_result_ids` / `missing_tool_results` failure: which
+ * `history` turn was affected, and which `toolCallId`s were the problem.
+ */
+interface HistoryToolResultIssue {
+  historyIndex: number;
+  ids: string[];
+}
+/**
+ * The specific values behind an `unsupported_capability` failure: which
+ * capability the current adapter/client/model doesn't support.
+ */
+interface UnsupportedCapabilityIssue {
+  capability: string;
+}
+/**
+ * The exact `issues` shape for each code that carries one. Codes whose message already says
+ * everything have no entry. Schema validation `issues` stay untyped, since they come from the
+ * caller's own validator.
+ */
+interface LLMErrorIssuesByCode {
+  unknown_tool: ToolIssue[];
+  duplicate_tool_call_id: ToolIssue[];
+  duplicate_tool_names: DuplicateToolNamesIssue;
+  unknown_tool_choice: UnknownToolChoiceIssue;
+  duplicate_tool_result_ids: HistoryToolResultIssue;
+  unknown_tool_result_ids: HistoryToolResultIssue;
+  missing_tool_results: HistoryToolResultIssue;
+  unsupported_capability: UnsupportedCapabilityIssue;
+}
+/**
+ * Plain data copy of an `LLMError`, as held by `RetryAttempt.error`. Never thrown again, so no
+ * `cause` and no live getters. Nested `attempts` form a tree, not a cycle.
+ */
+interface LLMErrorSnapshot {
+  message: string;
+  type: LLMErrorType;
+  status?: number;
+  issues?: unknown;
+  retryAfterMs?: number;
+  code?: LLMErrorCode;
+  /** Computed once, at snapshot time, since a snapshot has no live getter. */
+  retryable: boolean;
+  /** This attempt's own prior attempts, if it was itself the terminal failure of a retry loop. */
+  attempts?: RetryAttempt[];
+}
+/**
+ * Plain data copy of the request an attempt sent, as held by `RetryAttempt.request`. Safe to
+ * serialize and store.
+ */
+interface LLMRequestSnapshot {
+  /** Provider id this attempt targeted, e.g. "openai". */
+  provider: string;
+  /** Model id this attempt targeted. */
+  model: string;
+  /** The payload as actually sent for this attempt, after any transform/repair. Passed through `safeBody`. */
+  body: unknown;
+  /** Non sensitive request headers. Auth headers are stripped before the snapshot is built, never included. */
+  headers?: Record<string, string>;
+  /** Wall clock time the attempt started, ms since epoch. */
+  startedAt: number;
+}
+/** One failed attempt: its index and a snapshot of its error. `FallbackAttempt` extends it. */
+interface RetryAttempt {
+  index: number;
+  error: LLMErrorSnapshot;
+  /** What was sent for this attempt. Optional: absent for attempts predating this field. */
+  request?: LLMRequestSnapshot;
+}
+/** Optional fields for constructing an {@link LLMError}. `message` and `type` stay positional since every throw site sets both. */
+interface LLMErrorOptions {
+  status?: number;
+  issues?: unknown;
+  cause?: unknown;
+  retryAfterMs?: number;
+  /** Stable discriminator within `type`. Absent on errors predating it. */
+  code?: LLMErrorCode;
+  /** Every attempt made before this error was thrown, in order. Absent when nothing was retried. */
+  attempts?: RetryAttempt[];
+}
+declare class LLMError extends Error {
+  type: LLMErrorType;
+  status?: number;
+  issues?: unknown;
+  cause?: unknown;
+  retryAfterMs?: number;
+  /** Stable discriminator within `type`. Absent on errors predating it. */
+  code?: LLMErrorCode;
+  /** Every attempt made before this error was thrown, in order. Absent when nothing was retried. */
+  attempts?: RetryAttempt[];
+  constructor(message: string, type: LLMErrorType, options?: LLMErrorOptions);
+  /**
+   * Whether retrying could help, from `type` and `code` alone. See Error Handling for the full
+   * list. `response_truncated` is retryable despite its `parse` type.
+   */
+  get retryable(): boolean;
+  /**
+   * Whether this failure counts toward the breaker. Stricter than `retryable`: `quota_exceeded` and
+   * any 4xx other than 408, 425 and 429 are excluded.
+   */
+  get countsTowardBreaker(): boolean;
+  /**
+   * Copies the fields into an `LLMErrorSnapshot`. `cause` is left out, and `issues` are made
+   * serialization safe.
+   */
+  toSnapshot(): LLMErrorSnapshot;
+  /**
+   * Serializes `message` and `retryable` too, which a plain property walk misses. `cause` is left
+   * out since SDK errors can be circular; read `err.cause` directly.
+   */
+  toJSON(): Record<string, unknown>;
+}
+declare function isLLMError(err: unknown): err is LLMError;
+/**
+ * Narrows `err.issues` to the shape `LLMErrorIssuesByCode` maps `code` to, so no cast is needed.
+ */
+declare function hasIssues<C extends keyof LLMErrorIssuesByCode>(err: LLMError, code: C): err is LLMError & {
+  code: C;
+  issues: LLMErrorIssuesByCode[C];
+};
+//#endregion
+//#region src/logger.d.ts
+interface Logger {
+  debug(message: string): void;
+  warn(message: string): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Default logger. `debug` is gated by the `debug` option on VernLLM
+ * warn/error always fire since they indicate real problems (retries, cache failures)
+ */
+declare class ConsoleLogger implements Logger {
+  private debugEnabled;
+  constructor(debugEnabled: boolean);
+  debug(message: string): void;
+  warn(message: string): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+//#endregion
+//#region src/types/usage.d.ts
+type ReserveUsage = (params: {
+  coalesced: boolean;
+  signal?: AbortSignal;
+}) => Promise<void>;
+type RefundUsage = (params: {
+  coalesced: boolean;
+  signal?: AbortSignal;
+}) => Promise<void>;
+/**
+ * The reserve/refund usage hooks shared by `CallParams`, `CachedCallParams`,
+ * and `VernLLM`'s internal `withReservedUsage`. Centralized here so the pair
+ * has one definition instead of being redeclared at each use site.
+ */
+interface UsageHooks {
+  /**
+   * Reserves usage before the request. Failures become
+   * LLMError('quota_exceeded').
+   */
+  reserveUsage?: ReserveUsage;
+  /**
+   * Refunds usage after a failed call if reservation succeeded.
+   */
+  refundUsage?: RefundUsage;
+}
+interface TokenUsage {
+  /**
+   * Every input token the provider processed: uncached input plus cache reads plus cache writes.
+   */
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  /**
+   * Reasoning tokens, a subset of `completionTokens`, not extra. `undefined` when the provider
+   * doesn't report them separately.
+   */
+  reasoningTokens?: number;
+  /** Cache reads, a subset of `promptTokens`. `undefined` when not reported. */
+  cacheReadTokens?: number;
+  /** Cache writes, a subset of `promptTokens`. `undefined` when not reported. */
+  cacheWriteTokens?: number;
+  /** `cacheWriteTokens` by the provider's TTL label. `undefined` when not split. */
+  cacheWriteTokensByTtl?: Readonly<Record<string, number>>;
+  requestId: string;
+  model: string;
+  /**
+   * The target that produced this usage, `'primary'` by default. Always set by VernLLM; optional
+   * for hand built values.
+   */
+  provider?: string;
+  /**
+   * Whether a fallback target produced this usage. Always set by VernLLM; optional for hand built
+   * values.
+   */
+  usedFallback?: boolean;
+  /** The call's `context`. */
+  context?: CallContext;
+}
+type OnUsage = (usage: TokenUsage) => void;
+/**
+ * Called when a response carried usage but post-processing failed. Once per such attempt; never for
+ * transport failures, which have no usage to report.
+ */
+type OnUsageFailure = (usage: TokenUsage, error: LLMError) => void;
+//#endregion
+//#region src/types/events.d.ts
+/**
+ * Reports what happened during a call. Fire and forget, mirroring
+ * `onUsage`: the return value is never read and a throwing handler cannot
+ * change what the call does, only what gets reported about it.
+ */
+type VernLLMEvent = {
+  kind: 'retry';
+  requestId: string;
+  provider: string;
+  /** The model actually resolved for this call (honors a per-call `model` override). */
+  model: string;
+  /** The 1-based retry ordinal (the 1st retry is `1`, not the overall attempt count). */
+  attempt: number;
+  maxRetries: number;
+  delayMs: number;
+  retryAfterHonored: boolean;
+  error: LLMError;
+  context?: CallContext;
+} | {
+  kind: 'circuit_state';
+  provider: string;
+  /**
+   * The model of the call that triggered this transition. Without `isolateByModel` the count
+   * spans every model, so the threshold may have been reached by several.
+   */
+  model: string;
+  from: CircuitState;
+  to: CircuitState;
+  consecutiveFailures: number;
+  context?: CallContext;
+} | {
+  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;
+  context?: CallContext;
+} | {
+  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';
+  context?: CallContext;
+} | {
+  kind: 'middleware';
+  requestId: string;
+  /** This middleware's `name`, or its array position if unnamed. */
+  middleware: string;
+  hook: 'transform' | 'wrap_short_circuit' | 'enabled_skip';
+  /** For `hook: 'transform'` only: which top-level fields the merged patch touched. */
+  patchedFields?: string[];
+  context?: CallContext;
+} | {
+  /**
+   * Reported once a call fully succeeds. Same data `VernLLMOptions.onUsage`
+   * receives; that option is sugar over this event, not a second
+   * reporting path, see `makeEventReporter`.
+   */
+  kind: 'usage';
+  requestId: string;
+  usage: TokenUsage;
+  context?: CallContext;
+} | {
+  /**
+   * A response carried usage and post-processing then failed. Once per such attempt;
+   * `onUsageFailure` is driven from this event.
+   */
+  kind: 'usage_failure';
+  requestId: string;
+  usage: TokenUsage;
+  error: LLMError;
+  context?: CallContext;
+} | {
+  /** Reported by a middleware through `ctx.emit`. */
+  kind: 'custom';
+  requestId: string;
+  /** Namespaced by convention, e.g. `router.decision`. */
+  name: string;
+  /** Label of the emitting middleware. */
+  source: string;
+  data?: JsonValue;
+  context?: CallContext;
+};
+type OnEvent = (event: VernLLMEvent) => void;
+//#endregion
+//#region src/types/middleware.d.ts
+/** Capabilities of the target a middleware hook is currently looking at. */
+interface MiddlewareCapabilities {
+  /**
+   * Whether this target honors `response_format: { type: 'json_object' }`
+   * as a real constraint. Mirrors `LLMClient.supportsJsonObjectMode`.
+   * `false` for `fromAnthropic` and `fromBedrock`.
+   */
+  supportsJsonObjectMode: boolean;
+}
+/**
+ * Brands `MiddlewareStateKey` so a ref, or a hand written `{ debugName }`, can't pass as a state
+ * key. Only `createStateKey` can produce one.
+ */
+declare const stateKeyBrand: unique symbol;
+/**
+ * A typed reference to one slot in `ctx.state`. Create it with `createStateKey` and import it
+ * wherever the value is shared, so a typo is a compile error instead of a new property.
+ */
+interface MiddlewareStateKey<T> {
+  readonly debugName: string;
+  readonly [stateKeyBrand]: true;
+  /**
+   * Never set. Makes keys of different `T` distinct types, so `get` and `set` infer the value type.
+   */
+  readonly __phantom?: T;
+}
+/** Creates a new, distinct `MiddlewareStateKey`. `debugName` is used only in log lines and the `'middleware'` event; it never affects equality. */
+declare function createStateKey<T>(debugName: string): MiddlewareStateKey<T>;
+/** Not exported. See `stateKeyBrand`; same reasoning, distinct symbol, so the two token types can't be cross-assigned either. */
+declare const middlewareRefBrand: unique symbol;
+/**
+ * A typed reference to a middleware, used only as a `runsAfter` or `runsBefore` target, never as a
+ * label. Create it with `createMiddlewareRef` and export it, so a typo is a compile error.
+ */
+interface MiddlewareRef {
+  readonly debugName: string;
+  readonly [middlewareRefBrand]: true;
+}
+/** Creates a new, distinct `MiddlewareRef`. `debugName` is used only in error messages when a reference doesn't resolve; it never affects equality, so two refs with the same `debugName` never collide. */
+declare function createMiddlewareRef(debugName: string): MiddlewareRef;
+/**
+ * A `runsAfter` or `runsBefore` entry, made with `requireRef`, that throws at construction when the
+ * target isn't registered. A bare ref is optional and only warns.
+ */
+interface RequiredMiddlewareRef {
+  readonly ref: MiddlewareRef;
+}
+/** Wraps `ref` so `runsAfter`/`runsBefore` throws at `VernLLM` construction time if it doesn't resolve, instead of warning and continuing. */
+declare function requireRef(ref: MiddlewareRef): RequiredMiddlewareRef;
+/**
+ * Typed per call storage that middleware share values through. VernLLM never reads or writes it.
+ */
+interface MiddlewareStateBag {
+  get<T>(key: MiddlewareStateKey<T>): T | undefined;
+  set<T>(key: MiddlewareStateKey<T>, value: T): void;
+}
+/**
+ * One `[key, value]` pair for a call's `state`. A tuple can't tie each value to its own key's type,
+ * so `stateEntry` carries that check. Raw pairs are not type checked.
+ */
+type MiddlewareStateEntry = readonly [MiddlewareStateKey<unknown>, unknown];
+/** Builds a type checked `state` entry: `value` must match the key's type. */
+declare function stateEntry<T>(key: MiddlewareStateKey<T>, value: T): MiddlewareStateEntry;
+/** A plain, `Map`-backed `MiddlewareStateBag`, optionally seeded with `entries`. Later entries win. */
+declare function createMiddlewareStateBag(entries?: readonly MiddlewareStateEntry[]): MiddlewareStateBag;
+/** Fields every `MiddlewareContext` variant carries, regardless of `stage`. */
+interface MiddlewareContextBase {
+  requestId: string;
+  /** Capabilities of the target this stage's identity fields describe. */
+  capabilities: MiddlewareCapabilities;
+  signal?: AbortSignal;
+  /** Shared, collision-proof state for two middleware to deliberately coordinate through. See `MiddlewareStateBag`. */
+  state: MiddlewareStateBag;
+  /** Simple, string-keyed scratch space, pre-namespaced to this one middleware so two middleware can never collide here even by accident. */
+  own: Record<string, unknown>;
+  /**
+   * Every registered middleware's label, in `transform` order, e.g. to skip work another known
+   * middleware already does.
+   */
+  registeredMiddlewareNames: readonly string[];
+  /**
+   * The labels from `registeredMiddlewareNames` whose entry defines a
+   * `transform`, in the same order, frozen. Lets a middleware tell
+   * whether any entry after it can still change the request.
+   */
+  transformMiddlewareNames: readonly string[];
+  /** Reports a `custom` event to `onEvent` and every middleware. Never throws. */
+  emit(name: string, data?: JsonValue): void;
+  /** The call's `context`, frozen. `undefined` when none was given. */
+  context: CallContext | undefined;
+}
+/**
+ * The `ctx` for `transform` and every attempt scoped event. Built once a target is selected, so
+ * every field describes the real target.
+ */
+interface AttemptContext extends MiddlewareContextBase {
+  stage: 'attempt';
+  /** The target this attempt is actually dispatched to. */
+  requestedProvider: string;
+  /** The adapter behind this target. `{ name: 'custom' }` when its client doesn't identify one. */
+  adapter: AdapterInfo;
+  requestedModel: string;
+  isFallbackAttempt: boolean;
+  /**
+   * The current attempt number. A `'circuit_state'` event from the check before any attempt reports
+   * 1.
+   */
+  attempt: number;
+}
+/**
+ * The `ctx` for `wrap` and `onError`. Built before any target is chosen, so it only describes the
+ * primary. Read `next()`'s `CallResult.meta` for what happened.
+ */
+interface PreDispatchContext extends MiddlewareContextBase {
+  stage: 'pre-dispatch';
+  /** The primary target only, not necessarily who ends up answering. */
+  primaryProvider: string;
+  /** The adapter behind the primary target. `{ name: 'custom' }` when its client doesn't identify one. */
+  primaryAdapter: AdapterInfo;
+  primaryModel: string;
+  /** The order so far: what this `wrap` may try, after every outer `wrap` narrowed it. */
+  targets: readonly TargetInfo[];
+}
+/**
+ * What `enabled` and `onEvent` receive, since they run in both stages. Narrow on `ctx.stage` before
+ * reading stage specific fields.
+ */
+type MiddlewareContext = AttemptContext | PreDispatchContext;
+/** The `response_format` shape `RequestBuilder` can put on the wire. */
+type WireResponseFormat = {
+  type: 'json_object';
+} | {
+  type: 'json_schema';
+  json_schema: {
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+    description?: string;
+  };
+};
+/** A tool as it appears on the wire, OpenAI's `function`-wrapped shape. */
+interface WireTool {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+/**
+ * The wire-shaped request `RequestBuilder.build()` produces for one call
+ * attempt, before dispatch. Read only inside `transform`; return a patch
+ * of the fields you want to change instead of the whole object.
+ */
+interface WireCallRequest {
+  model: string;
+  temperature?: number;
+  max_tokens: number;
+  response_format?: WireResponseFormat;
+  reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+  budget_tokens?: number;
+  tools?: WireTool[];
+  tool_choice?: WireToolChoice;
+  messages: WireMessage[];
+}
+/**
+ * A patch `transform` returns, merged onto the built request. `model` and `response_format` can't
+ * be patched, since targets are attributed by the values already resolved. `add*` fields append, so
+ * two middleware can add without overwriting each other.
+ */
+interface WireCallRequestPatch {
+  temperature?: number;
+  max_tokens?: number;
+  reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+  budget_tokens?: number;
+  tool_choice?: WireToolChoice;
+  /** Replaces the whole message list. Prefer `addMessages` unless a full replace is genuinely the intent. */
+  messages?: WireMessage[];
+  /** Appended after whatever earlier middleware already added. Never clobbers a prior addition. */
+  addMessages?: WireMessage[];
+  /** Replaces the whole tool list. Prefer `addTools`, same reasoning as `messages`/`addMessages`. */
+  tools?: WireTool[];
+  /** Appended after whatever earlier middleware already added. Never clobbers a prior addition. */
+  addTools?: WireTool[];
+}
+/**
+ * The settled outcome of one logical call, from `wrap`'s `next()`. `meta` is `undefined` only on a
+ * cache hit.
+ */
+interface CallResult<T = unknown> {
+  value: T;
+  meta?: CallMeta;
+}
+/**
+ * One entry in `VernLLMOptions.middleware`. Every hook is optional. See the middleware docs for how
+ * hooks compose.
+ */
+interface VernLLMMiddleware {
+  /** Used in log lines and the `'middleware'` event. Defaults to this entry's array position when omitted. */
+  name?: string;
+  /**
+   * This entry's identity for other entries' `runsAfter` and `runsBefore`. Unrelated to `name`,
+   * which is only a label.
+   */
+  ref?: MiddlewareRef;
+  /** Sort key for composition order, ascending, ties broken by array order. See the middleware docs for what "lower runs first" means for `wrap`. */
+  priority?: number;
+  /**
+   * Middleware this entry runs after. An unresolved bare ref is dropped; wrap it with `requireRef`
+   * to throw at construction instead. A cycle always throws.
+   */
+  runsAfter?: (MiddlewareRef | RequiredMiddlewareRef)[];
+  /**
+   * Other middleware this entry must run before. See `runsAfter`; a
+   * bare reference is dropped if unresolved, a `requireRef`-wrapped one
+   * throws.
+   */
+  runsBefore?: (MiddlewareRef | RequiredMiddlewareRef)[];
+  /**
+   * Pins this entry in `wrap` nesting only. `'outermost'` sees the net result of every retry and
+   * fallback; `'innermost'` sits next to dispatch. A number works like `priority` for `wrap` only.
+   */
+  position?: 'outermost' | 'innermost' | number;
+  /**
+   * Boolean for a static on/off switch, or a predicate evaluated per
+   * call. A throwing, rejecting, or timed-out predicate is logged and
+   * treated as `false` for that call.
+   */
+  enabled?: boolean | ((ctx: MiddlewareContext) => boolean | Promise<boolean>);
+  /** Per-middleware override of the instance-level `middlewareTimeoutMs`, applied to this entry's `transform` and function `enabled`. `<= 0` means unbounded (no timer at all). */
+  timeoutMs?: number;
+  /** Transforms the outgoing wire request for one attempt. Runs once per attempt, including retries. `ctx` is always accurate to the real target for this attempt. */
+  transform?: (request: Readonly<WireCallRequest>, ctx: AttemptContext) => WireCallRequestPatch | Promise<WireCallRequestPatch>;
+  /**
+   * Wraps one whole logical call once, however many retries or targets ran. `ctx` describes the
+   * primary and the order so far (`ctx.targets`); read `next()`'s `CallResult.meta` for what
+   * happened. `next({ targets })` reorders or drops targets by name, never adds one.
+   */
+  wrap?: (request: Readonly<WireCallRequest>, next: (options?: {
+    targets?: readonly string[];
+  }) => Promise<CallResult>, ctx: PreDispatchContext) => Promise<CallResult>;
+  /**
+   * Wraps one attempt's provider request, after the limiter and every `transform`. `request` is
+   * exactly what the adapter gets. Runs per attempt, nested in `wrap` order.
+   *
+   * `next()` resolves when the response arrives, or at a stream's first content chunk; pings don't
+   * count. It rejects with the attempt's `LLMError`. A hook can observe but not change the outcome:
+   * returning or throwing without calling `next()` fails the attempt with code `middleware_threw`,
+   * and a throw after it is only logged.
+   */
+  dispatch?: (request: Readonly<WireCallRequest>, next: () => Promise<void>, ctx: AttemptContext) => Promise<void>;
+  /** Observes the same events reported on `VernLLMOptions.onEvent`, filtered by this middleware's own `enabled`. Called from both stages; narrow on `ctx.stage` before reading stage-specific fields. */
+  onEvent?: (event: VernLLMEvent, ctx: MiddlewareContext) => void;
+}
+//#endregion
+//#region src/circuitBreaker.d.ts
+/** The call this mutation happened as part of, forwarded to `onStateChange` untouched. */
+interface CircuitBreakerCallContext {
+  requestId: string;
+  state: MiddlewareStateBag;
+  signal?: AbortSignal;
+  /** Omitted for calls before any attempt exists, like `assertClosed`'s pre-dispatch check. */
+  attempt?: number;
+}
+/**
+ * Fires after every real state change. `model` is the triggering call's resolved model. Shared by
+ * the options and the adapter interface, so custom adapters report changes the same way.
+ */
+type CircuitBreakerStateChangeHandler = (from: CircuitState, to: CircuitState, consecutiveFailures: number, model?: string, context?: CircuitBreakerCallContext) => void;
+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;
+  onStateChange?: CircuitBreakerStateChangeHandler;
+  /**
+   * Track a separate circuit per resolved model instead of one shared
+   * circuit. Default false. A call that omits `model` falls into one
+   * shared bucket alongside every other call that also omits it.
+   */
+  isolateByModel?: boolean;
+  /** Trial calls allowed through per half-open cycle. Default 1, clamped to at least 1. */
+  halfOpenProbes?: number;
+  /** Fraction of `halfOpenProbes` that must succeed to close the circuit. Default 1, clamped to `[0, 1]`. */
+  halfOpenSuccessRatio?: number;
+  /**
+   * Grows `cooldownMs` on each repeat open instead of a fixed wait.
+   * `{ multiplier, maxMs }` covers exponential growth; a `CooldownBackoff`
+   * function covers anything else. Omitted means `cooldownMs` stays fixed.
+   */
+  cooldownBackoff?: ExponentialBackoffOptions | CooldownBackoff;
+  /**
+   * When failures open the circuit. `{ kind: 'consecutive', threshold }` (default) opens after that
+   * many in a row; `{ kind: 'rolling', windowMs, minCalls, failureRatio }` opens once `minCalls`
+   * calls in the window reach `failureRatio`. Invalid values throw `RangeError` at construction. A
+   * custom `TrippingPolicy` is shared across models, keyed per model.
+   */
+  tripping?: TrippingOption;
+}
+/** Computes the cooldown for a bucket's `reopenCount`-th repeat open. */
+type CooldownBackoff = (reopenCount: number, baseCooldownMs: number) => number;
+interface ExponentialBackoffOptions {
+  /** Growth factor applied per repeat open, e.g. 2 doubles each time. */
+  multiplier: number;
+  /** Upper bound on the computed cooldown, in ms. Default `Infinity`. */
+  maxMs?: number;
+}
+/**
+ * Decides when failures open the circuit. Keyed by model (or one shared key), so one instance
+ * serves every bucket.
+ */
+interface TrippingPolicy {
+  onSuccess(key: string): void;
+  /** Returns true if this failure should open the circuit for `key`. */
+  onFailure(key: string): boolean;
+  reset(key: string): void;
+  /**
+   * Called when `key`'s circuit is reset closed, so a keyed policy can drop that key's state. Not
+   * called on an ordinary success, whose state a rolling window still needs.
+   */
+  forget?(key: string): void;
+}
+declare class ConsecutiveTripping implements TrippingPolicy {
+  private readonly threshold;
+  private failuresByKey;
+  constructor(threshold: number);
+  onSuccess(key: string): void;
+  onFailure(key: string): boolean;
+  reset(key: string): void;
+  forget(key: string): void;
+}
+declare class RollingTripping implements TrippingPolicy {
+  private readonly windowMs;
+  private readonly minCalls;
+  private readonly failureRatio;
+  private ratiosByKey;
+  constructor(windowMs: number, minCalls: number, failureRatio: number);
+  private ratioFor;
+  onSuccess(key: string): void;
+  onFailure(key: string): boolean;
+  reset(key: string): void;
+  forget(key: string): void;
+}
+/** Not exported. Internal shorthand union for `CircuitBreakerOptions.tripping`. */
+type TrippingOption = {
+  kind: 'consecutive';
+  threshold: number;
+} | {
+  kind: 'rolling';
+  windowMs: number;
+  minCalls: number;
+  failureRatio: number;
+} | TrippingPolicy;
+type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * What VernLLM needs from a breaker. Pass your own for cross-process coordination. `onStateChange`
+ * is required so `circuit_state` events can't go missing; `() => {}` is fine. Omitting an optional
+ * member makes that call a no-op, as with no breaker. `open` and `close` are optional, since a
+ * distributed adapter may not allow forced transitions.
+ */
+interface CircuitBreakerAdapter {
+  /** Throws when the circuit is open (or half open with no trial slot free) for `model`. */
+  assertClosed(model?: string, context?: CircuitBreakerCallContext): void;
+  recordSuccess(model?: string, context?: CircuitBreakerCallContext): void;
+  /** `code`, when present, is the failing call's `LLMErrorCode`. */
+  recordFailure(model?: string, context?: CircuitBreakerCallContext, code?: LLMErrorCode): void;
+  getState?(model?: string): CircuitState;
+  /** Failure counts by `LLMErrorCode` for `model`'s bucket, `'unknown'` for one that carried no code. */
+  getFailureBreakdown?(model?: string): Partial<Record<LLMErrorCode | 'unknown', number>>;
+  /** Whether this adapter tracks failures per model, mirroring `CircuitBreakerOptions.isolateByModel`. Read by `warnIfModelUnsupported`'s diagnostic warning and by `VernLLM.getCircuitStates()`'s public output; omit if the notion doesn't apply to your adapter, `false` is assumed. */
+  isolateByModel?: boolean;
+  /** Manually opens the circuit, as if enough consecutive failures had just happened. Optional: an adapter that doesn't want external callers forcing a transition can omit it. */
+  open?(model?: string, context?: CircuitBreakerCallContext): void;
+  /** Manually closes the circuit, without requiring a real success first. Same opt-in reasoning as `open`. */
+  close?(model?: string, context?: CircuitBreakerCallContext): void;
+  /** Gives back a half-open trial slot when a call ends without `recordSuccess` or `recordFailure`. Idempotent, and a no-op for a call that holds no slot. */
+  releaseTrial?(model?: string, context?: CircuitBreakerCallContext): void;
+  /** Awaited right before `assertClosed` to refresh local state. Never blocks or fails a call: a rejection or `prepareTimeoutMs` is logged and the call carries on. */
+  prepare?(model?: string, context?: CircuitBreakerCallContext): Promise<void>;
+  /** How long to wait for `prepare`, in ms. Default 1000. */
+  prepareTimeoutMs?: number;
+  /** Live counterpart of `getState`, read by `VernLLM.readCircuitStates()`. */
+  readState?(model?: string): Promise<CircuitState>;
+  /** Receives the instance's `Logger` once, when `VernLLM` wires this adapter in. */
+  setLogger?(logger: Logger): void;
+  /**
+   * Called after every real state change, after VernLLM reports its `circuit_state` event. A throw
+   * here is caught and logged.
+   */
+  onStateChange: CircuitBreakerStateChangeHandler;
+}
+/**
+ * Per retry VernLLM-instance circuit breaker. Tracks consecutive failures
+ * across calls. Once the threshold is hit, short-circuits new calls with
+ * LLMError('circuit_open') until the cooldown elapses and a trial succeeds.
+ */
+declare class CircuitBreaker implements CircuitBreakerAdapter {
+  private readonly cooldownMs;
+  /** Satisfies `CircuitBreakerAdapter.onStateChange`, required there. Defaults to a no-op when `options.onStateChange` is omitted. */
+  readonly onStateChange: CircuitBreakerStateChangeHandler;
+  /** Whether this breaker tracks failures per model instead of one shared circuit. */
+  readonly isolateByModel: boolean;
+  private readonly halfOpenProbes;
+  private readonly halfOpenSuccessRatio;
+  private readonly cooldownBackoff?;
+  /** One instance, keyed per model internally. See `TrippingPolicy`. */
+  private readonly tripping;
+  private readonly sharedBucket;
+  private readonly bucketsByModel;
+  /**
+   * Breaker-wide rather than per bucket, since an evicted bucket is
+   * recreated with no history and a per bucket generation would restart.
+   */
+  private generation;
+  /** Each call's generation at admission, keyed by its `state`, so its outcome can be told apart from a later generation's. */
+  private readonly admittedInGeneration;
+  constructor(options?: CircuitBreakerOptions);
+  /**
+   * Throws if the circuit is open and the cooldown hasn't elapsed, or if
+   * half-open with every trial slot claimed. Otherwise claims a trial slot.
+   */
+  assertClosed(model?: string, context?: CircuitBreakerCallContext): void;
+  recordSuccess(model?: string, context?: CircuitBreakerCallContext): void;
+  /** `code`, when present, is the failing `LLMError`'s `code`. Missing attributes to `'unknown'`. */
+  recordFailure(model?: string, context?: CircuitBreakerCallContext, code?: LLMErrorCode): void;
+  /**
+   * Gives back the trial slot `context`'s call claimed when it ended without an outcome. Safe to
+   * call on any failure path: a no-op without a live permit.
+   */
+  releaseTrial(model?: string, context?: CircuitBreakerCallContext): void;
+  /**
+   * The current state. Ignores `model` unless isolated by model. An open circuit past its cooldown
+   * reports `'half-open'`, though the real transition waits for the next call.
+   */
+  getState(model?: string): CircuitState;
+  /** Failure counts by `LLMErrorCode` for `model`'s bucket. Returned as a plain object copy. */
+  getFailureBreakdown(model?: string): Partial<Record<LLMErrorCode | 'unknown', number>>;
+  /** Manually opens the circuit, as if `threshold` consecutive failures had just happened. */
+  open(model?: string, context?: CircuitBreakerCallContext): void;
+  /** Manually closes the circuit and resets its failure count, without requiring a real success first. */
+  close(model?: string, context?: CircuitBreakerCallContext): void;
+  /**
+   * Stamps the open time and cooldown, then transitions to open. Callers have already cleared
+   * `trial`.
+   */
+  private openBucket;
+  /** Computes and clamps the cooldown for `bucket`'s current `reopenCount`. Called once, on open. */
+  private computeCooldown;
+  private markAdmitted;
+  /**
+   * True if this call was admitted before `bucket` last opened, so its outcome belongs to an ended
+   * generation. A call without context always counts.
+   */
+  private isFromEarlierGeneration;
+  /** Returns the bucket for a model if one already exists, without allocating. */
+  private lookupBucket;
+  /**
+   * The key for `tripping`: per model when isolated by model, otherwise one shared key, matching
+   * which bucket a call lands in.
+   */
+  private trippingKeyFor;
+  /** Creates and stores a bucket for a model when the first mutation needs one. */
+  private ensureBucketFor;
+  /** Drops an idle model's bucket, keeping its tripping state. */
+  private dropBucket;
+  /** Drops a reset model's bucket and lets `tripping` release that key's state too. */
+  private forgetModel;
+  /** Every state mutation routes through here, so `onStateChange` fires exactly once per real change. */
+  private transition;
+  /** Once every admitted trial has reported in, closes or reopens based on `halfOpenSuccessRatio`. */
+  private settleTrialIfComplete;
+}
+//#endregion
+//#region src/internal/retryBudget.d.ts
+/**
+ * `windowMs` and `minCalls` work as in `RollingTripping`: `minCalls` keeps a cold start from
+ * tripping. `retryRatio` is the largest share of calls in the window that may be retries. Invalid
+ * values throw `RangeError` at construction.
+ */
+interface RetryBudgetOptions {
+  windowMs: number;
+  minCalls: number;
+  retryRatio: number;
+}
+/**
+ * Caps the share of a target's recent traffic that may be retries. The breaker asks whether the
+ * provider is healthy; this asks whether retrying is still worth the capacity it costs.
+ */
+declare class RetryBudget {
+  private readonly options;
+  private readonly ratio;
+  constructor(options: RetryBudgetOptions);
+  /**
+   * Throws `LLMError('retry_budget_exhausted')` once at least `minCalls`
+   * calls have landed in the trailing `windowMs` and the retry ratio
+   * among them has reached `retryRatio`. A no-op otherwise.
+   */
+  assertAvailable(): void;
+  /** Records one attempt. `isRetry` is false for a call's first attempt, true for every attempt after it. */
+  recordAttempt(isRetry: boolean): void;
+  /** Current traffic and retry ratio in the trailing window. */
+  getSnapshot(): {
+    attempts: number;
+    retryRatio: number;
+  };
+}
+//#endregion
+//#region src/internal/utils/circuit-breaker/circuitBreakerAdapter.utils.d.ts
+/** The `circuitBreaker` option union, shared by `VernLLMOptions` and `buildCircuitBreaker`. */
+type CircuitBreakerOption = boolean | CircuitBreakerOptions | CircuitBreakerAdapter;
+//#endregion
+//#region src/internal/utils/rate-limit/rateLimitHint.utils.d.ts
+/** A normalized read of a provider's rate limit headers. */
+interface ProviderRateLimitHint {
+  remainingRequests?: number;
+  limitRequests?: number;
+  resetAfterMs?: number;
+}
+//#endregion
+//#region src/rateLimit.d.ts
+/** 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 or pass 0 for unlimited. Otherwise a finite number of at least 1. */
+  requestsPerMinute?: number;
+  /**
+   * Max tokens per minute. Enforced against a pre-flight estimate, then
+   * reconciled against reported usage once the call completes. Omit or
+   * pass 0 for unlimited. Otherwise a finite number of at least 1.
+   */
+  tokensPerMinute?: number;
+  /** Max requests in flight at once, as a non-negative integer. 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. At most 2147483647, the longest timer delay.
+   */
+  maxQueueMs?: number;
+  /** Max queued calls before new ones reject immediately instead of queueing, as a non-negative integer. Default 0, unbounded. */
+  maxQueueSize?: number;
+  /**
+   * Pre-flight token estimate for `tokensPerMinute`. Defaults to a
+   * chars/4 heuristic over message text, a flat amount per image, plus
+   * `max_tokens`.
+   */
+  estimateTokens?: (request: WireRequest) => number;
+  /**
+   * Scales the token estimate reserved against `tokensPerMinute`, since most calls use less than
+   * `max_tokens`. Limiter bookkeeping only; `release` reconciles against real usage. Default 1,
+   * must be above 0, clamped to 1.
+   */
+  estimateFraction?: number;
+  /**
+   * AIMD against the `requestsPerMinute` bucket. Omit for a fixed
+   * ceiling, today's behavior. Requires `requestsPerMinute`; throws
+   * without it.
+   */
+  aimd?: AimdOptions;
+}
+interface AimdOptions {
+  /** Added to the requests-per-minute ceiling on every clean release. */
+  increaseBy: number;
+  /** Multiplied against the ceiling on a rate-limit signal. Must be greater than `0` and at most `1`; clamped otherwise. */
+  decreaseFactor: number;
+  /** Floor the ceiling never shrinks below. */
+  minCapacity: number;
+  /** Ceiling the bucket never grows above. */
+  maxCapacity: number;
+  /**
+   * Shrink proactively once a provider hint reports `remainingRequests`
+   * at or below this, before a real 429 happens. Default 0, meaning
+   * off.
+   */
+  proactiveFloor?: number;
+}
+interface RateLimitState {
+  /** Requests still available this window, or `undefined` if `requestsPerMinute` isn't configured. */
+  requestsRemaining?: number;
+  /** Tokens still available this window, or `undefined` if `tokensPerMinute` isn't configured. */
+  tokensRemaining?: number;
+  /** Concurrency slots currently in use, or `undefined` if `maxConcurrent` isn't configured. */
+  concurrentInFlight?: number;
+}
+interface RateLimitAcquireResult {
+  /**
+   * Frees the concurrency slot and reconciles tokens when `actualTokens` is given. Only the first
+   * call counts. Call it in a `finally` so a failed attempt never leaks a slot.
+   */
+  release: (actualTokens?: number, success?: boolean) => void;
+  /** How long this attempt waited in queue before capacity was available. */
+  waitedMs: number;
+  /** Which bucket was blocking this attempt just before it cleared, if any wait happened. */
+  reason?: RateLimitReason;
+}
+/**
+ * What VernLLM needs from a limiter. Pass your own for cross-process coordination. Every method is
+ * required; no-op the AIMD ones when unused, as `RateLimiter` does.
+ */
+interface RateLimiterAdapter {
+  estimate(request: WireRequest): number;
+  acquire(estimatedTokens: number, signal?: AbortSignal): Promise<RateLimitAcquireResult>;
+  signalRateLimit(): void;
+  reactToRateLimitHint(hint: ProviderRateLimitHint | undefined): void;
+  /** Optional: current bucket levels, for introspection. Omit if the adapter has no state worth reporting. */
+  getState?(): RateLimitState;
+  /** Optional: live bucket levels for `VernLLM.readRateLimitState()`, the async counterpart of `getState`. */
+  readState?(): Promise<RateLimitState>;
+  /** Optional: receives the instance's `Logger` once, when `VernLLM` wires this adapter in. */
+  setLogger?(logger: Logger): void;
+}
+/**
+ * Per target limiter: up to three buckets (requests, tokens, concurrency) behind one FIFO queue, so
+ * a large call isn't starved by small ones. An omitted bucket never blocks.
+ */
+declare class RateLimiter implements RateLimiterAdapter {
+  private readonly requests?;
+  private readonly tokens?;
+  private readonly concurrency?;
+  /** Buckets in acquire precedence order (concurrency, rpm, tpm), omitted ones filtered out. Built once so order can't drift between `tryAcquireBuckets` and `scheduleWake`. */
+  private readonly buckets;
+  private readonly maxQueueMs;
+  private readonly maxQueueSize;
+  private readonly estimateTokensFn;
+  private readonly estimateFraction;
+  private readonly aimd?;
+  private readonly queue;
+  /**
+   * A scheduled recheck of the queue head when it waits on a bucket that refills by time, so the
+   * queue doesn't wait for an unrelated acquire or release. A concurrency block only clears on
+   * release.
+   */
+  private wakeTimer?;
+  /** When AIMD last shrank the ceiling, see `AIMD_SHRINK_WINDOW_MS`. */
+  private lastShrinkAt?;
+  constructor(options: RateLimitOptions);
+  /**
+   * The token estimate reserved against `tokensPerMinute`, scaled by `estimateFraction`. The
+   * request's `max_tokens` is never changed.
+   */
+  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;
+  /** Takes from every configured bucket as one atomic unit, in `this.buckets`' order. Rolls back whatever was already taken if any bucket lacks capacity. */
+  private tryAcquireBuckets;
+  /** Drains the queue head first. Stops at the first waiter that still can't proceed, so no one is starved out of turn. */
+  private drain;
+  /**
+   * Schedules one recheck for when the bucket blocking the head should have capacity. No-op for a
+   * concurrency block or while a wake is pending.
+   */
+  private scheduleWake;
+  /**
+   * The one-shot release for an acquired slot. Concurrency is given back, requests only recover by
+   * refill, and tokens are reconciled against real usage. AIMD grows only when `success` is true,
+   * so a failed attempt can't undo a shrink.
+   */
+  private makeRelease;
+  /** Shared guard and resize call behind both AIMD halves below; only the arithmetic differs. */
+  private resizeRequestsCeiling;
+  /** AIMD's additive-increase half: grows the ceiling by `aimd.increaseBy` on a clean release. No-op without `aimd`/`requestsPerMinute`. */
+  private growOnSuccess;
+  /**
+   * AIMD's decrease, on a real 429 or a low remaining hint. Only adjusts the ceiling, never throws.
+   * Shrinks at most once per `AIMD_SHRINK_WINDOW_MS`.
+   */
+  signalRateLimit(): void;
+  /**
+   * AIMD's proactive entry point: shrinks via `signalRateLimit()` if
+   * `hint.remainingRequests` is at or below `aimd.proactiveFloor`.
+   */
+  reactToRateLimitHint(hint: ProviderRateLimitHint | undefined): void;
+  /**
+   * Current bucket levels, read live rather than cached. `concurrency`
+   * tracks free slots internally, so `concurrentInFlight` is reported as
+   * `capacity - available`, the inverse of what the bucket itself holds.
+   */
+  getState(): RateLimitState;
+}
+//#endregion
+//#region src/internal/utils/rate-limit/rateLimitAdapter.utils.d.ts
+/** Not exported. Internal shorthand only, so this union isn't duplicated between the public option fields and `buildRateLimit`'s own signature. */
+type RateLimitOption = RateLimitOptions | RateLimiterAdapter;
+//#endregion
+//#region src/types/fallback.d.ts
+/**
+ * A provider tried after the primary fails, in the order given. Omitted overrides fall back to the
+ * instance's options, except `circuitBreaker`, `rateLimit` and `retryBudget`, which are never
+ * inherited since limits tuned for the primary rarely fit a fallback.
+ */
+interface FallbackTarget {
+  client: LLMClient;
+  model: string;
+  /** Label for events, errors, and `TokenUsage.provider`. Default `` `fallback[${index}]` ``. */
+  name?: string;
+  maxRetries?: number;
+  timeoutMs?: number;
+  chunkIdleTimeoutMs?: number;
+  readerStallTimeoutMs?: number;
+  baseDelayMs?: number;
+  maxRetryAfterMs?: number;
+  defaultMaxTokens?: number;
+  defaultTemperature?: number | null;
+  defaultReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+  defaultBudgetTokens?: number;
+  nonRetryableStatus?: number[];
+  /** This target's own breaker, or a shared `CircuitBreakerAdapter`. Not inherited from the parent's `circuitBreaker`. */
+  circuitBreaker?: CircuitBreakerOption;
+  /** This target's own rate limiter, independent of every other target's. Not inherited from the parent's `rateLimit`. */
+  rateLimit?: RateLimitOption;
+  /** This target's own retry budget, independent of every other target's. Not inherited from the parent's `retryBudget`. */
+  retryBudget?: RetryBudgetOptions;
+  /**
+   * Reclassifies a successful result from this target as a failure. Inherits the instance's
+   * `detectSoftFailure` when omitted.
+   */
+  detectSoftFailure?: DetectSoftFailure;
+}
+/**
+ * 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;
+  /** Position of the answering target in the order tried, 0 based. */
+  position: number;
+}
+/** One configured target, as a middleware sees it in `ctx.targets`. */
+interface TargetInfo {
+  /** The name `targets` selects by. */
+  name: string;
+  /** Declared position: 0 is the primary. */
+  index: number;
+  model: string;
+  adapter: AdapterInfo;
+}
+/** 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;
+  /** Whether this target tracks failures per model. `false` means `model` on `getCircuitStates` had no effect on this entry. */
+  isolateByModel: boolean;
+  /** `undefined` if that target has no circuit breaker configured. */
+  state: CircuitState | undefined;
+}
+/** Which target/model `VernLLM.getCircuitState`, `openCircuit`, and `closeCircuit` act on. */
+interface CircuitTarget {
+  /** Which target to act on. `0` is the primary, `1`+ are fallbacks. Defaults to `0`. */
+  index?: number;
+  /** Which model bucket to act on, if the resolved target isolates by model. */
+  model?: string;
+}
+/**
+ * One target's failure. `index` is `-1` for the primary; `provider` and `model` name the target.
+ */
+interface FallbackAttempt extends RetryAttempt {
+  provider: string;
+  model: string;
+}
+/** What `fallbackOn` is told about the failed target and what would come after it. */
+interface FallbackOnContext {
+  /** Whether no target is left in the order tried. The chain stops after the last one whatever `fallbackOn` returns. */
+  isLastTarget: boolean;
+  /** The target that just failed. `model` is what it ran, so the per call `model` shows on the primary only. */
+  failed: TargetInfo;
+  /** The target that would be tried next. `undefined` on the last target. */
+  next?: TargetInfo;
+}
+/**
+ * Whether to try the next target (`'next'`) or give up (`'stop'`) after a target's own retries.
+ * Called once per failed target.
+ */
+type FallbackOn = (error: LLMError, context: FallbackOnContext) => '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: (error: LLMError, context: Pick<FallbackOnContext, 'isLastTarget'>) => 'next' | 'stop';
+/**
+ * Thrown when the chain gives up, carrying every attempt in order. Extends `LLMError` and takes the
+ * last failure's `type`, `status` and `retryAfterMs`, so existing handling keeps working.
+ */
+declare class FallbackExhaustedError extends LLMError {
+  readonly attempts: FallbackAttempt[];
+  constructor(attempts: FallbackAttempt[]);
+  /**
+   * Defers to the last attempt's `retryable`, since `fallback_exhausted` alone says nothing about
+   * it.
+   */
+  get retryable(): boolean;
+}
+/** Narrows `err` to {@link FallbackExhaustedError}, for direct access to its `attempts` (`provider`/`model` per failed target) without a manual `instanceof` check. */
+declare function isFallbackExhaustedError(err: unknown): err is FallbackExhaustedError;
+/**
+ * An empty holder for `CallParams['meta']`, so `call()`'s `CallMeta` can be read without declaring
+ * one by hand.
+ *
+ * @example
+ * const meta = metaRef();
+ * const result = await vern.call({ userContent: '...', meta });
+ * meta.current?.provider;
+ */
+declare function metaRef(): {
+  current?: CallMeta;
+};
+//#endregion
+//#region src/types/schema.d.ts
+/**
+ * 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
+ * `safeParse` (Zod v3/v4, and most Zod-compatible validators) should satisfy this
+ */
+interface SchemaLike<T> {
+  safeParse(data: unknown): {
+    success: true;
+    data: T;
+  } | {
+    success: false;
+    error: unknown;
+  };
+}
+/**
+ * A provider-native JSON Schema for structured outputs (OpenAI/Groq
+ * `response_format: { type: 'json_schema' }`) This is the wire-format
+ * schema the model is constrained to generate against, distinct from
+ * `schema`, which is a client-side Zod validator run on the parsed result
+ * You can use one, both, or neither; using both gets you provider-level
+ * constraint plus client-side type inference/validation as a safety net
+ */
+interface JsonSchemaSpec {
+  name: string;
+  schema: Record<string, unknown>;
+  /** Enforces the schema strictly (OpenAI-specific), default true when supported */
+  strict?: boolean;
+  description?: string;
+}
+//#endregion
+//#region src/types/tools.d.ts
+/**
+ * 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 extends string = string, Args = unknown> {
+  name: Name;
+  description: string;
+  /** JSON Schema for the tool's input. */
+  parameters: Record<string, unknown>;
+  /**
+   * Validates the parsed `arguments`, using the same `safeParse` shape as `schema`. Failure throws
+   * `LLMError('validation')`; on success `ToolCall.arguments` is the schema's output, defaults and
+   * transforms applied. Without it, arguments are parsed as JSON only. Types flow into `ToolCall`
+   * when the tool's `name` is literal, see `defineTool()`.
+   */
+  argumentsSchema?: SchemaLike<Args>;
+}
+/**
+ * Keeps a tool's literal `name` and inferred `Args`, so `ToolCall` narrows by name. A plain object
+ * literal widens `name` to `string` without `as const`, which breaks narrowing once a second tool
+ * is added.
+ */
+declare function defineTool<const Name extends string, Args = unknown>(tool: ToolDefinition<Name, Args>): ToolDefinition<Name, Args>;
+/** Maps a single `ToolDefinition` to its matching `ToolCall` shape. */
+type ToolCallFor<T> = T extends ToolDefinition<infer N, infer A> ? {
+  id: string;
+  name: N;
+  arguments: A;
+} : never;
+/**
+ * One tool call from the model. With a literal `Tools` tuple this is a union keyed by `name`, so
+ * checking `name` narrows `arguments`. Otherwise `arguments` is `unknown`.
+ */
+type ToolCall<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = ToolCallFor<Tools[number]>;
+/** The application's result of executing a `ToolCall`, sent back to the model. */
+interface ToolResult {
+  toolCallId: string;
+  content: unknown;
+  /**
+   * Marks a failed tool execution. Sent as Anthropic's `is_error` and Bedrock's error status;
+   * OpenAI-compatible adapters prefix the content with `Error: `; Gemini has no equivalent and
+   * ignores it.
+   */
+  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<Tools extends readonly ToolDefinition[] = ToolDefinition[]> {
+  type: 'tool_calls';
+  toolCalls: ToolCall<Tools>[];
+  /** Any text the model produced alongside the tool request, if present. */
+  content?: string;
+  /**
+   * Claude's reasoning blocks before this tool request, when thinking is
+   * on (`fromAnthropic` and `fromBedrock`). Put them on the assistant
+   * history turn with `toolCalls` so the tool loop can continue.
+   */
+  thinking?: ThinkingBlock[];
+}
+type CallWithToolsResult<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = ContentResult<T> | ToolCallResult<Tools>;
+/** Recovers `Tools` from a `result` already typed `ContentResult<T> | ToolCallResult<Tools>`. Falls back to `ToolDefinition[]`. */
+type ExtractTools<R> = Extract<R, ToolCallResult<ToolDefinition[]>> extends ToolCallResult<infer Tools> ? Tools : ToolDefinition[];
+/** Explicit `Tools` type argument if given, otherwise inferred via `ExtractTools`. `never` marks "unset". */
+type ResolvedTools<Tools, R> = [Tools] extends [never] ? ExtractTools<R> : Tools;
+/**
+ * Whether a `call()` result is a tool calls result. Use it whenever `tools` was set conditionally.
+ * `toolCalls[number].arguments` is typed per tool; pass `Tools` explicitly to override inference,
+ * e.g. `isToolCallResult<typeof tools>(result)`.
+ */
+declare function isToolCallResult<Tools extends readonly ToolDefinition[] | undefined = never, R = unknown>(result: R): result is R & ToolCallResult<NonNullable<ResolvedTools<Tools, R>>>;
+/** What the model should do about tools on a given call. */
+type ToolChoice = 'auto' | 'none' | 'required' | {
+  name: string;
+};
+//#endregion
+//#region src/types/call.d.ts
+/**
+ * Any valid JSON value: a primitive, `null`, or a JSON array/object made
+ * of the same. This is what `call()` returns when `jsonMode: true`.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Plain JSON describing the request, e.g. tenant or routing constraints. Never sent to the
+ * provider.
+ */
+type CallContext = {
+  readonly [key: string]: JsonValue;
+};
+/**
+ * Content for an `assistant` turn in `history`. A parsed `JsonValue` from a `jsonMode` response can
+ * go straight back in; it is stringified before sending.
+ */
+type AssistantContent = string | JsonValue;
+/**
+ * A reasoning block Claude produced before a tool call. Pass it back untouched on the assistant
+ * turn that requested the tools: Claude with thinking on rejects the next call without it, and the
+ * `signature` covers the text.
+ */
+type ThinkingBlock = {
+  type: 'thinking';
+  thinking: string;
+  signature: string;
+} | {
+  type: 'redacted_thinking';
+  data: string;
+};
+/**
+ * One prior turn in `history`. A tool turn must directly follow the assistant turn that called the
+ * tools, with a result for every call.
+ */
+type ConversationTurn = {
+  role: 'user';
+  content: string;
+} | {
+  role: 'assistant';
+  content?: AssistantContent;
+  toolCalls?: ToolCall[];
+  /**
+   * Reasoning blocks from this turn, as `ToolCallResult.thinking`
+   * returned them. Sent ahead of the text and tool calls by
+   * `fromAnthropic` and `fromBedrock`; other adapters drop them.
+   */
+  thinking?: ThinkingBlock[];
+} | {
+  role: 'tool';
+  toolResults: ToolResult[];
+};
+/** A plain text segment of a multimodal `userContent` array. */
+interface TextBlock {
+  type: 'text';
+  text: string;
+}
+/**
+ * An inline image in a multimodal `userContent` array. `data` is raw base64 with no `data:` prefix;
+ * each adapter converts it as its provider needs.
+ */
+interface ImageBlock {
+  type: 'image';
+  /** Base64-encoded image bytes, no `data:` prefix */
+  data: string;
+  /** e.g. 'image/png', 'image/jpeg', 'image/webp', 'image/gif' */
+  mimeType: string;
+}
+/** A single segment of multimodal `userContent`. */
+type ContentBlock = TextBlock | ImageBlock;
+/**
+ * Every request field except the `UsageHooks`. The `Cached*` params use it, since `cachedCall`
+ * meters usage once at the top level.
+ */
+interface LLMRequestShape<T = unknown, Tools extends readonly ToolDefinition[] = ToolDefinition[]> {
+  systemPrompt?: string;
+  /** Current user message, as text or multimodal content blocks. */
+  userContent: string | ContentBlock[];
+  /**
+   * Previous conversation turns. Must alternate roles; tool turns must follow
+   * assistant tool calls. Invalid history throws LLMError('invalid_params').
+   */
+  history?: ConversationTurn[];
+  /**
+   * 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;
+  /**
+   * Total ms budget for the whole call, across retries and fallback targets, unlike the per attempt
+   * `timeoutMs`. Covers getting to a result and opening a stream, not reading one; use
+   * `chunkIdleTimeoutMs` for that. Omit or pass Infinity for none.
+   */
+  deadlineMs?: number;
+  /**
+   * Per call override for the max gap between stream chunks. Only applies with `stream: true`. Pass
+   * 0 to disable.
+   */
+  chunkIdleTimeoutMs?: number;
+  /**
+   * Overrides the instance model for this call. Applies to the primary
+   * target only, fallback targets always run their own configured model.
+   */
+  model?: string;
+  /**
+   * Reasoning effort for supported models. `null` skips `defaultReasoningEffort` for this call, as
+   * `temperature: null` does; `undefined` uses the default.
+   */
+  reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | null;
+  /**
+   * Reasoning token budget, for providers with a numeric budget. Providers with only effort tiers
+   * get the nearest tier. With both set, each adapter uses the one it understands. `null` skips
+   * `defaultBudgetTokens`.
+   */
+  budgetTokens?: number | null;
+  /**
+   * Provider-native JSON Schema output constraint. Implies jsonMode: true.
+   */
+  jsonSchema?: JsonSchemaSpec;
+  /**
+   * Validates parsed JSON output. Failure throws LLMError('validation').
+   * Implies jsonMode: true.
+   */
+  schema?: SchemaLike<T>;
+  /**
+   * Tools the model may call. Makes `call()` return `CallWithToolsResult<T>`. A literal array also
+   * types each tool's `arguments`.
+   */
+  tools?: Tools;
+  /** Defaults to `'auto'` when `tools` is set. */
+  toolChoice?: ToolChoice;
+  /**
+   * Streams the response. Requires an adapter with `createStream`. Retries and fallback cover the
+   * stream until its first content; later failures reject `finalResult`. `finalResult` resolves to
+   * the same shape a non-streaming call returns. See `StreamCallResult`.
+   */
+  stream?: boolean;
+  /**
+   * Out parameter written with the answering target's `CallMeta`, set before `call()` returns,
+   * streams included. Left untouched when a `wrap` middleware short-circuits, so a reused holder
+   * may keep an older value.
+   */
+  meta?: {
+    current?: CallMeta;
+  };
+  /** See `CallContext`. Read by middleware, events and usage. */
+  context?: CallContext;
+  /** Values placed in `ctx.state` before any middleware runs. Build entries with `stateEntry`. */
+  state?: readonly MiddlewareStateEntry[];
+  /** Target names to try, in order. Default: every target, as declared. */
+  targets?: readonly string[];
+}
+interface CallParams<T = unknown, Tools extends readonly ToolDefinition[] = ToolDefinition[]> extends LLMRequestShape<T, Tools>, UsageHooks {}
+/** `CallParams` with `tools` set, selecting the overload that returns `CallWithToolsResult<T>`. */
+type ToolEnabledCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  tools: NonNullable<CallParams<T, Tools>['tools']>;
+};
+/**
+ * `CallParams` for conditionally set tools, e.g. `tools: flag ? [tool] : undefined`. Returns `T |
+ * CallWithToolsResult<T, Tools>`, forcing an `isToolCallResult()` check. Typed `arguments` need an
+ * explicit `Tools` argument on that check, since a ternary loses the literal tuple.
+ */
+type ConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  tools: Tools | undefined;
+};
+/** Conditional tool-call parameters whose non-tool result is plain text. */
+type ConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = ConditionalToolCallParams<string, Tools> & {
+  jsonMode: false;
+};
+/**
+ * `CallParams` with `toolChoice: 'none'`. The model can't call a tool, so `call()` returns
+ * `ContentResult<T>` and no `isToolCallResult` check is needed.
+ */
+type ToolsDisabledCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  tools: NonNullable<CallParams<T, Tools>['tools']>;
+  toolChoice: 'none';
+};
+/**
+ * `CallParams` with `jsonMode: false`, returning a `string`. `jsonSchema` is `never`, since a
+ * schema forces JSON parsing regardless of `jsonMode`.
+ */
+type JsonModeDisabledCallParams = Omit<CallParams<unknown>, 'jsonSchema'> & {
+  jsonMode: false;
+  jsonSchema?: never;
+};
+/**
+ * `CallParams` with `jsonMode: true` and no `schema`, returning `JsonValue`. `schema` is `never`
+ * rather than omitted, so a schema whose output happens to fit `JsonValue` still picks the schema
+ * aware overload.
+ */
+type JsonModeEnabledCallParams = Omit<CallParams<JsonValue>, 'schema'> & {
+  jsonMode: true;
+  schema?: never;
+};
+/** Shared cache-configuration fields, minus the internal `fn` primitive. */
+interface CachedCallInput extends UsageHooks {
+  cacheKey: string;
+  ttl: number;
+  signal?: AbortSignal;
+}
+/**
+ * A cached call without tools: cache config plus the `call` params. `reserveUsage` and
+ * `refundUsage` go at the top level, not inside `call`.
+ */
+type CachedCallParams<T> = CachedCallInput & {
+  call: LLMRequestShape<T>;
+};
+/** A cached call with tools. Tool requests and content responses are cached exactly as returned. */
+type CachedToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  call: LLMRequestShape<T, Tools> & {
+    tools: NonNullable<LLMRequestShape<T, Tools>['tools']>;
+  };
+};
+/**
+ * A cached call with `call.tools` set conditionally. Returns `T | CallWithToolsResult<T>`, see
+ * `ConditionalToolCallParams`.
+ */
+type CachedConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  call: LLMRequestShape<T, Tools> & {
+    tools: Tools | undefined;
+  };
+};
+/** Cached conditional tool-call parameters whose non-tool result is plain text. */
+type CachedConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedConditionalToolCallParams<string, Tools> & {
+  call: {
+    jsonMode: false;
+  };
+};
+/**
+ * Parameters for a cached LLM call with `jsonMode: false`. Selects the
+ * `cachedCall()` overload that returns a plain `string`.
+ */
+type CachedJsonModeDisabledCallParams = CachedCallInput & {
+  call: Omit<LLMRequestShape<unknown>, 'jsonSchema'> & {
+    jsonMode: false;
+    jsonSchema?: never;
+  };
+};
+/**
+ * Parameters for a cached LLM call with `jsonMode: true` and no `schema`.
+ * Selects the `cachedCall()` overload that returns a `JsonValue`.
+ */
+type CachedJsonModeEnabledCallParams = CachedCallInput & {
+  call: Omit<LLMRequestShape<JsonValue>, 'schema'> & {
+    jsonMode: true;
+    schema?: never;
+  };
+};
+/** Context handed to `DetectSoftFailure` alongside the response it's inspecting. */
+interface SoftFailureMeta {
+  requestId: string;
+  model: string;
+  providerName: string;
+  isFallback: boolean;
+  /** 1-based, matching `CallMeta.attempts`. */
+  attempt: number;
+  /**
+   * Usage for this attempt, if reported. `undefined` means unknown, not zero, so treat it as such
+   * in cost checks.
+   */
+  usage?: TokenUsage;
+}
+/**
+ * Reclassifies an otherwise successful result. Return an `LLMErrorCode` to fail the attempt through
+ * the normal retry and breaker paths, or `undefined` to keep it. Catches empty, truncated or
+ * refusal answers that parse fine.
+ */
+type DetectSoftFailure<T = unknown> = (result: T | CallWithToolsResult<T>, meta: SoftFailureMeta) => LLMErrorCode | undefined;
+//#endregion
+//#region src/types/stream.d.ts
+/** 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` holds the whole arguments rather than a fragment, as with Gemini and
+   * cache replays.
+   */
+  complete?: boolean;
+} | {
+  type: 'usage';
+  usage: TokenUsage;
+};
+/**
+ * What `call()` returns with `stream: true`. `finalResult` resolves to the same shape a
+ * non-streaming call returns. `chunks` is single use; see the streaming docs.
+ */
+interface StreamCallResult<R> {
+  chunks: AsyncIterable<StreamChunk>;
+  finalResult: Promise<R>;
+}
+/** `CallParams` with `stream: true`, selecting the overload that returns `StreamCallResult`. */
+type StreamEnabledCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CallParams<T, Tools> & {
+  stream: true;
+};
+/** Streaming conditional tool-call parameters whose non-tool result is text. */
+type StreamConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = StreamEnabledCallParams<string, Tools> & ConditionalStringToolCallParams<Tools>;
+/** Recovers `T` from a `result` already typed `T | StreamCallResult<T>`. Falls back to `unknown`. */
+type ExtractStreamValue<R> = Extract<R, StreamCallResult<unknown>> extends StreamCallResult<infer V> ? V : unknown;
+/**
+ * Whether a `call()` result is a `StreamCallResult`. Useful when `stream` was set conditionally,
+ * since the overloads only pick the streaming shape for a literal `stream: true`.
+ */
+declare function isStreamResult<R = unknown>(result: R): result is R & StreamCallResult<ExtractStreamValue<R>>;
+/**
+ * Streaming `jsonMode: false`, with `finalResult` as a `string`. `jsonSchema` is `never`, as in
+ * `JsonModeDisabledCallParams`.
+ */
+type StreamJsonModeDisabledCallParams = Omit<StreamEnabledCallParams<unknown>, 'jsonSchema'> & {
+  jsonMode: false;
+  jsonSchema?: never;
+};
+/**
+ * Streaming `jsonMode: true` without `schema`, with `finalResult` as `JsonValue`. `schema` is
+ * `never`, as in `JsonModeEnabledCallParams`.
+ */
+type StreamJsonModeEnabledCallParams = Omit<StreamEnabledCallParams<JsonValue>, 'schema'> & {
+  jsonMode: true;
+  schema?: never;
+};
+/**
+ * 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;
+    completion_tokens_details?: {
+      reasoning_tokens?: number;
+    };
+    /** Cache split of `prompt_tokens`. Follows OpenAI and OpenRouter naming. */
+    prompt_tokens_details?: {
+      cached_tokens?: number;
+      cache_write_tokens?: number;
+      /** Writes by TTL label, e.g. `{ '5m': 1200, '1h': 800 }`. */
+      cache_write_tokens_by_ttl?: Record<string, number>;
+    };
+  };
+} | {
+  /** A provider keep-alive with no content. Resets the idle timeout; never reaches callers. */
+  type: 'ping';
+} | {
+  /**
+   * A rate limit hint from the stream's response headers, yielded as early as possible for
+   * AIMD. The streaming counterpart of `attachRateLimitHint`. Never reaches callers.
+   */
+  type: 'rate_limit_hint';
+  hint: ProviderRateLimitHint;
+} | {
+  /**
+   * One complete reasoning block, yielded once it has fully arrived.
+   * Collected onto `ToolCallResult.thinking`, never surfaced to
+   * callers as a `StreamChunk`.
+   */
+  type: 'thinking_block';
+  block: ThinkingBlock;
+};
+/**
+ * A cached streaming call without tools. A miss relays live chunks; a hit replays the cached value
+ * as chunks. `reserveUsage` and `refundUsage` go at the top level.
+ */
+type CachedStreamCallParams<T> = CachedCallInput & {
+  call: LLMRequestShape<T> & {
+    stream: true;
+  };
+};
+/** A cached streaming call with tools, caching the full `CallWithToolsResult<T>`. */
+type CachedStreamToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  call: LLMRequestShape<T, Tools> & {
+    stream: true;
+    tools: NonNullable<LLMRequestShape<T, Tools>['tools']>;
+  };
+};
+/**
+ * A cached streaming call with `call.tools` set conditionally, resolving to `T |
+ * CallWithToolsResult<T>`.
+ */
+type CachedStreamConditionalToolCallParams<T, Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedCallInput & {
+  call: LLMRequestShape<T, Tools> & {
+    stream: true;
+    tools: Tools | undefined;
+  };
+};
+/** Cached streaming conditional tool-call parameters whose non-tool result is text. */
+type CachedStreamConditionalStringToolCallParams<Tools extends readonly ToolDefinition[] = ToolDefinition[]> = CachedStreamConditionalToolCallParams<string, Tools> & {
+  call: {
+    jsonMode: false;
+  };
+};
+/**
+ * Parameters for a cached, streaming LLM call with `jsonMode: false`.
+ * Selects the `cachedCall()` overload whose `finalResult` (on a miss) or
+ * cached value (on a hit) is a plain `string`.
+ */
+type CachedStreamJsonModeDisabledCallParams = CachedCallInput & {
+  call: Omit<LLMRequestShape<unknown>, 'jsonSchema'> & {
+    stream: true;
+    jsonMode: false;
+    jsonSchema?: never;
+  };
+};
+/**
+ * Parameters for a cached, streaming LLM call with `jsonMode: true` and no
+ * `schema`. Selects the `cachedCall()` overload whose `finalResult` (on a
+ * miss) or cached value (on a hit) is a `JsonValue`.
+ */
+type CachedStreamJsonModeEnabledCallParams = CachedCallInput & {
+  call: Omit<LLMRequestShape<JsonValue>, 'schema'> & {
+    stream: true;
+    jsonMode: true;
+    schema?: never;
+  };
+};
+//#endregion
+//#region src/types/client.d.ts
+/** 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[];
+  /** Reasoning blocks to send back ahead of the text and tool calls. Adapters without the concept drop it. */
+  thinking?: ThinkingBlock[];
+} | {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+  /** Honored by `fromAnthropic` (maps to `tool_result.is_error`) and `fromBedrock` (maps to `toolResult.status`); other adapters ignore it. */
+  is_error?: boolean;
+};
+/** The OpenAI-shaped wire `tool_choice`. */
+type WireToolChoice = 'auto' | 'none' | 'required' | {
+  type: 'function';
+  function: {
+    name: string;
+  };
+};
+/**
+ * Which adapter built an `LLMClient`, and which provider it talks to.
+ * Read by middleware through `AttemptContext.adapter`, so telemetry can
+ * name the provider without guessing from the model id.
+ */
+interface AdapterInfo {
+  /** Adapter family, e.g. `'anthropic'`, `'openai-compatible'`, or `'custom'` for a client that sets none. */
+  name: string;
+  /**
+   * The provider this client talks to, in the OpenTelemetry
+   * `gen_ai.provider.name` vocabulary (`'openai'`, `'anthropic'`,
+   * `'aws.bedrock'`, ...). Only set when the adapter knows it for certain.
+   */
+  provider?: string;
+}
+/**
+ * The client shape adapters implement, modeled on OpenAI's `chat.completions.create`. Structural
+ * rather than an SDK's own types, since not every SDK's types accept every field.
+ */
+interface LLMClient {
+  /**
+   * Whether `response_format: 'json_object'` is really enforced. Defaults to `true`. `false` makes
+   * a default `jsonMode` fall back to plain text instead of getting an unenforced no-op, while an
+   * explicit `jsonMode: true` throws.
+   */
+  supportsJsonObjectMode?: boolean;
+  /** Whether cache reads count toward this provider's token rate limit. Default `true`. */
+  cacheReadsCountTowardRateLimit?: boolean;
+  /** Which adapter built this client. Every built in adapter sets it; a hand written client may leave it out. */
+  adapter?: AdapterInfo;
+  /**
+   * Hands the client the `VernLLM` instance's logger, once per target at
+   * construction, for adapter log lines. A client shared by several
+   * instances keeps the last one it was given.
+   */
+  setLogger?(logger: Logger): void;
+  chat: {
+    completions: {
+      create(params: {
+        model: string;
+        temperature?: number;
+        max_tokens: number;
+        response_format?: {
+          type: 'json_object';
+        } | {
+          type: 'json_schema';
+          json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean;
+            description?: string;
+          };
+        };
+        /** OpenAI reasoning-model param (o-series, gpt-5), ignored by providers that don't support it */
+        reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+        /**
+         * Numeric reasoning budget, for providers with one. Clients with only effort tiers use
+         * `reasoning_effort` instead.
+         */
+        budget_tokens?: number;
+        /** 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[];
+            /** Reasoning blocks the model produced, in order. Only Claude adapters report them. */
+            thinking?: ThinkingBlock[];
+          };
+          /**
+           * Why generation stopped, in OpenAI's terms. Only `'length'` is read: output that then
+           * fails to parse becomes the retryable `response_truncated`. Optional.
+           */
+          finish_reason?: string | null;
+        }>;
+        usage?: {
+          prompt_tokens?: number;
+          completion_tokens?: number;
+          total_tokens?: number;
+          completion_tokens_details?: {
+            reasoning_tokens?: number;
+          };
+          /** Cache split of `prompt_tokens`. Follows OpenAI and OpenRouter naming. */
+          prompt_tokens_details?: {
+            cached_tokens?: number;
+            cache_write_tokens?: number;
+            /** Writes by TTL label, e.g. `{ '5m': 1200, '1h': 800 }`. */
+            cache_write_tokens_by_ttl?: Record<string, number>;
+          };
+        };
+      }>;
+      /**
+       * Required only for `stream: true`, which throws a clear error without it. Takes the same
+       * request as `create`.
+       */
+      createStream?(params: Parameters<LLMClient['chat']['completions']['create']>[0], options: {
+        signal: AbortSignal;
+      }): AsyncIterable<WireStreamChunk>;
+    };
+  };
+}
+//#endregion
+export { SchemaLike as $, createStateKey as $t, ConditionalToolCallParams as A, ConsecutiveTripping as At, ThinkingBlock as B, MiddlewareRef as Bt, CachedConditionalToolCallParams as C, hasIssues as Cn, RetryBudgetOptions as Ct, CallContext as D, CircuitBreakerOptions as Dt, CachedToolCallParams as E, CircuitBreakerCallContext as Et, JsonModeDisabledCallParams as F, AttemptContext as Ft, ToolCall as G, RequiredMiddlewareRef as Gt, ToolsDisabledCallParams as H, MiddlewareStateEntry as Ht, JsonModeEnabledCallParams as I, CallResult as It, ToolDefinition as J, WireCallRequestPatch as Jt, ToolCallResult as K, VernLLMMiddleware as Kt, JsonValue as L, MiddlewareCapabilities as Lt, ConversationTurn as M, ExponentialBackoffOptions as Mt, DetectSoftFailure as N, RollingTripping as Nt, CallParams as O, CircuitBreakerStateChangeHandler as Ot, ImageBlock as P, TrippingPolicy as Pt, JsonSchemaSpec as Q, createMiddlewareStateBag as Qt, LLMRequestShape as R, MiddlewareContext as Rt, CachedConditionalStringToolCallParams as S, UnsupportedCapabilityIssue as Sn, RetryBudget as St, CachedJsonModeEnabledCallParams as T, CircuitBreakerAdapter as Tt, CallWithToolsResult as U, MiddlewareStateKey as Ut, ToolEnabledCallParams as V, MiddlewareStateBag as Vt, ContentResult as W, PreDispatchContext as Wt, defineTool as X, WireTool as Xt, ToolResult as Y, WireResponseFormat as Yt, isToolCallResult as Z, createMiddlewareRef as Zt, StreamJsonModeEnabledCallParams as _, LLMErrorType as _n, RateLimiter as _t, WireToolChoice as a, OnUsageFailure as an, FallbackOnContext as at, AssistantContent as b, ToolIssue as bn, ProviderRateLimitHint as bt, CachedStreamConditionalToolCallParams as c, TokenUsage as cn, TargetInfo as ct, CachedStreamToolCallParams as d, DuplicateToolNamesIssue as dn, metaRef as dt, requireRef as en, CallMeta as et, StreamCallResult as f, HistoryToolResultIssue as fn, RateLimitOption as ft, StreamJsonModeDisabledCallParams as g, LLMErrorSnapshot as gn, RateLimitState as gt, StreamEnabledCallParams as h, LLMErrorIssuesByCode as hn, RateLimitReason as ht, WireToolCall as i, OnUsage as in, FallbackOn as it, ContentBlock as j, CooldownBackoff as jt, ConditionalStringToolCallParams as k, CircuitState as kt, CachedStreamJsonModeDisabledCallParams as l, ConsoleLogger as ln, defaultFallbackOn as lt, StreamConditionalStringToolCallParams as m, LLMErrorCode as mn, RateLimitOptions as mt, LLMClient as n, OnEvent as nn, FallbackAttempt as nt, CachedStreamCallParams as o, RefundUsage as on, FallbackTarget as ot, StreamChunk as p, LLMError as pn, RateLimitAcquireResult as pt, ToolChoice as q, WireCallRequest as qt, WireMessage as r, VernLLMEvent as rn, FallbackExhaustedError as rt, CachedStreamConditionalStringToolCallParams as s, ReserveUsage as sn, TargetCircuitState as st, AdapterInfo as t, stateEntry as tn, CircuitTarget as tt, CachedStreamJsonModeEnabledCallParams as u, Logger as un, isFallbackExhaustedError as ut, WireStreamChunk as v, LLMRequestSnapshot as vn, RateLimiterAdapter as vt, CachedJsonModeDisabledCallParams as w, isLLMError as wn, CircuitBreaker as wt, CachedCallParams as x, UnknownToolChoiceIssue as xn, CircuitBreakerOption as xt, isStreamResult as y, RetryAttempt as yn, WireRequest as yt, TextBlock as z, MiddlewareContextBase as zt };
+//# sourceMappingURL=client-HWxkwVvj.d.cts.map