vern-llm 2.1.1 → 2.3.0

package/dist/index.d.cts

@@ -1,87 +1,22 @@
-//#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';
+type LLMErrorType = 'timeout' | 'api' | 'network' | 'parse' | 'validation' | 'invalid_params' | 'rate_limited' | 'quota_exceeded' | 'circuit_open' | 'fallback_exhausted' | 'aborted' | 'unknown';
 /**
  * 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.
+ * before a given code existed simply omit it. Not owned by a single type;
+ * e.g. `authentication`/`authorization` apply the same way regardless of
+ * which type wraps them.
  */
-type LLMErrorCode = 'unknown_tool' | 'duplicate_tool_call_id' | 'local_rate_limit' | 'provider_rate_limited' | 'fallback_exhausted';
+type LLMErrorCode = 'unknown_tool' | 'duplicate_tool_call_id' | 'tool_choice_none_violated' | 'unexpected_tool_calls' | 'unsupported_capability' | 'duplicate_tool_names' | 'unknown_tool_choice' | 'duplicate_tool_result_ids' | 'unknown_tool_result_ids' | 'missing_tool_results' | 'rate_limit_queue_full' | 'rate_limit_queue_timeout' | 'rate_limit_capacity_exceeded' | 'provider_rate_limited' | 'request_timeout' | 'idle_timeout' | 'authentication' | 'authorization' | 'not_found' | 'payload_too_large' | 'server_error' | 'empty_response' | 'connection_failed' | 'circuit_cooling_down' | 'circuit_trial_in_flight' | 'fallback_exhausted' | 'tool_arguments_parse_failed' | 'stream_frame_invalid';
+/**
+ * Tool contract codes: a model or provider response defect, not a
+ * transient provider fault. Deterministic on the wire request, so
+ * retrying can't change the outcome and it shouldn't count toward the
+ * circuit breaker either. Shared by `LLMError.retryable` below and by
+ * `CallExecutor`'s own retry/breaker accounting, so the two can't drift
+ * apart.
+ */
+
 /** One tool call's contract failure, used to report every bad call in a response at once. */
 interface ToolIssue {
   name: string;
@@ -89,23 +24,184 @@ interface ToolIssue {
   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;
+}
+/**
+ * Maps each `LLMErrorCode` that carries structured `issues` to that
+ * payload's exact shape. Not every code appears here: most `invalid_params`
+ * failures are a single deterministic fact the `message` already states in
+ * full, so adding a typed `issues` entry for them would only duplicate the
+ * message into a field, the same near-duplicate-code problem `code` itself
+ * avoids. Codes that repeat here are exactly the ones whose `message`
+ * already string-joins a list a caller might want to consume directly
+ * rather than re-parse out of prose, or that otherwise want a place to
+ * report the exact captured values of a failure.
+ *
+ * Deliberately not a mapped type over the whole `LLMErrorCode` union: a
+ * schema-validation failure's `issues` (the caller's own Zod-compatible
+ * validator's error object) has no code and no shape VernLLM could know in
+ * advance, so it stays untyped on `LLMError.issues` itself rather than
+ * forcing every code into this table.
+ */
+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;
+}
+/**
+ * Point-in-time copy of an `LLMError`'s fields, produced by
+ * `LLMError.toSnapshot()`. This is what `RetryAttempt.error` holds
+ * instead of a live `LLMError`.
+ *
+ * A past attempt only needs to be describable (message, type, code,
+ * whether it was retryable), never thrown again. So it skips `Error`'s
+ * behavior, `instanceof` identity, and any live getter. Using the full
+ * `LLMError` class here would also make the type self referential
+ * through its own `attempts` field.
+ *
+ * Has no `cause`. `cause` is `unknown` and never validated by VernLLM,
+ * and it is meant to be read directly on the live error you just
+ * caught, not carried indefinitely inside history. `type`, `code`,
+ * `status`, and `issues` are the structured fields a snapshot carries
+ * instead.
+ *
+ * `attempts` is still present, since a recorded attempt can itself be
+ * the terminal failure of an inner retry loop with its own history (see
+ * `FallbackAttempt`). That's a tree of past data, 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[];
+}
+/**
+ * One failed attempt on the way to a terminal error: which attempt index
+ * it was, and a snapshot of the error it failed with. The base shape
+ * every richer attempt record (e.g. `FallbackAttempt`) extends, rather
+ * than duplicates.
+ */
+interface RetryAttempt {
+  index: number;
+  error: LLMErrorSnapshot;
+}
+/** 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 | undefined;
-  issues?: unknown | undefined;
-  cause?: unknown | undefined;
-  retryAfterMs?: number | undefined;
+  status?: number;
+  issues?: unknown;
+  cause?: unknown;
+  retryAfterMs?: number;
   /** 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[];
+  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);
+  /**
+   * Computed purely from `type`/`code`, independent of any specific call's
+   * `nonRetryableStatus` list. False for `parse`/`validation`/
+   * `invalid_params`/`aborted` types (the caller's own input, the model's
+   * own response, or intentional cancellation, none of which are the
+   * provider being unhealthy), the tool contract codes, and the local
+   * rate limit codes. Subclasses (see `FallbackExhaustedError`) may
+   * override this when `type` alone carries no retry signal.
+   */
+  get retryable(): boolean;
+  /**
+   * Copies this error's fields into an {@link LLMErrorSnapshot}, for
+   * recording as a `RetryAttempt`/`FallbackAttempt`. `retryable` is
+   * captured here since a snapshot has no getter of its own. `cause` is
+   * not copied, see `LLMErrorSnapshot`'s own doc. `issues` and every
+   * nested `attempts` entry's own `issues` go through `safeAttempts`,
+   * since a schema validation failure's `issues` is a caller supplied
+   * value, not controlled by VernLLM, and `attempts` is itself a public
+   * constructor option a caller can hand build.
+   */
+  toSnapshot(): LLMErrorSnapshot;
+  /**
+   * Controls what `JSON.stringify(err)` produces. Omits `cause` for the
+   * same reason `toSnapshot()` does: `cause` is `unknown` and never
+   * validated by VernLLM, and some SDK errors carry circular structures
+   * `JSON.stringify` cannot serialize at all. Read `err.cause` directly
+   * instead. `issues`, including every nested `attempts` entry's own
+   * `issues`, goes through `safeAttempts` for the same reason: a schema
+   * validation failure's `issues` is caller supplied and not guaranteed
+   * circular free. Also includes `message` and `retryable`, which a
+   * plain property walk would otherwise miss: `message` is
+   * non-enumerable on `Error`, and `retryable` is a getter, not an own
+   * property.
+   */
+  toJSON(): Record<string, unknown>;
 }
 declare function isLLMError(err: unknown): err is LLMError;
