vern-llm 1.7.0 → 2.0.0

package/dist/index.d.cts

@@ -110,8 +110,79 @@ interface JsonSchemaSpec {
 }
 
 //#endregion
-//#region src/types/usage.d.ts
+//#region src/types/tools.d.ts
 //# sourceMappingURL=schema.d.ts.map
+/**
+ * Describes a capability the model may request, not the capability
+ * itself. VernLLM transports this to the provider and parses what comes
+ * back; it never executes anything.
+ */
+interface ToolDefinition {
+  name: string;
+  description: string;
+  /** JSON Schema for the tool's input. */
+  parameters: Record<string, unknown>;
+  /**
+   * Optional client-side validator run on the parsed `arguments` before
+   * they're handed back to the caller, mirroring the `schema: SchemaLike<T>`
+   * pattern already used for response validation (see `types/schema.ts`).
+   * Reuses that zero-dependency, `safeParse`-compatible shape instead of
+   * requiring a JSON Schema validator (e.g. ajv) as a new dependency.
+   * Failed validation throws `LLMError('validation')`. If omitted, VernLLM
+   * parses arguments as JSON but does not validate them further.
+   */
+  argumentsSchema?: SchemaLike<unknown>;
+}
+/** A single tool invocation requested by the model. */
+interface ToolCall {
+  id: string;
+  name: string;
+  /** Parsed JSON arguments (and validated, if `argumentsSchema` was set). */
+  arguments: unknown;
+}
+/** The application's result of executing a `ToolCall`, sent back to the model. */
+interface ToolResult {
+  toolCallId: string;
+  content: unknown;
+  /**
+   * Signals a failed tool execution back to the model (matches Anthropic's
+   * native `is_error` on tool_result blocks). Only `fromAnthropic` honors
+   * this today, Gemini and Bedrock have no equivalent wire concept, so
+   * other adapters ignore it silently.
+   */
+  isError?: boolean;
+}
+/** `call()` result when `tools` was set and the model produced a normal answer. */
+interface ContentResult<T> {
+  type: 'content';
+  content: T;
+}
+/** `call()` result when `tools` was set and the model requested one or more tools. */
+interface ToolCallResult {
+  type: 'tool_calls';
+  toolCalls: ToolCall[];
+  /** Any text the model produced alongside the tool request, if present. */
+  content?: string;
+}
+type CallWithToolsResult<T> = ContentResult<T> | ToolCallResult;
+/**
+ * Runtime-safe check for whether a `call()` result is a `tool_calls`
+ * result. Prefer this over relying on TypeScript's static narrowing
+ * whenever `params` passed to `call()` wasn't a literal with `tools`
+ * inlined (see the "note on the overload" in `VernLLM.call`'s docs), in
+ * that case TS may have typed the result as plain `T` even though it's
+ * actually a `CallWithToolsResult<T>` at runtime, and this check works
+ * either way.
+ */
+declare function isToolCallResult(result: unknown): result is ToolCallResult;
+/** What the model should do about tools on a given call. */
+type ToolChoice = 'auto' | 'none' | 'required' | {
+  name: string;
+};
+
+//#endregion
+//#region src/types/usage.d.ts
+//# sourceMappingURL=tools.d.ts.map
 type ReserveUsage = (params: {
   coalesced: boolean;
   signal?: AbortSignal;
@@ -144,15 +215,39 @@ interface TokenUsage {
   model: string;
 }
 type OnUsage = (usage: TokenUsage) => void;
+/**
+ * Called when a provider response arrives but VernLLM's own post-processing
+ * then fails, after usage data was already present in that response. Covers
+ * any error thrown after usage extraction, not just parse/validation, since
+ * everything in that path only runs once a response, and real spend, has
+ * already arrived. Fires once per failed attempt with extractable usage,
+ * never for transport failures, where no response means no honest number
+ * to report.
+ */
+type OnUsageFailure = (usage: TokenUsage, error: LLMError) => void;
 
 //#endregion
 //#region src/types/call.d.ts
 //# sourceMappingURL=usage.d.ts.map
-/** A single prior turn in a multi-turn conversation, passed via `history`. */
-interface ConversationTurn {
-  role: 'user' | 'assistant';
+/**
+ * A single prior turn in a multi-turn conversation, passed via `history`.
+ *
+ * Supports normal user/assistant messages and tool continuations: an assistant
+ * turn may include `toolCalls`, and a tool turn carries the matching
+ * `toolResults`. A tool turn must immediately follow an assistant tool call
+ * turn, and every requested tool call must have a result.
+ */
+type ConversationTurn = {
+  role: 'user';
   content: string;
-}
+} | {
+  role: 'assistant';
+  content?: string;
+  toolCalls?: ToolCall[];
+} | {
+  role: 'tool';
+  toolResults: ToolResult[];
+};
 /** A plain text segment of a multimodal `userContent` array. */
 interface TextBlock {
   type: 'text';
@@ -180,15 +275,28 @@ interface CallParams<T = unknown> extends UsageHooks {
   /** Current user message, as text or multimodal content blocks. */
   userContent: string | ContentBlock[];
   /**
-   * Previous conversation turns. Must alternate user/assistant and end with
-   * an assistant turn; invalid history throws LLMError('validation').
+   * Previous conversation turns. Must alternate roles; tool turns must follow
+   * assistant tool calls. Invalid history throws LLMError('validation').
    */
   history?: ConversationTurn[];
-  temperature?: number;
+  /**
+   * Generation temperature. Default 0.2, not the provider's own default.
+   * Pass `null` to omit `temperature` from the request entirely, so the
+   * provider applies its own default instead.
+   */
+  temperature?: number | null;
   jsonMode?: boolean;
   maxTokens?: number;
   requestId?: string;
   signal?: AbortSignal;
+  /**
+   * Per-call override for the instance's `chunkIdleTimeoutMs` (max gap
+   * between stream chunks once opened). Only applies when `stream: true`.
+   * Useful for routes using reasoning-heavy models with documented long
+   * silent gaps mid-stream. Pass 0 to disable the idle timeout for this
+   * call.
+   */
+  chunkIdleTimeoutMs?: number;
   /** Overrides the instance model for this call. */
   model?: string;
   /** Reasoning effort for supported reasoning models. */
@@ -202,17 +310,233 @@ interface CallParams<T = unknown> extends UsageHooks {
    * Implies jsonMode: true.
    */
   schema?: SchemaLike<T>;
+  /**
+   * Tools the model may call. When set, `call()` always returns a
+   * `CallWithToolsResult<T>` discriminated union instead of `T` directly
+   * (see `CallWithToolsResult`), a breaking-change point: omitting `tools`
+   * keeps `call()`'s old `Promise<T>` behavior exactly.
+   *
+   * Mutually exclusive with `jsonSchema`/`schema`: on Anthropic and
+   * Bedrock, `jsonSchema` is implemented internally as a forced single-tool
+   * call, which would collide with real tools. Setting both throws
+   * `LLMError('validation')`.
+   */
+  tools?: ToolDefinition[];
+  /** Defaults to `'auto'` when `tools` is set. */
+  toolChoice?: ToolChoice;
+  /**
+   * Streams the response incrementally instead of resolving once. Default:
+   * false. Requires a client/adapter that implements `createStream`.
+   * Retry/timeout/circuit-breaker guarantees apply only to opening the
+   * stream (through the first chunk); a failure after that point rejects
+   * `finalResult` directly and is not retried, since a mid-stream failure
+   * isn't connection-time evidence for the circuit breaker, the attempt
+   * already counted as a success once the first chunk arrived. Once the
+   * stream opens successfully, `finalResult` still resolves to the same
+   * validated `T`/`CallWithToolsResult<T>` shape `call()` would have
+   * returned for the same params with `stream` omitted. See
+   * `StreamCallResult`.
+   */
+  stream?: boolean;
 }
-interface CachedCallParams<T> extends UsageHooks {
+/**
+ * A `CallParams` variant where tool calling is explicitly enabled.
+ *
+ * Requiring `tools` to be present allows TypeScript to select the
+ * tool-aware `call()` overload and return `CallWithToolsResult<T>` instead
+ * of the normal `T` response type.
+ */
+type ToolEnabledCallParams<T> = CallParams<T> & {
+  tools: NonNullable<CallParams<T>['tools']>;
+};
+/** Shared cache-configuration fields, minus the internal `fn` primitive. */
+interface CachedCallInput extends UsageHooks {
   cacheKey: string;
   ttl: number;
-  fn: () => Promise<T>;
   signal?: AbortSignal;
 }
+/**
+ * Parameters for a cached LLM call without tool calling.
+ *
+ * Combines the cache configuration with the `CallParams` passed to
+ * `VernLLM.call()`. The cached value is the normal LLM response type `T`.
+ */
+type CachedCallParams<T> = CachedCallInput & {
+  call: CallParams<T>;
+};
+/**
+ * Parameters for a cached LLM call with tool calling enabled.
+ *
+ * The cached value includes the full `CallWithToolsResult<T>`, meaning
+ * tool requests and normal content responses are cached exactly as returned
+ * by the model.
+ */
+type CachedToolCallParams<T> = CachedCallInput & {
+  call: ToolEnabledCallParams<T>;
+};
 
 //#endregion
-//#region src/types/client.d.ts
+//#region src/types/stream.d.ts
 //# sourceMappingURL=call.d.ts.map
+/** One incremental unit of a streaming response, as delivered to the caller. */
+type StreamChunk = {
+  type: 'text-delta';
+  delta: string;
+} | {
+  type: 'tool_call_delta';
+  index: number;
+  id?: string;
+  name?: string;
+  argsDelta?: string;
+  /**
+   * True when `argsDelta` is the whole set of arguments, not a
+   * fragment. Set for Gemini (its API returns function-call args
+   * whole in one chunk) and for cache/replay chunks, which are
+   * one-shot too. Omitted or `false` for a genuine fragment from
+   * providers that do stream incrementally (OpenAI-compatible,
+   * Anthropic, Bedrock).
+   */
+  complete?: boolean;
+} | {
+  type: 'usage';
+  usage: TokenUsage;
+};
+/**
+ * What `call()` returns when `stream: true`. `chunks` is for live rendering;
+ * `finalResult` resolves to the same validated `T`/`CallWithToolsResult<T>`
+ * shape `call()` would have returned had `stream` been omitted, once the
+ * stream completes successfully.
+ *
+ * `chunks` is single-use and supports only one consumer: iterating it more
+ * than once, or from more than one place concurrently, shares the same
+ * underlying buffered stream rather than replaying or forking it, which can
+ * split chunks unpredictably between consumers. Stopping iteration early
+ * (e.g. `break`ing out of a `for await`) does not cancel or otherwise
+ * signal the underlying stream, the background pump keeps running to
+ * completion regardless, buffering any chunks emitted after that point, so
+ * `finalResult` still settles normally even if `chunks` is abandoned or
+ * never read at all.
+ *
+ * Unread chunks are buffered internally for the duration of one stream,
+ * this is what lets a caller start iterating `chunks` after the stream has
+ * already progressed (or finished) and still see everything. That backlog
+ * is capped: an unusually large stream whose `chunks` is never read at all
+ * has its oldest buffered chunks dropped once the backlog grows past
+ * roughly twice a fixed internal limit, trimmed back down to that limit in
+ * one batch rather than one-at-a-time, bounding both peak memory and the
+ * eviction work itself for that pathological case instead of the array
+ * growing (or being trimmed) proportional to the whole stream's output.
+ * Ordinary consumption, even started somewhat late, stays far under the
+ * limit and is unaffected.
+ */
+interface StreamCallResult<R> {
+  chunks: AsyncIterable<StreamChunk>;
+  finalResult: Promise<R>;
+}
+/**
+ * A `CallParams` variant where streaming is explicitly enabled.
+ *
+ * Requiring `stream: true` to be statically present allows TypeScript to
+ * select the streaming `call()` overload and return `StreamCallResult<...>`
+ * instead of the normal, single-shot response type.
+ */
+type StreamEnabledCallParams<T> = CallParams<T> & {
+  stream: true;
+};
+/**
+ * The adapter-facing, pre-normalization shape a `createStream` client
+ * implementation emits, analogous to how `WireMessage`/`WireToolCall`
+ * already sit between `CallParams` and each provider's own wire format.
+ */
+type WireStreamChunk = {
+  type: 'text-delta';
+  delta: string;
+} | {
+  type: 'tool_call_delta';
+  index: number;
+  id?: string;
+  name?: string;
+  argumentsDelta?: string;
+  /** Same meaning as `StreamChunk`'s `tool_call_delta.complete`. */
+  complete?: boolean;
+} | {
+  type: 'usage';
+  usage: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+} | {
+  /**
+   * A provider keep-alive signal with no content of its own (e.g.
+   * Anthropic's `ping` events, an SSE comment-line heartbeat).
+   * Adapters yield this so the stream loop resets its idle timeout.
+   * Never surfaced to callers as a `StreamChunk`.
+   */
+  type: 'ping';
+};
+/**
+ * Parameters for a cached, streaming LLM call without tool calling.
+ *
+ * The cached value is `T`, same as `CachedCallParams<T>`, but a miss
+ * relays live `chunks` to the caller while the result is being generated,
+ * and a hit synthesizes a one-shot `chunks` replay from the cached value
+ * (see `VernLLM.cachedCall`'s docs for exactly what that replay looks
+ * like).
+ */
+type CachedStreamCallParams<T> = CachedCallInput & {
+  call: StreamEnabledCallParams<T>;
+};
+/**
+ * Parameters for a cached, streaming LLM call with tool calling enabled.
+ *
+ * The cached value is the full `CallWithToolsResult<T>`, same as
+ * `CachedToolCallParams<T>`, with the same live-chunks-on-miss,
+ * replayed-chunks-on-hit behavior as `CachedStreamCallParams<T>`.
+ */
+type CachedStreamToolCallParams<T> = CachedCallInput & {
+  call: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>;
+};
+
+//#endregion
+//#region src/types/client.d.ts
+//# sourceMappingURL=stream.d.ts.map
+/** A tool call as it appears on the wire, OpenAI's `function`-wrapped shape. */
+interface WireToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    /** JSON-encoded arguments, matching every OpenAI-compatible provider's wire format. */
+    arguments: string;
+  };
+}
+/** One entry of `LLMClient`'s `messages` array, named so callers building it can annotate against it. */
+type WireMessage = {
+  role: 'system';
+  content: string;
+} | {
+  role: 'user';
+  content: string | ContentBlock[];
+} | {
+  role: 'assistant';
+  /** Optional: an assistant turn that only requested tools has no text. */
+  content?: string;
+  tool_calls?: WireToolCall[];
+} | {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+  /** Only honored by `fromAnthropic` today (maps to `tool_result.is_error`); other adapters ignore it. */
+  is_error?: boolean;
+};
+/** The OpenAI-shaped wire `tool_choice`. */
+type WireToolChoice = 'auto' | 'none' | 'required' | {
+  type: 'function';
+  function: {
+    name: string;
+  };
+};
 /**
  * Minimal shape compatible with the OpenAI SDKs chat.completions.create,
  * so consumers can pass an OpenAI client directly
@@ -226,7 +550,7 @@ interface LLMClient {
     completions: {
       create(params: {
         model: string;
-        temperature: number;
+        temperature?: number;
         max_tokens: number;
         response_format?: {
           type: 'json_object';
@@ -241,19 +565,29 @@ interface LLMClient {
         };
         /** OpenAI reasoning-model param (o-series, gpt-5), ignored by providers that don't support it */
         reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
-        messages: Array<{
-          role: 'system' | 'assistant';
-          content: string;
-        } | {
-          role: 'user';
-          content: string | ContentBlock[];
+        /** Tools the model may call, OpenAI's `function`-wrapped shape. */
+        tools?: Array<{
+          type: 'function';
+          function: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+          };
         }>;
+        tool_choice?: WireToolChoice;
+        /**
+         * Wire-format messages. Breaking change for custom adapters:
+         * implementations must handle tool messages and assistant tool_calls.
+         * Exhaustive switches over only system/user/assistant roles may no longer compile.
+         */
+        messages: WireMessage[];
       }, options: {
         signal: AbortSignal;
       }): Promise<{
         choices?: Array<{
           message?: {
             content?: string | null;
+            tool_calls?: WireToolCall[];
           };
         }>;
         usage?: {
@@ -262,6 +596,15 @@ interface LLMClient {
           total_tokens?: number;
         };
       }>;
+      /**
+       * Optional. Required only for `stream: true` calls. Adapters/clients
+       * that don't implement this make `stream: true` throw a clear
+       * `LLMError('validation')` rather than a confusing runtime failure.
+       * Takes the same request shape as `create`, minus the response type.
+       */
+      createStream?(params: Parameters<LLMClient['chat']['completions']['create']>[0], options: {
+        signal: AbortSignal;
+      }): AsyncIterable<WireStreamChunk>;
     };
   };
 }