-
-//#endregion
+/**
+ * Narrows `err.issues` to the exact shape {@link LLMErrorIssuesByCode} maps
+ * `code` to, for any code listed there. `code` stays the only discriminator
+ * VernLLM uses; this just gives that existing check a typed return instead
+ * of requiring a manual cast of `issues`:
+ *
+ * ```ts
+ * if (isLLMError(err) && hasIssues(err, 'duplicate_tool_names')) {
+ *   console.log(err.issues.names); // string[], no cast needed
+ * }
+ * ```
+ */
+declare function hasIssues<C extends keyof LLMErrorIssuesByCode>(err: LLMError, code: C): err is LLMError & {
+  code: C;
+  issues: LLMErrorIssuesByCode[C];
+}; //#endregion
 //#region src/types/cache.d.ts
+
 //# sourceMappingURL=errors.d.ts.map
 interface CacheAdapter<T = unknown> {
   get(key: string): Promise<{
@@ -172,8 +268,102 @@ declare class TieredCacheAdapter<T = unknown> implements CacheAdapter<T> {
 }
 
 //#endregion
-//#region src/rateLimit.d.ts
+//#region src/circuitBreaker.d.ts
 //# sourceMappingURL=cache.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;
+  /**
+   * 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?;
+  /** Whether this breaker tracks failures per model instead of one shared circuit. Read by `CallExecutor`/`VernLLM` to report per-target in `getCircuitStates`. */
+  readonly isolateByModel: boolean;
+  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;
+  /**
+   * Manually opens the circuit, as if `threshold` consecutive failures had
+   * just happened, e.g. to pull a provider out of rotation ahead of known
+   * maintenance. Resets the cooldown window from now, same as a real
+   * threshold-crossing failure would, and clears any in-flight half-open
+   * trial since it no longer applies once the circuit is (re)opened.
+   */
+  open(model?: string): void;
+  /**
+   * Manually closes the circuit and resets its failure count, e.g. once a
+   * provider is confirmed healthy again without waiting out the cooldown.
+   * Mirrors `recordSuccess`'s bookkeeping (including dropping the
+   * per-model bucket under `isolateByModel`, once idle) but without
+   * requiring an actual successful call first.
+   */
+  close(model?: string): void;
+}
+
+//#endregion
+//#region src/rateLimit.d.ts
+//# sourceMappingURL=circuitBreaker.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. */
@@ -331,16 +521,27 @@ interface TargetCircuitState {
   /** 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;
 }
-/** One target's failure, recorded on the way to either the next target or `FallbackExhaustedError`. */
-interface FallbackAttempt {
-  /** `-1` for the primary target. */
-  index: number;
+/** 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, recorded on the way to either the next target or
+ * `FallbackExhaustedError`. Extends `RetryAttempt`: `index` is `-1` for
+ * the primary target here (rather than a plain retry count), and
+ * `provider`/`model` identify which target failed.
+ */
+interface FallbackAttempt extends RetryAttempt {
   provider: string;
   model: string;
-  error: LLMError;
 }
 /**
  * Decides what happens after a target's own retries are exhausted or
@@ -361,13 +562,23 @@ declare const defaultFallbackOn: FallbackOn;
  * 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.
+ * still passes, inheriting the last failure's `type`/`status`/`retryAfterMs`
+ * so existing type-based handling, including reading `retryAfterMs` on an
+ * `'api'`-typed error, keeps working on a fallback-exhausted error too.
  */
 declare class FallbackExhaustedError extends LLMError {
   readonly attempts: FallbackAttempt[];
   constructor(attempts: FallbackAttempt[]);
+  /**
+   * `type: 'fallback_exhausted'` by itself says nothing about whether
+   * retrying could help; the reason the last target failed does. Defers to
+   * that attempt's own `retryable` instead of anything about this class's
+   * own type.
+   */
+  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;
 
 //#endregion
 //#region src/types/schema.d.ts
@@ -676,6 +887,20 @@ interface CallParams<T = unknown> extends UsageHooks {
 type ToolEnabledCallParams<T> = CallParams<T> & {
   tools: NonNullable<CallParams<T>['tools']>;
 };
+/**
+ * A `CallParams` variant where tools are offered but the model is barred
+ * from calling one. `toolChoice: 'none'` guarantees the response can never
+ * be a `tool_calls` result, so `call()` can narrow straight to
+ * `ContentResult<T>` instead of the full `CallWithToolsResult<T>` union.
+ * A call site that already knows it forced `'none'` no longer needs a
+ * runtime `isToolCallResult` check, or to remember that `String(result)`
+ * on the wrapper object silently produces `"[object Object]"` instead of
+ * throwing. The type itself rules that shape out.
+ */
+type ToolsDisabledCallParams<T> = CallParams<T> & {
+  tools: NonNullable<CallParams<T>['tools']>;
+  toolChoice: 'none';
+};
 /** Shared cache-configuration fields, minus the internal `fn` primitive. */
 interface CachedCallInput extends UsageHooks {
   cacheKey: string;
@@ -687,9 +912,21 @@ interface CachedCallInput extends UsageHooks {
  *
  * Combines the cache configuration with the `CallParams` passed to
  * `VernLLM.call()`. The cached value is the normal LLM response type `T`.
+ *
+ * `reserveUsage`/`refundUsage` are omitted from `call`'s type on purpose:
+ * `CachedCallInput` already extends `UsageHooks`, so those two hooks
+ * belong at the top level, alongside `cacheKey`/`ttl`, not nested inside
+ * `call`. Both positions used to typecheck, which meant `cachedCall`
+ * could only catch the mistake at runtime with a warning, after silently
+ * ignoring the caller's usage hooks. Putting them inside `call` as an
+ * inline object literal is now a compile error instead; TypeScript's
+ * excess-property check only applies to object literals though, so a
+ * preconstructed value carrying `reserveUsage`/`refundUsage` can still be
+ * structurally assignable, which is why `cachedCall` also checks for and
+ * rejects both hooks at runtime.
  */
 type CachedCallParams<T> = CachedCallInput & {
-  call: CallParams<T>;
+  call: Omit<CallParams<T>, 'reserveUsage' | 'refundUsage'>;
 };
 /**
  * Parameters for a cached LLM call with tool calling enabled.
@@ -697,9 +934,12 @@ type CachedCallParams<T> = CachedCallInput & {
  * The cached value includes the full `CallWithToolsResult<T>`, meaning
  * tool requests and normal content responses are cached exactly as returned
  * by the model.
+ *
+ * See `CachedCallParams` for why `reserveUsage`/`refundUsage` are omitted
+ * from `call`'s type here too.
  */
 type CachedToolCallParams<T> = CachedCallInput & {
-  call: ToolEnabledCallParams<T>;
+  call: Omit<ToolEnabledCallParams<T>, 'reserveUsage' | 'refundUsage'>;
 };
 
 //#endregion
@@ -810,9 +1050,12 @@ type WireStreamChunk = {
  * and a hit synthesizes a one-shot `chunks` replay from the cached value
  * (see `VernLLM.cachedCall`'s docs for exactly what that replay looks
  * like).
+ *
+ * `reserveUsage`/`refundUsage` are omitted from `call`'s type; see
+ * `CachedCallParams` for why — they belong at the top level here too.
  */
 type CachedStreamCallParams<T> = CachedCallInput & {
-  call: StreamEnabledCallParams<T>;
+  call: Omit<StreamEnabledCallParams<T>, 'reserveUsage' | 'refundUsage'>;
 };
 /**
  * Parameters for a cached, streaming LLM call with tool calling enabled.
@@ -822,7 +1065,7 @@ type CachedStreamCallParams<T> = CachedCallInput & {
  * replayed-chunks-on-hit behavior as `CachedStreamCallParams<T>`.
  */
 type CachedStreamToolCallParams<T> = CachedCallInput & {
-  call: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>;
+  call: Omit<StreamEnabledCallParams<T> & ToolEnabledCallParams<T>, 'reserveUsage' | 'refundUsage'>;
 };
 
 //#endregion
@@ -865,8 +1108,7 @@ type WireToolChoice = 'auto' | 'none' | 'required' | {
   };
 };
 /**
- * Minimal shape compatible with the OpenAI SDKs chat.completions.create,
- * so consumers can pass an OpenAI client directly
+ * Minimal shape similar to the OpenAI SDK's chat.completions.create API,
  * `response_format.json_schema` and `reasoning_effort` are optional on the wire
  * providers that don't support them will just ignore fields they don't recognize,
  * but not every SDKs TS types accept them, hence this being a structural type
@@ -1223,13 +1465,17 @@ declare class VernLLM {
    *
    * @param params System/user content plus per-call overrides. See `CallParams`.
    * @returns Without `tools` or `stream`: the parsed response, or raw
-   * string if `jsonMode` is false. With `tools`: a `CallWithToolsResult<T>`.
-   * With `stream: true` (statically): a `{ chunks, finalResult }`
+   * string if `jsonMode` is false. With `tools`: a `CallWithToolsResult<T>`,
+   * narrowed to `ContentResult<T>` when `toolChoice: 'none'` is set, since
+   * the model is then structurally barred from returning a `tool_calls`
+   * result. With `stream: true` (statically): a `{ chunks, finalResult }`
    * `StreamCallResult`, `finalResult` resolving to whichever of the above
    * shapes applies once the stream completes. See `StreamCallResult`.
    */
+  call<T = unknown>(params: StreamEnabledCallParams<T> & ToolsDisabledCallParams<T>): Promise<StreamCallResult<ContentResult<T>>>;
   call<T = unknown>(params: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
   call<T = unknown>(params: StreamEnabledCallParams<T>): Promise<StreamCallResult<T>>;
+  call<T = unknown>(params: ToolsDisabledCallParams<T>): Promise<ContentResult<T>>;
   call<T = unknown>(params: ToolEnabledCallParams<T>): Promise<CallWithToolsResult<T>>;
   call<T = unknown>(params: CallParams<T>): Promise<T>;
   /**
@@ -1281,26 +1527,41 @@ 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(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.
+   * @param target.index Which target to read. Defaults to the primary.
+   * @param target.model Which model bucket to read, if the target isolates by model.
+   * @returns The breaker state, or `undefined` if that target has no breaker.
+   * @throws {RangeError} If `target.index` names no target. Lets a real
+   * target with no breaker (`undefined`) stay distinguishable from a
+   * target that doesn't exist.
+   */
+  getCircuitState(target?: CircuitTarget): CircuitState | undefined;
+  /**
+   * @param model Which model bucket to read, for targets that isolate by model.
+   * @returns Every target's state, in chain order.
    */
   getCircuitStates(model?: string): TargetCircuitState[];
+  /**
+   * Manually opens a target's breaker, e.g. to pull a provider out of
+   * rotation ahead of known maintenance instead of waiting for it to fail.
+   *
+   * @param target.index Which target to open. Defaults to the primary.
+   * @param target.model Which model bucket to open, if the target isolates by model.
+   * @throws {RangeError} If `target.index` names no target.
+   */
+  openCircuit(target?: CircuitTarget): void;
+  /**
+   * Manually closes a target's breaker, e.g. once a provider is confirmed
+   * healthy again without waiting out the cooldown.
+   *
+   * @param target.index Which target to close. Defaults to the primary.
+   * @param target.model Which model bucket to close, if the target isolates by model.
+   * @throws {RangeError} If `target.index` names no target.
+   */
+  closeCircuit(target?: CircuitTarget): void;
+  /** Resolves a target index so every circuit-breaker method agrees on what counts as valid. */
+  private resolveExecutor;
+  /** Warns when `model` can't do anything on this target, so it's never silently ignored. */
+  private warnIfModelUnsupported;
 }
 
 //#endregion
@@ -1358,9 +1619,10 @@ type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
 //#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.
+ * Throws a non-retryable `LLMError('invalid_params')`, since an unsupported
+ * mimeType is a bug in the caller's own input, deterministic before any
+ * request is built, the same class of failure as every other check in
+ * `RequestBuilder`.
  */
 
 /**
@@ -2249,8 +2511,6 @@ declare const fromNvidiaNIM: typeof fromOpenAICompatible;
 declare const fromVercelAIGateway: typeof fromOpenAICompatible;
 /** Cloudflare Workers AI exposes an OpenAI-compatible endpoint */
 declare const fromCloudflareWorkersAI: typeof fromOpenAICompatible;
-/** GitHub Models is OpenAI-compatible */
-declare const fromGitHubModels: typeof fromOpenAICompatible;
 /** Nebius AI Studio is OpenAI-compatible */
 declare const fromNebius: typeof fromOpenAICompatible;
 /** SambaNova Cloud's API is OpenAI-compatible */
@@ -2277,8 +2537,6 @@ declare const fromSnowflakeCortex: typeof fromOpenAICompatible;
 declare const fromAnyscale: typeof fromOpenAICompatible;
 /** Lepton AI's inference API is OpenAI-compatible */
 declare const fromLepton: typeof fromOpenAICompatible;
-/** kluster.ai's inference API is OpenAI-compatible */
-declare const fromKlusterAI: typeof fromOpenAICompatible;
 /** Inference.net's API is OpenAI-compatible */
 declare const fromInferenceNet: typeof fromOpenAICompatible;
 /** Infermatic's API is OpenAI-compatible */
@@ -2291,5 +2549,5 @@ declare const from01AI: typeof fromOpenAICompatible;
 //#endregion
 //# sourceMappingURL=openaiCompatible.d.ts.map
 
-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, fromOpenAI, 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, CircuitTarget, ConsoleLogger, ContentBlock, ContentResult, ConversationTurn, DuplicateToolNamesIssue, FallbackAttempt, FallbackExhaustedError, FallbackOn, FallbackTarget, FetchAdapterConfig, GeminiClient, HistoryToolResultIssue, ImageBlock, InMemoryCacheAdapter, JsonSchemaSpec, LLMClient, LLMError, LLMErrorCode, LLMErrorIssuesByCode, LLMErrorSnapshot, LLMErrorType, Logger, NormalizedCacheAdapter, OnEvent, OnUsage, RateLimitAcquireResult, RateLimitOptions, RateLimitReason, RateLimiter, RefundUsage, ReserveUsage, RetryAttempt, SSE_PING, SchemaLike, StreamCallResult, StreamChunk, StreamEnabledCallParams, TargetCircuitState, TextBlock, TieredCacheAdapter, TokenUsage, ToolCall, ToolCallResult, ToolChoice, ToolDefinition, ToolEnabledCallParams, ToolIssue, ToolResult, ToolsDisabledCallParams, UnknownToolChoiceIssue, UnsupportedCapabilityIssue, 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, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAI, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, hasIssues, isFallbackExhaustedError, isLLMError, isToolCallResult, parseSseStream };
 //# sourceMappingURL=index.d.cts.map