@@ -337,10 +680,26 @@ interface VernLLMOptions {
   maxRetries?: number;
   /** Per-attempt timeout in ms. Default 25000 */
   timeoutMs?: number;
+  /**
+   * For `stream: true` calls: max gap allowed between chunks once the
+   * stream has opened, in ms. Resets on every chunk, including keep-alive
+   * pings. `timeoutMs` only covers opening the stream and its first
+   * chunk; this covers every gap after that. Also counts as a
+   * circuit-breaker failure, unlike other mid-stream errors, since a
+   * provider that streams one chunk then stalls should still trip it.
+   * Default 30000. Pass 0 or negative to disable.
+   */
+  chunkIdleTimeoutMs?: number;
   /** Base delay for exponential backoff in ms. Default 500 */
   baseDelayMs?: number;
   /** Default max_tokens for calls that don't override it. Default 1000 */
   defaultMaxTokens?: number;
+  /**
+   * Default temperature for calls that don't override it. Default 0.2, not
+   * the provider's own default. Pass `null` to omit `temperature` from the
+   * request entirely, so the provider applies its own default instead.
+   */
+  defaultTemperature?: number | null;
   /** Enables debug logging of raw model output (logs up to 800 chars of each
    * response). Off by default */
   debug?: boolean;
@@ -352,6 +711,18 @@ interface VernLLMOptions {
   parseJson?: (content: string) => unknown;
   /** Called after every successful call with token usage, if the provider reports it */
   onUsage?: OnUsage;
+  /**
+   * Called when a provider response arrives but VernLLM's own post-processing
+   * then fails, after usage data was already present in that response.
+   * Separate from `onUsage`, which only fires on full success.
+   *
+   * For non-streaming calls, never fires for transport failures (timeout,
+   * network error, non-retryable status), since no response means no usage
+   * to report. For streaming calls, this is not guaranteed: a stream can
+   * deliver a usage chunk and then fail later (e.g. an idle timeout waiting
+   * for the final close), in which case this does fire.
+   */
+  onUsageFailure?: OnUsageFailure;
   /** Injectable logger. Defaults to a console-based logger gated by `debug` */
   logger?: Logger;
   /**
@@ -366,31 +737,34 @@ interface VernLLMOptions {
 //#region src/vernLLM.d.ts
 //# sourceMappingURL=options.d.ts.map
 /**
- * A resilient layer around an LLM chat completions client, this is VernLLM!
+ * A resilient layer around an LLM chat completions client. This is VernLLM!
  *
- * Adds retry with backoff/jitter, per-attempt timeouts, an optional circuit breaker,
- * JSON parsing with optional schema validation, usage tracking, and an
- * optional response cache, all configurable, all opt-in beyond sensible
- * defaults.
+ * Adds retry with backoff and jitter, per-attempt timeouts, an optional
+ * circuit breaker, JSON parsing with optional schema validation, usage
+ * tracking, and an optional response cache. All configurable, all opt-in
+ * beyond sensible defaults.
  */
 declare class VernLLM {
   private readonly client;
   private readonly model;
   private readonly maxRetries;
   private readonly timeoutMs;
+  private readonly chunkIdleTimeoutMs;
   private readonly baseDelayMs;
   private readonly defaultMaxTokens;
+  private readonly defaultTemperature;
   private readonly cache;
   private readonly nonRetryableStatus;
   private readonly inFlight;
   private readonly parseJson;
   private readonly onUsage?;
+  private readonly onUsageFailure?;
   private readonly logger;
   private readonly breaker?;
   /**
-   * @param options - Client, model, and tunables. Notable defaults:
-   * `maxRetries` 1, `timeoutMs` 25000, `baseDelayMs` 500 (exponential backoff
-   * base), `defaultMaxTokens` 1000, `cache` an in-memory adapter,
+   * @param options Client, model, and tunables. Defaults: `maxRetries` 1,
+   * `timeoutMs` 25000, `baseDelayMs` 500, `defaultMaxTokens` 1000,
+   * `defaultTemperature` 0.2, `cache` an in-memory adapter,
    * `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
    */
   constructor(options: VernLLMOptions);
@@ -399,23 +773,103 @@ declare class VernLLM {
   /**
    * Makes a single logical LLM call, retrying on failure per the configured
    * policy. Fails fast if the breaker is open or the signal is already
-   * aborted. On exhausting retries, records a breaker failure and rejects
-   * with a normalized LLMError.
+   * aborted. Rejects with a normalized LLMError on exhausted retries.
+   *
+   * When `tools` is set, returns a `CallWithToolsResult<T>` instead of `T`:
+   * `{ type: 'content', content }` or `{ type: 'tool_calls', toolCalls,
+   * content? }`. VernLLM never executes tools; run them yourself and
+   * continue via `history` (see `ConversationTurn`). Mutually exclusive
+   * with `jsonSchema`/`schema`.
+   *
+   * TypeScript only picks the tools-aware overload when `tools` is
+   * statically present on `params`. If set conditionally on a plain
+   * `CallParams<T>`, use `isToolCallResult()` to check the shape at
+   * runtime instead. See the Tool Calling docs for details.
    *
-   * @param params - System/user content plus per-call overrides (model,
-   * temperature, jsonMode, schema, signal, etc). See `CallParams`.
-   * @returns The parsed (and optionally schema-validated) response, or the
-   * raw string content when `jsonMode` is false and no `jsonSchema` is set.
+   * The same static-vs-dynamic caveat applies to `stream`: TypeScript only
+   * selects the streaming overload (returning `StreamCallResult<...>`) when
+   * `stream: true` is statically present on `params`. A `stream` value set
+   * conditionally on a plain `CallParams<T>` still resolves to `Promise<T>`
+   * (or `Promise<CallWithToolsResult<T>>`) at the type level even though
+   * the actual runtime result is the `{ chunks, finalResult }` streaming
+   * shape whenever `stream` evaluates to `true`, callers doing this should
+   * narrow/cast accordingly rather than relying on the static return type.
+   *
+   * @param params System/user content plus per-call overrides. See `CallParams`.
+   * @returns Without `tools` or `stream`: the parsed response, or raw
+   * string if `jsonMode` is false. With `tools`: a `CallWithToolsResult<T>`.
+   * With `stream: true` (statically): a `{ chunks, finalResult }`
+   * `StreamCallResult`, `finalResult` resolving to whichever of the above
+   * shapes applies once the stream completes. See `StreamCallResult`.
    */
+  call<T = unknown>(params: StreamEnabledCallParams<T> & ToolEnabledCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
+  call<T = unknown>(params: StreamEnabledCallParams<T>): Promise<StreamCallResult<T>>;
+  call<T = unknown>(params: ToolEnabledCallParams<T>): Promise<CallWithToolsResult<T>>;
   call<T = unknown>(params: CallParams<T>): Promise<T>;
-  /** Runs `fn`, retrying with backoff according to `shouldRetry`. */
-  private retryWithBackoff;
   /**
-   * Performs a single attempt: builds the request, dispatches it with a
-   * timeout, and shapes the response. Throws on an empty response so the
+   * Performs a single attempt: builds the request (translating `tools` to
+   * wire shape when present), dispatches it with a timeout, and shapes the
+   * response into `T` or a `CallWithToolsResult<T>` when `params.tools` was
+   * set. Throws on an empty response (no text and no tool_calls) so the
    * retry loop treats it like any other transient failure.
    */
   private executeCall;
+  /**
+   * Shapes a fully-arrived response (content and/or tool_calls, already
+   * extracted from the provider's payload) into `T` or a
+   * `CallWithToolsResult<T>`. Reused by the streaming path once it has
+   * buffered the full text/tool-call deltas, so there's no separate
+   * parsing/validation logic for streaming.
+   *
+   * Normalizes and reports usage failure on error itself, so every caller
+   * gets identical error handling without duplicating it.
+   */
+  private finalizeResponse;
+  /**
+   * Opens a stream for a single attempt: builds the request exactly like
+   * `executeCall`, then requires `createStream` on the client (a clear
+   * `validation` error if the adapter doesn't support it). The timeout
+   * wraps stream construction and the first `.next()` together, not just
+   * construction: calling an `async function*` returns an iterator
+   * synchronously without running its body until `.next()` is first
+   * invoked, so timing only construction would time an operation that's
+   * always instant, not the actual connection. Both are folded into a
+   * single `withTimeout` so the same abort signal reaches whatever the
+   * adapter's `createStream` uses internally for its first network
+   * round-trip.
+   *
+   * Circuit-breaker success is recorded once the stream fully completes,
+   * not on the first chunk arriving, so a connection that opens but then
+   * dies mid-stream isn't masked as a success (see `buildStreamResult`).
+   */
+  private executeStreamCall;
+  /**
+   * The streaming accumulator: wraps the raw `WireStreamChunk` iterator in
+   * an async generator that yields translated `StreamChunk`s to the caller
+   * live, as they arrive, with no per-chunk timeout and no bound on total
+   * duration, and accumulates text/tool-call deltas internally so that
+   * `finalizeResponse` can produce `finalResult` once the stream completes.
+   *
+   * Two separate try/catches: the iteration loop's catch handles errors
+   * the transport itself throws, which aren't normalized yet, so that
+   * happens here along with the one `reportUsageFailure` call for them.
+   * The second catch, around `finalizeResponse`, does not re-normalize or
+   * re-report since `finalizeResponse` already does both internally.
+   * Circuit-breaker success is only recorded once the stream fully
+   * completes, not when the first chunk arrives, so a connection that
+   * opens and then dies mid-way still counts as a failure below instead
+   * of masking it.
+   */
+  private buildStreamResult;
+  /**
+   * Checks every `ToolCall` against the `tools` that were offered, catching
+   * a hallucinated tool name early instead of letting it reach the
+   * application's dispatch table. Then runs each tool's `argumentsSchema`,
+   * if present, throwing `LLMError('validation')` on failure.
+   */
+  private validateToolCallArguments;
+  /** Runs `fn`, retrying with backoff according to `shouldRetry`. */
+  private retryWithBackoff;
   /**
    * Validates `history` alternates user/assistant turns, since providers
    * like Anthropic/Gemini reject or mishandle consecutive same-role turns.
@@ -423,6 +877,16 @@ declare class VernLLM {
   private validateHistory;
   /** Applies per-call defaults and shapes params into the client's request object. */
   private buildRequestPayload;
+  /** Maps VernLLM's app-facing `ToolChoice` onto the OpenAI-shaped wire `tool_choice`. */
+  private buildWireToolChoice;
+  /**
+   * Expands one `ConversationTurn` into one or more wire messages. Plain
+   * user/assistant turns map 1:1. An assistant turn with `toolCalls` maps
+   * to an assistant message carrying wire-shaped `tool_calls`. A `'tool'`
+   * turn expands into one wire `tool` message per `toolResult`, since
+   * OpenAI-shaped wire format wants one message per tool_call_id.
+   */
+  private turnToWireMessages;
   /**
    * Chooses the response format: a provider-native `jsonSchema` takes
    * priority when supplied (constrains generation directly), otherwise
@@ -430,8 +894,23 @@ declare class VernLLM {
    * requested, or no format at all for plain text responses.
    */
   private buildResponseFormat;
-  /** Reports token usage to `onUsage`, swallowing and logging any error it throws. */
-  private recordUsage;
+  /**
+   * Pulls `TokenUsage` out of a raw response, if the provider reported it.
+   * Extraction doesn't depend on what happens to the response afterward, so
+   * a malformed body can still yield usage if the provider's usage block
+   * itself came through intact.
+   */
+  private extractUsage;
+  /** Reports token usage for a successful call, swallowing and logging any error `onUsage` throws. */
+  private reportUsage;
+  /**
+   * Reports token usage spent on an attempt that then failed, so it isn't
+   * dropped alongside the error. Covers any error thrown after usage
+   * extraction, since all of them happen only after a response (real
+   * spend) already arrived. Swallows and logs any error `onUsageFailure`
+   * itself throws.
+   */
+  private reportUsageFailure;
   /** Parses response content as JSON and validates it against `schema` when supplied. */
   private parseAndValidate;
   /**
@@ -448,38 +927,97 @@ declare class VernLLM {
    * supports deletion. Cache invalidation is the caller's responsibility;
    * only the application knows when cached data is stale.
    *
-   * @param key - The raw cache key (resolved through the adapter's
+   * @param key The raw cache key (resolved through the adapter's
    * `resolveKey`, if any, before deletion).
    */
   deleteCache(key: string): Promise<void>;
   /**
-   * Cache wrapper around caller-supplied logic. Concurrent misses for the
-   * same `cacheKey` share a single in-flight call, avoiding cache stampedes.
+   * Internal cache primitive around caller-supplied logic. Concurrent misses
+   * for the same `cacheKey` share a single in-flight call, avoiding cache
+   * stampedes.
+   *
+   * Not part of the public API. Backs the public `cachedCall()`, which
+   * always composes this with `call()` so cached results get the same
+   * retry/timeout/circuit-breaker guarantees as any other LLM call.
    *
-   * @param params - `cacheKey`, `ttl`, `fn` (the work to run on a cache
+   * @param params `cacheKey`, `ttl`, `fn` (the work to run on a cache
    * miss, typically `() => this.call(...)`), and optional
-   * `reserveUsage`/`refundUsage`/`signal`. See `CachedCallParams`.
+   * `reserveUsage`/`refundUsage`/`signal`. See `InternalCacheParams`.
    * @returns The cached value on a hit, or the result of `fn()` on a miss.
    */
-  cachedCall<T>(params: CachedCallParams<T>): Promise<T>;
+  private runCached;
   /** Starts the shared fn() call for a cache miss and tracks it in the in-flight map until it settles. */
   private registerTrigger;
   /** Runs `fn` and writes its result to the cache. */
   private runAndCache;
+  /**
+   * Streaming counterpart to `runCached`. Three cases:
+   *
+   * - Hit: no live generation to relay. Returns immediately with
+   *   `finalResult` resolved to the cached value and a one-shot `chunks`
+   *   replay built from it, so `for await (const c of chunks)` call sites
+   *   work identically on a hit or a miss. No usage hooks fire, since
+   *   nothing was actually spent.
+   * - Miss, nothing else in flight for this key: delegates to
+   *   `registerStreamTrigger`, which opens the stream and relays its
+   *   `chunks` live.
+   * - Miss, but another call for the same key is already in flight: this
+   *   call has no live chunks of its own to relay, so it's treated like a
+   *   delayed hit. `finalResult` shares the trigger's in-flight promise
+   *   (the same `this.inFlight` map non-streaming `runCached` uses, so
+   *   streaming and non-streaming `cachedCall`s for the same key coalesce
+   *   against each other too), and `chunks` is a one-shot replay built
+   *   once that promise resolves.
+   */
+  private runCachedStream;
+  /**
+   * Opens the shared stream for a cache miss and tracks its settled value
+   * in `this.inFlight` until it resolves or rejects. Writes to the cache
+   * on success only, matching `runAndCache`.
+   *
+   * Registers the in-flight promise synchronously, before anything async
+   * runs, so a concurrent `cachedCall` for the same key always sees it in
+   * time to join instead of triggering its own stream. Settlement is
+   * wired onto the whole `withReservedUsageForStream` call rather than a
+   * line inside its callback, so any failure point (reserving usage,
+   * opening the stream, or the stream itself) reliably settles the
+   * in-flight entry instead of leaving it stuck.
+   */
+  private registerStreamTrigger;
   /** Logs a failed refundUsage attempt via the configured logger. */
   private logRefundError;
   /**
-   * Convenience wrapper composing `call` + `cachedCall`, so cached LLM calls
+   * Cache wrapper composing `call` + caching, so cached LLM calls
    * automatically get retry/timeout/circuit-breaker behavior. `reserveUsage`/
-   * `refundUsage` are read from the top-level params only.
+   * `refundUsage` are read from the top-level params only. Concurrent misses
+   * for the same `cacheKey` share a single in-flight call, avoiding cache
+   * stampedes. Supports `stream: true` and `tools` in any combination.
+   *
+   * When `call.tools` is set, this caches the whole `CallWithToolsResult`,
+   * including `tool_calls` results, not just final answers. Whether
+   * that's appropriate depends on the tool: caching "the model decided to
+   * call get_weather" is usually fine to reuse briefly, but caching a
+   * decision made under permissions or account state that can change
+   * between calls is not. Use a short `ttl` or a separate `cacheKey` for
+   * such tools if this distinction matters.
+   *
+   * There is no public way to cache an arbitrary non-LLM function through
+   * `VernLLM`. This method always composes with `call()`. For
+   * general-purpose caching unrelated to an LLM call, use a dedicated
+   * caching library at the application level instead.
    *
-   * @param params - `cachedCall` params (`cacheKey`, `ttl`, etc, minus `fn`)
-   * plus `call`, the `CallParams` to pass through to `this.call(...)`.
+   * @param params `cacheKey`, `ttl`, and optional
+   * `reserveUsage`/`refundUsage`/`signal`, plus `call`, the `CallParams`
+   * (optionally with `tools` and/or `stream`) to pass through to
+   * `this.call(...)`. The top-level `signal` governs the cached operation
+   * and its usage hooks only; to also abort the underlying provider
+   * request, set `signal` inside `call`.
    * @returns The cached value on a hit, or the freshly-called result on a miss.
    */
-  cachedLLMCall<T>(params: Omit<CachedCallParams<T>, 'fn'> & {
-    call: CallParams<T>;
-  }): Promise<T>;
+  cachedCall<T>(params: CachedStreamToolCallParams<T>): Promise<StreamCallResult<CallWithToolsResult<T>>>;
+  cachedCall<T>(params: CachedStreamCallParams<T>): Promise<StreamCallResult<T>>;
+  cachedCall<T>(params: CachedToolCallParams<T>): Promise<CallWithToolsResult<T>>;
+  cachedCall<T>(params: CachedCallParams<T>): Promise<T>;
   /**
    * @returns The current circuit breaker state (`'closed' | 'open' |
    * 'half-open'`), or undefined if no circuit breaker was configured.
@@ -488,8 +1026,64 @@ declare class VernLLM {
 }
 
 //#endregion
-//#region src/adapters/anthropic.d.ts
+//#region src/internal/sse.d.ts
 //# sourceMappingURL=vernLLM.d.ts.map
+/**
+ * Parses a Server-Sent-Events byte/text stream into the JSON payload of
+ * each `data:` frame, in arrival order. Generic over transport: works with
+ * anything that hands back progressively-arriving `Uint8Array` or `string`
+ * chunks via async iteration: native `fetch`'s `response.body` (wrapped
+ * to be iterable, see `webStreamToAsyncIterable` in `fetch.ts`), axios's
+ * Node `Readable` (already async-iterable, no wrapping needed), etc, so
+ * this framing layer doesn't care which transport produced the bytes.
+ *
+ * Follows the SSE spec's frame-delimiting rules closely enough for LLM
+ * streaming responses: frames are separated by a blank line, each frame
+ * may carry one or more `data:` lines (joined with `\n` per spec when
+ * there's more than one), `:`-prefixed lines are comments and ignored, and
+ * other SSE fields (`event:`, `id:`, `retry:`) are ignored since VernLLM
+ * only needs the payload. A frame whose data is exactly `[DONE]` (the
+ * sentinel several providers, notably OpenAI, send to mark stream end)
+ * ends iteration without yielding it.
+ *
+ * Line endings: `\r\n` and bare `\r` (both legal per the SSE spec, alongside `\n`) are normalized
+ * to `\n` before frame splitting. A `\r` at the very end of the currently-buffered text is left
+ * alone until either more text arrives (in case it's the first half of a split `\r\n` pair) or the
+ * stream ends, so a `\r\n` pair split across two transport chunks is never misread as two blank
+ * lines.
+ *
+ * Malformed JSON in a frame throws `LLMError('parse')`, consistent with
+ * how malformed JSON is handled elsewhere in VernLLM.
+ */
+declare function parseSseStream(source: AsyncIterable<Uint8Array | string>): AsyncGenerator<unknown>;
+/**
+ * Sentinel yielded by `parseSseStream` for a comment-only frame (no
+ * `data:` payload), the mechanism providers use for SSE keep-alive
+ * pings. Exported so a consumer (e.g. `fromFetch`) can react to "still
+ * alive" separately from a genuinely empty frame (`NO_DATA`, kept internal).
+ */
+declare const SSE_PING: unique symbol;
+
+//#endregion
+//#region src/internal/imageFormat.d.ts
+//# sourceMappingURL=sse.d.ts.map
+/**
+ * MIME types accepted for `ImageBlock.mimeType` across all adapters. This is
+ * the intersection of what Anthropic, Gemini, OpenAI-compatible, and Bedrock
+ * Converse all natively support, so a `ContentBlock[]` that validates for
+ * one provider validates for all of them.
+ */
+declare const SUPPORTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+type SupportedImageMimeType = (typeof SUPPORTED_IMAGE_MIME_TYPES)[number];
+
+//#endregion
+//#region src/adapters/anthropic.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.
+ */
 /** Anthropic's native per-block content shape for a message. */
 type AnthropicContentBlock = {
   type: 'text';
@@ -498,9 +1092,19 @@ type AnthropicContentBlock = {
   type: 'image';
   source: {
     type: 'base64';
-    media_type: string;
+    media_type: SupportedImageMimeType;
     data: string;
   };
+} | {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: unknown;
+} | {
+  type: 'tool_result';
+  tool_use_id: string;
+  content: string;
+  is_error?: boolean;
 };
 /** Minimal structural type for the Anthropic SDK's `messages.create` */
 interface AnthropicClient {
@@ -517,10 +1121,19 @@ interface AnthropicClient {
       tools?: Array<{
         name: string;
         description?: string;
-        input_schema: Record<string, unknown>;
+        input_schema: {
+          type: 'object';
+          [key: string]: unknown;
+        };
         strict?: boolean;
       }>;
       tool_choice?: {
+        type: 'auto';
+      } | {
+        type: 'any';
+      } | {
+        type: 'none';
+      } | {
         type: 'tool';
         name: string;
       };
@@ -530,6 +1143,7 @@ interface AnthropicClient {
       content: Array<{
         type: string;
         text?: string;
+        id?: string;
         name?: string;
         input?: unknown;
       }>;
@@ -566,13 +1180,30 @@ type GeminiPart = {
     mimeType: string;
     data: string;
   };
+} | {
+  functionCall: {
+    name: string;
+    args: unknown;
+  };
+} | {
+  functionResponse: {
+    name: string;
+    response: unknown;
+  };
 };
 /**
- * Minimal structural type for VernLLM's two-argument wrapper around Gemini
- * `generateContent`. The wrapper exposes a request shape aligned with the
- * adapter interface, with top-level `systemInstruction` and
- * `generationConfig` fields, while transport options (such as `AbortSignal`)
- * are passed separately as the second argument.
+ * Structural type matching the real `@google/genai` SDK's `ai.models`
+ * object: `generateContent`/`generateContentStream` both take a single
+ * `{ model, contents, config }` argument (config carries
+ * `systemInstruction`, `tools`, `toolConfig`, generation settings, and
+ * `abortSignal` all together), matching the real SDK closely enough that
+ * `fromGemini(ai.models)` works directly, e.g:
+ *
+ * ```ts
+ * import { GoogleGenAI } from '@google/genai';
+ * const ai = new GoogleGenAI({ apiKey: '...' });
+ * const llm = new VernLLM({ client: fromGemini(ai.models), model: 'gemini-2.5-flash' });
+ * ```
  */
 interface GeminiClient {
   generateContent(params: {
@@ -581,24 +1212,40 @@ interface GeminiClient {
       role: 'user' | 'model';
       parts: GeminiPart[];
     }>;
-    systemInstruction?: {
-      parts: Array<{
-        text: string;
-      }>;
-    };
-    generationConfig?: {
+    config?: {
+      systemInstruction?: {
+        parts: Array<{
+          text: string;
+        }>;
+      };
       temperature?: number;
       maxOutputTokens?: number;
       responseMimeType?: string;
       responseSchema?: Record<string, unknown>;
+      tools?: Array<{
+        functionDeclarations: Array<{
+          name: string;
+          description?: string;
+          parameters: Record<string, unknown>;
+        }>;
+      }>;
+      toolConfig?: {
+        functionCallingConfig: {
+          mode: 'AUTO' | 'ANY' | 'NONE';
+          allowedFunctionNames?: string[];
+        };
+      };
+      abortSignal?: AbortSignal;
     };
-  }, options: {
-    signal: AbortSignal;
   }): Promise<{
     candidates?: Array<{
       content?: {
         parts?: Array<{
           text?: string;
+          functionCall?: {
+            name: string;
+            args: unknown;
+          };
         }>;
       };
     }>;
@@ -608,6 +1255,32 @@ interface GeminiClient {
       totalTokenCount?: number;
     };
   }>;
+  /**
+   * Optional. Required only for `stream: true` calls. Takes the same
+   * request shape as `generateContent`. Matching the real SDK's own
+   * `generateContentStream`, this resolves to an `AsyncIterable` (rather
+   * than returning one synchronously) of partial responses, each chunk
+   * holding the same `candidates[].content.parts[]` structure as
+   * `generateContent`'s response, just incremental.
+   */
+  generateContentStream?(params: Parameters<GeminiClient['generateContent']>[0]): Promise<AsyncIterable<{
+    candidates?: Array<{
+      content?: {
+        parts?: Array<{
+          text?: string;
+          functionCall?: {
+            name: string;
+            args: unknown;
+          };
+        }>;
+      };
+    }>;
+    usageMetadata?: {
+      promptTokenCount?: number;
+      candidatesTokenCount?: number;
+      totalTokenCount?: number;
+    };
+  }>>;
 }
 /**
  * Wraps a Gemini client so it satisfies the `LLMClient` interface VernLLM
@@ -619,6 +1292,25 @@ interface GeminiClient {
  * `responseSchema`. `reasoning_effort` has no equivalent. Gemini's thinking
  * models use a token budget, not an effort tier, so it's dropped, same as
  * Anthropic.
+ *
+ * `tools` maps to Gemini's native `functionDeclarations`/`functionCall`;
+ * `tool_choice` maps to `toolConfig.functionCallingConfig`. `jsonSchema`
+ * and `tools` are mutually exclusive by the time a call reaches here
+ * (enforced in vernLLM.ts), so `responseSchema` and `tools` never
+ * both apply.
+ *
+ * `createStream` calls `generateContentStream` (optional on `GeminiClient`
+ *, required only if the caller sets `stream: true`) and translates each
+ * partial response into `WireStreamChunk`s. Unlike OpenAI/Anthropic,
+ * Gemini's own function-calling API doesn't stream tool-call arguments
+ * incrementally: a `functionCall` part always arrives whole in one chunk,
+ * so each one is emitted as a single, complete `tool_call_delta` (a
+ * one-shot "delta" containing the full arguments) rather than accumulated
+ * fragments, that's a real difference in the underlying API, not
+ * something this adapter can smooth over. `usageMetadata` is (per Gemini's
+ * own behavior) only reliably present on the last chunk, so the `usage`
+ * `WireStreamChunk` is emitted once, after the stream completes, from
+ * whichever chunk's `usageMetadata` was seen last.
  */
 declare function fromGemini(geminiClient: GeminiClient): LLMClient;
 
@@ -636,6 +1328,20 @@ type BedrockContentBlock = {
       bytes: Uint8Array;
     };
   };
+} | {
+  toolUse: {
+    toolUseId: string;
+    name: string;
+    input: unknown;
+  };
+} | {
+  toolResult: {
+    toolUseId: string;
+    content: Array<{
+      text: string;
+    }>;
+    status?: 'success' | 'error';
+  };
 };
 /**
  * Minimal structural type matching AWS Bedrock's Converse API. This is
@@ -682,6 +1388,10 @@ interface BedrockConverseClient {
         tool: {
           name: string;
         };
+      } | {
+        auto: Record<string, never>;
+      } | {
+        any: Record<string, never>;
       };
     };
   }, options: {
@@ -692,6 +1402,7 @@ interface BedrockConverseClient {
         content?: Array<{
           text?: string;
           toolUse?: {
+            toolUseId?: string;
             name?: string;
             input?: unknown;
           };
@@ -704,7 +1415,89 @@ interface BedrockConverseClient {
       totalTokens?: number;
     };
   }>;
+  /**
+   * Optional. Required only for `stream: true` calls. Takes the same
+   * request shape `converse` does, returning `{ stream }`, matching
+   * `ConverseStreamCommand`'s real AWS SDK v3 output shape, an
+   * `AsyncIterable` of incremental events under a `stream` property,
+   * rather than the whole response being the iterable directly.
+   */
+  converseStream?(params: Parameters<BedrockConverseClient['converse']>[0], options: {
+    signal: AbortSignal;
+  }): Promise<{
+    stream: AsyncIterable<BedrockConverseStreamEvent>;
+  }>;
 }
+/**
+ * One event of a Bedrock `ConverseStreamCommand` response's `stream`.
+ * Content blocks (text or toolUse) are identified by `contentBlockIndex`,
+ * Converse's own convention for correlating start/delta/stop events across
+ * possibly-interleaved blocks, mirrored directly by VernLLM's
+ * `tool_call_delta.index`.
+ */
+type BedrockConverseStreamEvent = {
+  messageStart: {
+    role: 'assistant';
+  };
+} | {
+  contentBlockStart: {
+    contentBlockIndex: number;
+    start?: {
+      toolUse?: {
+        toolUseId?: string;
+        name?: string;
+      };
+    };
+  };
+} | {
+  contentBlockDelta: {
+    contentBlockIndex: number;
+    delta?: {
+      text?: string;
+    } | {
+      toolUse?: {
+        input?: string;
+      };
+    };
+  };
+} | {
+  contentBlockStop: {
+    contentBlockIndex: number;
+  };
+} | {
+  messageStop: {
+    stopReason?: string;
+  };
+} | {
+  metadata: {
+    usage?: {
+      inputTokens?: number;
+      outputTokens?: number;
+      totalTokens?: number;
+    };
+  };
+} | {
+  internalServerException: {
+    message?: string;
+  };
+} | {
+  modelStreamErrorException: {
+    message?: string;
+    originalStatusCode?: number;
+  };
+} | {
+  validationException: {
+    message?: string;
+  };
+} | {
+  throttlingException: {
+    message?: string;
+  };
+} | {
+  serviceUnavailableException: {
+    message?: string;
+  };
+};
 /**
  * Optional configuration for `fromBedrock`.
  */
@@ -743,6 +1536,22 @@ interface BedrockAdapterOptions {
  * `response_format: json_object` (no schema to build a tool from) and
  * `reasoning_effort` (no Converse equivalent) fall back to a system-prompt
  * instruction and are dropped respectively.
+ *
+ * `tools` maps to Converse's native `toolConfig`/`toolUse`/`toolResult`;
+ * `tool_choice` maps to `toolConfig.toolChoice`. Mutually exclusive with
+ * `jsonSchema` by the time a call reaches here (enforced in vernLLM.ts).
+ *
+ * `createStream` calls `converseStream` (optional on `BedrockConverseClient`
+ *, required only if the caller sets `stream: true`) and translates its
+ * `contentBlockStart`/`contentBlockDelta`/`metadata` events into
+ * `WireStreamChunk`s. Content blocks are tracked by `contentBlockIndex`,
+ * same as `fromAnthropic`'s block-index tracking (Converse's streaming
+ * shape is structurally close to Anthropic's own, both being tool-use-aware
+ * content-block streams), including the same `json-tool` unwrapping: a
+ * `jsonSchema`-forced tool's `toolUse.input` deltas are re-emitted as
+ * `text-delta`, not `tool_call_delta`, so the accumulated result lands in
+ * `finalizeResponse`'s `content` path exactly like the non-streaming
+ * `create` branch above unwraps it.
  */
 declare function fromBedrock(bedrockClient: BedrockConverseClient, options?: BedrockAdapterOptions): LLMClient;
 
@@ -772,6 +1581,22 @@ type RequestLike = (url: string, init: {
   body?: string;
   signal?: AbortSignal;
 }) => Promise<ResponseLike>;
+/**
+ * A streaming-capable request function. Unlike `RequestLike`, which returns
+ * a fully-buffered `ResponseLike`, this resolves to an `AsyncIterable` of
+ * progressively-arriving chunks, the common ground across transports:
+ * native `fetch`'s `response.body` (wrapped to be iterable; see
+ * `webStreamToAsyncIterable` below), axios's Node `Readable` in
+ * `responseType: 'stream'` mode (already async-iterable, no wrapping
+ * needed), `node-fetch`, `undici`, etc, all satisfy this with little or no
+ * glue code. Defaults to native `fetch`.
+ */
+type StreamRequestLike = (url: string, init: {
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  signal?: AbortSignal;
+}) => Promise<AsyncIterable<Uint8Array | string>>;
 interface FetchAdapterConfig {
   /** Endpoint URL, or a function of the request in case it depends on model/params */
   url: string | ((params: ChatRequest) => string);
@@ -788,17 +1613,65 @@ interface FetchAdapterConfig {
   /** Maps VernLLMs internal chat-completion request into the providers raw request body */
   mapRequest: (params: ChatRequest) => unknown;
   /**
-   * Maps the providers raw JSON response into `{ content, usage? }`
-   * `content` is the assistants text (JSON string when JSON mode was requested)
+   * Maps the providers raw JSON response into `{ content, usage?, toolCalls? }`
+   * `content` is the assistants text (JSON string when JSON mode was requested).
+   * `content` may be empty/omitted when the model responded with only tool
+   * calls and no text.
+   *
+   * `toolCalls`, when the model requested one or more tools, is the list of
+   * calls as flat `{ id, name, arguments }` entries (matching this config's
+   * own `toolCalls?: Array<{ id: string; name: string; arguments: string }>`
+   * return type below), each entry's `arguments` already JSON-*encoded* as a
+   * string (not the parsed object), mirroring the wire format every
+   * OpenAI-compatible provider uses. `fromFetch` itself converts these into
+   * `WireToolCall`'s `type`/`function`-wrapped shape before returning them
+   * from `create`. VernLLM parses (and validates, if `argumentsSchema` was
+   * set) the arguments string internally, mapResponse doesn't need to do
+   * that itself.
    */
   mapResponse: (json: unknown) => {
-    content: string;
+    content?: string;
     usage?: {
       promptTokens?: number;
       completionTokens?: number;
       totalTokens?: number;
     };
+    toolCalls?: Array<{
+      id: string;
+      name: string;
+      arguments: string;
+    }>;
   };
+  /**
+   * Optional. Required only for `stream: true` calls. The function used to
+   * open a streaming HTTP request. Takes the same request shape as
+   * `request`, but resolves to an `AsyncIterable` of progressively-arriving
+   * `Uint8Array` or `string` chunks instead of a buffered `ResponseLike`.
+   * Defaults to native `fetch`.
+   */
+  requestStream?: StreamRequestLike;
+  /**
+   * Optional. How the raw stream bytes are split into individual event
+   * payloads. Defaults to Server-Sent Events framing (`data: ...` blocks
+   * separated by a blank line, `[DONE]` sentinel honored, see
+   * `parseSseStream`), which covers the large majority of LLM providers'
+   * streaming HTTP endpoints. Override this for a provider that frames its
+   * stream differently, e.g. newline-delimited JSON (NDJSON) with no SSE
+   * envelope.
+   */
+  parseStreamFrames?: (chunks: AsyncIterable<Uint8Array | string>) => AsyncIterable<unknown>;
+  /**
+   * Optional. Required only for `stream: true` calls. Maps one parsed
+   * stream event (already extracted from its frame by `parseStreamFrames`)
+   * into zero, one, or more `WireStreamChunk`s, mirrors `mapResponse`'s
+   * role for the non-streaming path, just per-event instead of once for
+   * the whole body. Return `undefined` to skip an event that carries
+   * nothing VernLLM needs (e.g. a provider's keep-alive ping). Configs
+   * that don't implement this make `stream: true` throw a clear
+   * `LLMError('validation')` rather than a confusing runtime failure or a
+   * silently empty stream.
+   */
+  mapStreamEvent?: (event: unknown) => WireStreamChunk | WireStreamChunk[] | undefined;
 }
 /**
  * A fetch-based escape hatch for providers with no SDK, or where pulling one
@@ -810,6 +1683,34 @@ interface FetchAdapterConfig {
  * Non-2xx responses throw an error with `.status` set to the HTTP status
  * code, so VernLLMs `nonRetryableStatus` handling (e.g. failing fast on
  * 401/403) applies here too
+ *
+ * Tool calling works the same way as every other adapter: `mapRequest`
+ * receives the full `ChatRequest`, including `tools`/`toolChoice`, so it can
+ * translate them into whatever shape the provider's wire format expects
+ * (typically an OpenAI-`function`-wrapped `tools` array plus a `tool_choice`
+ * field). On the way back, `mapResponse` may return a `toolCalls` array
+ * (id/name/JSON-encoded-arguments-string per call) alongside or instead of
+ * `content`; VernLLM parses and (if `argumentsSchema` was set) validates
+ * those arguments the same way it does for every other adapter. For
+ * `stream: true`, tool-call deltas go through the existing
+ * `mapStreamEvent` seam via `WireStreamChunk`'s `tool_call_delta` variant,
+ * no separate config is needed for streaming vs non-streaming tool calls.
+ *
+
+ * `createStream` requires `mapStreamEvent` (there's no non-streaming
+ * response to fall back on, unlike the other three optional streaming
+ * seams). It opens the request via `requestStream` (defaults to native
+ * `fetch`), splits the raw bytes into individual events via
+ * `parseStreamFrames` (defaults to SSE framing, see `parseSseStream`),
+ * and translates each event into `WireStreamChunk`(s) via
+ * `mapStreamEvent`. Both seams are overridable per-config for providers
+ * that don't fit the SSE-over-fetch default. If a custom `request`
+ * transport is configured, `requestStream` must be configured too,
+ * `requestStream` never silently falls back to `request` (see
+ * `createStream`'s own comment for why), so a `stream: true` call with
+ * `request` set but no `requestStream` throws a clear
+ * `LLMError('validation')` instead of quietly using unrelated native
+ * `fetch`.
  */
 declare function fromFetch(config: FetchAdapterConfig): LLMClient;
 
@@ -834,11 +1735,46 @@ declare function fromFetch(config: FetchAdapterConfig): LLMClient;
  * (extra fields, stricter unions, etc.), so this takes `unknown` and casts:
  * the actual compatibility contract is the JSON each provider sends and
  * receives over the wire, not the SDKs TS types.
+ *
+ * `createStream` is implemented by calling the same underlying
+ * `chat.completions.create` with `stream: true` (and, for providers that
+ * support it, `stream_options: { include_usage: true }`, so a final usage
+ * block arrives), the OpenAI SDK, and every OpenAI-compatible client
+ * modeled on it, returns an `AsyncIterable` of SSE chunks instead of a
+ * single completion object when `stream: true` is set. Each chunk is
+ * translated into `WireStreamChunk`(s) via `toWireStreamChunks`.
+ *
+ * Note on long-running reasoning models: this adapter consumes the
+ * underlying SDK's already-parsed stream rather than raw SSE bytes, so
+ * unlike `fromFetch`/`fromAnthropic` it cannot see comment-only keep-alive
+ * ping frames. Combined with `chunkIdleTimeoutMs`'s 30 second default and
+ * `reasoningEffort` (documented to have long silent gaps for o-series and
+ * similar models), a long-running reasoning call on this adapter can trip
+ * the idle timeout even though the provider is still working. Raise or
+ * disable `chunkIdleTimeoutMs` per call for those routes, see `CallParams`.
  */
-declare function fromOpenAICompatible(client: unknown): LLMClient;
+interface OpenAICompatibleAdapterOptions {
+  /**
+   * Whether the provider supports `stream_options.include_usage`. Not
+   * every "OpenAI-compatible" provider is guaranteed to, so this defaults
+   * to `true` (matching OpenAI, Groq, Mistral, and most others observed)
+   * and should be set to `false` for a provider verified not to support
+   * it. When `false`, `stream_options` is omitted entirely and no usage
+   * block will arrive on the stream; callers relying on streamed `usage`
+   * with such a provider won't get one.
+   */
+  supportsStreamUsage?: boolean;
+}
+declare function fromOpenAICompatible(client: unknown, options?: OpenAICompatibleAdapterOptions): LLMClient;
 /** Groqs SDK matches the OpenAI wire format */
 declare const fromGroq: typeof fromOpenAICompatible;
-/** Mistrals `chat.completions`-shaped client (or their OpenAI-compat endpoint) */
+/**
+ * Mistrals `chat.completions`-shaped client (or their OpenAI-compat
+ * endpoint). Mistral supports `stream_options.include_usage` (added after
+ * an earlier period where it returned a 422 for unrecognized fields, per
+ * Mistral's changelog and streaming docs), so this is a plain alias like
+ * the others, `supportsStreamUsage` defaults to `true`.
+ */
 declare const fromMistral: typeof fromOpenAICompatible;
 /** DeepSeeks API is OpenAI-compatible */
 declare const fromDeepSeek: typeof fromOpenAICompatible;
@@ -929,5 +1865,5 @@ declare const from01AI: typeof fromOpenAICompatible;
 //#endregion
 //# sourceMappingURL=openaiCompatible.d.ts.map
 
-export { AnthropicClient, BedrockConverseClient, CacheAdapter, CachedCallParams, CallParams, CircuitBreaker, CircuitBreakerOptions, ConsoleLogger, ContentBlock, ConversationTurn, FetchAdapterConfig, GeminiClient, ImageBlock, InMemoryCacheAdapter, JsonSchemaSpec, LLMClient, LLMError, LLMErrorType, Logger, NormalizedCacheAdapter, OnUsage, RefundUsage, ReserveUsage, SchemaLike, TextBlock, TieredCacheAdapter, TokenUsage, VernLLM, VernLLMOptions, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGitHubModels, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromKlusterAI, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, isLLMError };
+export { AnthropicClient, BedrockConverseClient, CacheAdapter, CachedCallParams, CachedStreamCallParams, CachedStreamToolCallParams, CachedToolCallParams, CallParams, CallWithToolsResult, CircuitBreaker, CircuitBreakerOptions, ConsoleLogger, ContentBlock, ContentResult, ConversationTurn, FetchAdapterConfig, GeminiClient, ImageBlock, InMemoryCacheAdapter, JsonSchemaSpec, LLMClient, LLMError, LLMErrorType, Logger, NormalizedCacheAdapter, OnUsage, RefundUsage, ReserveUsage, SSE_PING, SchemaLike, StreamCallResult, StreamChunk, StreamEnabledCallParams, TextBlock, TieredCacheAdapter, TokenUsage, ToolCall, ToolCallResult, ToolChoice, ToolDefinition, ToolEnabledCallParams, ToolResult, VernLLM, VernLLMOptions, WireMessage, WireStreamChunk, WireToolCall, WireToolChoice, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGitHubModels, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromKlusterAI, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, isLLMError, isToolCallResult, parseSseStream };
 //# sourceMappingURL=index.d.cts.map