vern-llm 1.7.0 → 2.0.0

package/dist/index.js

@@ -51,7 +51,7 @@ var CircuitBreaker = class {
 		if (this.state === "closed") return;
 		if (this.state === "open") {
 			const elapsed = Date.now() - this.openedAt;
-			if (elapsed < this.cooldownMs) throw new LLMError(`Circuit open — provider has failed ${this.consecutiveFailures} times in a row. Retry in ${Math.ceil((this.cooldownMs - elapsed) / 1e3)}s.`, "circuit_open");
+			if (elapsed < this.cooldownMs) throw new LLMError(`Circuit open, provider has failed ${this.consecutiveFailures} times in a row. Retry in ${Math.ceil((this.cooldownMs - elapsed) / 1e3)}s.`, "circuit_open");
 			this.state = "half-open";
 			this.trialInFlight = true;
 			return;
@@ -84,6 +84,48 @@ var CircuitBreaker = class {
 
 //#endregion
 //#region src/internal/vernLLM.utils.ts
+/** Translates app-facing `ToolDefinition[]` into the OpenAI-shaped wire tools array. */
+function toWireTools(tools) {
+	return tools.map((tool) => ({
+		type: "function",
+		function: {
+			name: tool.name,
+			description: tool.description,
+			parameters: tool.parameters
+		}
+	}));
+}
+/** Translates app-facing `ToolCall[]` (e.g. from a replayed assistant turn) into wire tool_calls. */
+function toWireToolCalls(toolCalls) {
+	return toolCalls.map((tc) => ({
+		id: tc.id,
+		type: "function",
+		function: {
+			name: tc.name,
+			arguments: JSON.stringify(tc.arguments ?? {})
+		}
+	}));
+}
+/**
+* Parses the provider's wire-shaped `tool_calls` back into VernLLM's
+* `ToolCall[]`. Malformed argument JSON is a `'parse'` error, same
+* convention as malformed JSON response bodies elsewhere in VernLLM.
+*/
+function parseWireToolCalls(wireToolCalls) {
+	return wireToolCalls.map((wc) => {
+		let parsedArgs;
+		try {
+			parsedArgs = wc.function.arguments.trim() ? JSON.parse(wc.function.arguments) : {};
+		} catch {
+			throw new LLMError(`Invalid JSON arguments for tool call "${wc.function.name}"`, "parse");
+		}
+		return {
+			id: wc.id,
+			name: wc.function.name,
+			arguments: parsedArgs
+		};
+	});
+}
 function defaultParseJson(content) {
 	try {
 		return JSON.parse(content);
@@ -94,7 +136,9 @@ function defaultParseJson(content) {
 /**
 * Looks inside an unknown error value and pulls out an http status code
 * if one is present. Checks the status field first then the status code
-* field since different client libraries use different names for this.
+* field since different client libraries use different names for this,
+* falling back to AWS SDK v3's `$metadata.httpStatusCode` (e.g. Bedrock's
+* `ThrottlingException`), which doesn't set either of the other two.
 * Returns undefined when the error is not an object or carries no status
 */
 function extractStatus(err) {
@@ -102,6 +146,7 @@ function extractStatus(err) {
 	const error = err;
 	if (typeof error.status === "number") return error.status;
 	if (typeof error.statusCode === "number") return error.statusCode;
+	if (typeof error.$metadata?.httpStatusCode === "number") return error.$metadata.httpStatusCode;
 	return void 0;
 }
 function formatSafely(value) {
@@ -131,6 +176,21 @@ function describeError(err) {
 	return formatSafely(err);
 }
 /**
+* `setTimeout` silently clamps any delay above this (~24.8 days) or
+* `Infinity` down to ~1ms instead of erroring, so a caller passing
+* `Infinity` as "no timeout" gets the opposite of what they asked for.
+* Both timeout helpers below guard against this explicitly.
+*/
+const MAX_SETTIMEOUT_MS = 2147483647;
+/** True when a timeout value should be treated as "disabled" rather than passed to `setTimeout`. */
+function isTimeoutDisabled(ms) {
+	return !ms || ms <= 0 || ms === Infinity;
+}
+/** Caps a timeout at the largest delay `setTimeout` actually honors. */
+function clampTimeoutMs(ms) {
+	return Math.min(ms, MAX_SETTIMEOUT_MS);
+}
+/**
 * Runs an async function and cancels it if it takes longer than the given
 * timeout. Creates an internal abort controller that fires after the
 * timeout elapses, and combines it with any external signal the caller
@@ -140,12 +200,15 @@ function describeError(err) {
 * continue to propagate as aborted errors. The internal timer is always
 * cleared afterward, whether the function succeeds, fails, or is aborted,
 * so nothing is left running in the background.
+*
+* `timeoutMs` of `Infinity` (or any value beyond what `setTimeout` can
+* represent) disables the timeout rather than firing almost immediately.
 */
 async function withTimeout(fn, timeoutMs, externalSignal) {
 	const controller = new AbortController();
-	const timer = setTimeout(() => {
+	const timer = isTimeoutDisabled(timeoutMs) ? void 0 : setTimeout(() => {
 		controller.abort();
-	}, timeoutMs);
+	}, clampTimeoutMs(timeoutMs));
 	const signal = externalSignal ? AbortSignal.any([externalSignal, controller.signal]) : controller.signal;
 	try {
 		return await fn(signal);
@@ -157,6 +220,54 @@ async function withTimeout(fn, timeoutMs, externalSignal) {
 	}
 }
 /**
+* Races one `iterator.next()` call against a per-call idle timer, to
+* bound the gap *between* chunks (unlike `withTimeout`, which only bounds
+* opening the stream and its first chunk). Without this, a connection
+* that streams one chunk then hangs would never fail.
+*
+* `timeoutMs` of 0/undefined/`Infinity` disables the check. Otherwise
+* rejects with `LLMError('timeout')` if `next()` doesn't settle in time.
+* The clock resets on every call, so the window is measured from the most
+* recent chunk, not from stream start.
+*
+* `onIdle`, if given, is called the moment the timer fires (before the
+* rejection), so callers can abort the underlying transport instead of
+* just walking away from an unread promise. `logger`, if given, records a
+* debug line if `next()` still settles *after* the idle timeout already
+* rejected. `resolve`/`reject` on an already-settled promise is otherwise
+* a silent no-op, so without this the late chunk (possibly the final
+* usage chunk) would vanish with no trace.
+*/
+function withChunkIdleTimeout(next, timeoutMs, onIdle, logger) {
+	if (isTimeoutDisabled(timeoutMs)) return next();
+	const activeTimeoutMs = timeoutMs;
+	let settled = false;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			settled = true;
+			onIdle?.();
+			reject(new LLMError(`No stream chunk received for ${activeTimeoutMs}ms (idle timeout)`, "timeout"));
+		}, clampTimeoutMs(activeTimeoutMs));
+		next().then((result) => {
+			clearTimeout(timer);
+			if (settled) {
+				logger?.debug("[VernLLM] chunk resolved after idle timeout already fired; discarding");
+				return;
+			}
+			settled = true;
+			resolve(result);
+		}, (error) => {
+			clearTimeout(timer);
+			if (settled) {
+				logger?.debug("[VernLLM] chunk rejection arrived after idle timeout already fired; discarding");
+				return;
+			}
+			settled = true;
+			reject(error);
+		});
+	});
+}
+/**
 * Default cap (ms) for both exponential backoff and honored Retry-After
 * values, so a misbehaving/adversarial Retry-After can't stall a caller
 * indefinitely
@@ -271,6 +382,143 @@ async function withReservedUsage(params, coalesced, getResult, signal, onRefundE
 	}
 	return result;
 }
+/**
+* Streaming counterpart to `withReservedUsage`. `withReservedUsage` assumes
+* `getResult()` settling *is* the operation's final outcome, awaiting it
+* synchronously before reserve/refund resolve. Streaming can't satisfy that:
+* `call()` must return `{ chunks, finalResult }` as soon as the stream
+* opens, well before the real outcome (validation, schema/tool-call checks)
+* is known.
+*
+* Reserves usage before `openStream` runs, same failure mode as the
+* non-streaming path if `reserveUsage` itself throws (mapped to
+* `quota_exceeded`, nothing opened). If `openStream` itself throws (stream
+* never opened), refunds synchronously and rethrows, exactly like
+* `withReservedUsage` does today. If it succeeds, returns `{ chunks,
+* finalResult }` immediately, refund/report is deferred onto
+* `finalResult`'s continuation, since that's the only point the real
+* outcome is known. This means `onUsageFailure` (and any refund) can fire
+* well after this function itself has returned.
+*/
+async function withReservedUsageForStream(params, openStream, signal, onRefundError) {
+	if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+	let reserved = false;
+	try {
+		if (params.reserveUsage) {
+			await params.reserveUsage({
+				coalesced: false,
+				signal
+			});
+			reserved = true;
+		}
+	} catch (error) {
+		if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+		throw new LLMError(error instanceof Error ? error.message : "Usage reservation failed", "quota_exceeded", void 0, void 0, error);
+	}
+	const refund = async (logMessage) => {
+		try {
+			await params.refundUsage?.({
+				coalesced: false,
+				signal
+			});
+		} catch (refundError) {
+			onRefundError(logMessage, refundError);
+		}
+	};
+	let opened;
+	try {
+		opened = await openStream();
+	} catch (error) {
+		if (reserved) await refund("[VernLLM] refundUsage failed after stream-open failure");
+		throw error;
+	}
+	const finalResult = opened.finalResult.then((value) => value, async (error) => {
+		if (reserved) await refund("[VernLLM] refundUsage failed after stream error");
+		throw error;
+	});
+	finalResult.catch(() => {});
+	return {
+		chunks: opened.chunks,
+		finalResult
+	};
+}
+/**
+* Converts an already-known cache value back into a plausible "text" form
+* for a one-shot replay chunk: passed through unchanged if it's already a
+* string (the `jsonMode: false` case), otherwise `JSON.stringify`'d (the
+* `jsonMode: true` case, where the cached value is the *parsed* result, not
+* the original raw text). This is a reasonable reconstruction, not a
+* byte-identical replay of whatever text the model originally streamed,
+* good enough for `for await (const c of chunks)` call sites that don't
+* branch on hit vs. miss, which is the only thing a cache-hit replay needs
+* to support.
+*/
+function toReplayText(value) {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+* Builds a trivially-exhausted one-shot `chunks` iterable from an
+* already-known value, used for a `cachedCall` cache hit, where there's no
+* live generation to relay (see `VernLLM.cachedCall`'s docs). No `usage`
+* chunk is emitted: a cache hit spent no real tokens, so there's nothing to
+* report, matching how non-streaming `cachedCall` never calls `onUsage` on
+* a hit either.
+*
+* `hasTools` must reflect whether the *original* call that produced this
+* cached value had `tools` set, that's what determines whether `value` is
+* `T` directly or a `CallWithToolsResult<T>` wrapper, and it isn't
+* something that can be reliably guessed from the value's shape alone
+* (a `schema`-validated `T` could coincidentally look like a
+* `CallWithToolsResult`).
+*/
+function buildReplayChunks(value, hasTools) {
+	const items = [];
+	if (hasTools) {
+		const result = value;
+		if (result.type === "tool_calls") {
+			result.toolCalls.forEach((toolCall, index) => {
+				items.push({
+					type: "tool_call_delta",
+					index,
+					id: toolCall.id,
+					name: toolCall.name,
+					argsDelta: JSON.stringify(toolCall.arguments ?? {}),
+					complete: true
+				});
+			});
+			if (result.content) items.push({
+				type: "text-delta",
+				delta: result.content
+			});
+		} else items.push({
+			type: "text-delta",
+			delta: toReplayText(result.content)
+		});
+	} else items.push({
+		type: "text-delta",
+		delta: toReplayText(value)
+	});
+	return { async *[Symbol.asyncIterator]() {
+		for (const item of items) yield item;
+	} };
+}
+/**
+* Streaming counterpart to `buildReplayChunks` for a `cachedCall` that
+* *joined* an already-in-flight call for the same key rather than
+* triggering one itself (see `runCachedStream`'s in-flight-coalescing
+* path): there's no live stream to relay (it isn't this call's stream to
+* relay, see the joiner-path comment in `runCachedStream`), but there's
+* also no value yet, only a pending promise for one. Waits for `promise`,
+* then delegates to `buildReplayChunks`. If `promise` rejects, iterating
+* `chunks` throws that same error, consistent with how a live stream's
+* `chunks` throws on a mid-stream failure.
+*/
+function buildReplayChunksFromPromise(promise, hasTools) {
+	return { async *[Symbol.asyncIterator]() {
+		const value = await promise;
+		yield* buildReplayChunks(value, hasTools);
+	} };
+}
 
 //#endregion
 //#region src/logger.ts
@@ -403,34 +651,52 @@ var TieredCacheAdapter = class {
 	}
 };
 
+//#endregion
+//#region src/types/tools.ts
+/**
+* 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.
+*/
+function isToolCallResult(result) {
+	return typeof result === "object" && result !== null && "type" in result && result.type === "tool_calls" && Array.isArray(result.toolCalls);
+}
+
 //#endregion
 //#region src/vernLLM.ts
 /**
-* 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.
 */
 var VernLLM = class {
 	client;
 	model;
 	maxRetries;
 	timeoutMs;
+	chunkIdleTimeoutMs;
 	baseDelayMs;
 	defaultMaxTokens;
+	defaultTemperature;
 	cache;
 	nonRetryableStatus;
 	inFlight = new Map();
 	parseJson;
 	onUsage;
+	onUsageFailure;
 	logger;
 	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) {
@@ -438,8 +704,10 @@ var VernLLM = class {
 		this.model = options.model;
 		this.maxRetries = options.maxRetries ?? 1;
 		this.timeoutMs = options.timeoutMs ?? 25e3;
+		this.chunkIdleTimeoutMs = options.chunkIdleTimeoutMs ?? 3e4;
 		this.baseDelayMs = options.baseDelayMs ?? 500;
 		this.defaultMaxTokens = options.defaultMaxTokens ?? 1e3;
+		this.defaultTemperature = options.defaultTemperature === void 0 ? .2 : options.defaultTemperature;
 		this.cache = options.cache ?? new InMemoryCacheAdapter();
 		this.nonRetryableStatus = options.nonRetryableStatus ?? [
 			400,
@@ -450,6 +718,7 @@ var VernLLM = class {
 		];
 		this.parseJson = options.parseJson ?? defaultParseJson;
 		this.onUsage = options.onUsage;
+		this.onUsageFailure = options.onUsageFailure;
 		this.logger = options.logger ?? new ConsoleLogger(options.debug ?? false);
 		this.breaker = options.circuitBreaker ? new CircuitBreaker(options.circuitBreaker === true ? void 0 : options.circuitBreaker) : void 0;
 	}
@@ -457,38 +726,307 @@ var VernLLM = class {
 	async resolveCacheKey(key) {
 		return this.cache.resolveKey ? await this.cache.resolveKey(key) : key;
 	}
-	/**
-	* Makes a single logical LLM call, retrying on failure per the configured
-	* policy. Fails fast if the breaker is open or the signal is already
-	* aborted. On exhausting retries, records a breaker failure and rejects
-	* with a normalized LLMError.
-	*
-	* @param params - System/user content plus per-call overrides (model,
-	* temperature, jsonMode, schema, signal, etc). See `CallParams`.
-	* @returns The parsed (and optionally schema-validated) response, or the
-	* raw string content when `jsonMode` is false and no `jsonSchema` is set.
-	*/
 	async call(params) {
 		this.breaker?.assertClosed();
 		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
 		const requestId = params.requestId ?? randomUUID();
+		if (params.stream) return withReservedUsageForStream(params, async () => {
+			try {
+				return await this.retryWithBackoff((attempt) => this.executeStreamCall(params, requestId, attempt), requestId, params.signal);
+			} catch (error) {
+				const normalized = normalizeError(error, params.signal);
+				if (normalized.type !== "validation" && normalized.type !== "parse" && normalized.type !== "aborted") this.breaker?.recordFailure();
+				this.logger.debug(`[VernLLM:${requestId}] stream-open error:\n${describeError(error)}`);
+				throw normalized;
+			}
+		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
 		return withReservedUsage(params, false, async () => {
 			try {
-				return await this.retryWithBackoff(() => this.executeCall(params, requestId), requestId, params.signal);
+				return await this.retryWithBackoff((attempt) => this.executeCall(params, requestId, attempt), requestId, params.signal);
 			} catch (error) {
 				const normalized = normalizeError(error, params.signal);
 				if (normalized.type !== "validation" && normalized.type !== "parse" && normalized.type !== "aborted") this.breaker?.recordFailure();
-				this.logger.debug(`[vern:${requestId}] error:\n${describeError(error)}`);
+				this.logger.debug(`[VernLLM:${requestId}] error:\n${describeError(error)}`);
 				throw normalized;
 			}
 		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
 	}
+	/**
+	* 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.
+	*/
+	async executeCall(params, requestId, attempt) {
+		const { useJson, model, request } = this.buildRequestPayload(params);
+		const response = await withTimeout((attemptSignal) => this.client.chat.completions.create(request, { signal: attemptSignal }), this.timeoutMs, params.signal);
+		const usage = this.extractUsage(response, requestId, model);
+		const rawContent = response.choices?.[0]?.message?.content;
+		const wireToolCalls = response.choices?.[0]?.message?.tool_calls;
+		return this.finalizeResponse(rawContent, wireToolCalls, params, useJson, usage, requestId, attempt);
+	}
+	/**
+	* 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.
+	*/
+	finalizeResponse(rawContent, wireToolCalls, params, useJson, usage, requestId, attempt) {
+		try {
+			const content = rawContent?.trim();
+			if (!content && !wireToolCalls?.length) throw new LLMError("Empty LLM response", "api");
+			this.logger.debug(`[VernLLM:${requestId}] output:\n${(content ?? `[${wireToolCalls?.length ?? 0} tool call(s)]`).slice(0, 800)}`);
+			if (wireToolCalls?.length) {
+				if (!params.tools) throw new LLMError("Provider returned tool_calls but no `tools` were sent with this call.", "api");
+				const toolCalls = parseWireToolCalls(wireToolCalls);
+				this.validateToolCallArguments(toolCalls, params.tools);
+				this.breaker?.recordSuccess();
+				this.reportUsage(usage);
+				return {
+					type: "tool_calls",
+					toolCalls,
+					...content ? { content } : {}
+				};
+			}
+			const textContent = content ?? "";
+			if (!useJson) {
+				this.breaker?.recordSuccess();
+				this.reportUsage(usage);
+				return params.tools ? {
+					type: "content",
+					content: textContent
+				} : textContent;
+			}
+			const result = this.parseAndValidate(textContent, params.schema);
+			this.breaker?.recordSuccess();
+			this.reportUsage(usage);
+			return params.tools ? {
+				type: "content",
+				content: result
+			} : result;
+		} catch (error) {
+			const normalized = normalizeError(error, params.signal);
+			if (usage && normalized.type !== "aborted") this.reportUsageFailure(usage, normalized, attempt);
+			throw normalized;
+		}
+	}
+	/**
+	* 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`).
+	*/
+	async executeStreamCall(params, requestId, attempt) {
+		const { useJson, model, request } = this.buildRequestPayload(params);
+		const createStream = this.client.chat.completions.createStream;
+		if (!createStream) throw new LLMError("stream: true requires a client/adapter with createStream", "validation");
+		const streamController = new AbortController();
+		const combinedExternal = params.signal ? AbortSignal.any([params.signal, streamController.signal]) : streamController.signal;
+		const { iterator, first } = await withTimeout(async (attemptSignal) => {
+			const streamIterator = createStream(request, { signal: attemptSignal })[Symbol.asyncIterator]();
+			const firstResult = await streamIterator.next();
+			return {
+				iterator: streamIterator,
+				first: firstResult
+			};
+		}, this.timeoutMs, combinedExternal);
+		if (first.done) throw new LLMError("Empty LLM response", "api");
+		return this.buildStreamResult(iterator, first, params, useJson, requestId, model, attempt, streamController);
+	}
+	/**
+	* 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.
+	*/
+	buildStreamResult(iterator, first, params, useJson, requestId, model, attempt, streamController) {
+		let resolveFinal;
+		let rejectFinal;
+		const finalResult = new Promise((resolve, reject) => {
+			resolveFinal = resolve;
+			rejectFinal = reject;
+		});
+		finalResult.catch(() => {});
+		const MAX_BUFFERED_CHUNKS = 1e4;
+		const buffered = [];
+		const pending = [];
+		let streamDone = false;
+		let streamError;
+		let hasLoggedEviction = false;
+		const push = (chunk) => {
+			const waiter = pending.shift();
+			if (waiter) {
+				waiter.resolve({
+					done: false,
+					value: chunk
+				});
+				return;
+			}
+			buffered.push(chunk);
+			if (buffered.length > MAX_BUFFERED_CHUNKS * 2) {
+				if (!hasLoggedEviction) {
+					hasLoggedEviction = true;
+					this.logger.debug(`[VernLLM] stream chunk buffer exceeded cap (${MAX_BUFFERED_CHUNKS}), evicting ${buffered.length - MAX_BUFFERED_CHUNKS} oldest chunk(s); buffered=${buffered.length}. The chunks iterable was never read (or fell far behind) for this stream.`);
+				}
+				buffered.splice(0, buffered.length - MAX_BUFFERED_CHUNKS);
+			}
+		};
+		const finish = () => {
+			streamDone = true;
+			for (const waiter of pending.splice(0)) waiter.resolve({
+				done: true,
+				value: void 0
+			});
+		};
+		const fail = (error) => {
+			streamDone = true;
+			streamError = error;
+			for (const waiter of pending.splice(0)) waiter.reject(error);
+		};
+		const chunks = { [Symbol.asyncIterator]() {
+			return { next() {
+				if (buffered.length) return Promise.resolve({
+					done: false,
+					value: buffered.shift()
+				});
+				if (streamDone) return streamError ? Promise.reject(streamError) : Promise.resolve({
+					done: true,
+					value: void 0
+				});
+				return new Promise((resolve, reject) => {
+					pending.push({
+						resolve,
+						reject
+					});
+				});
+			} };
+		} };
+		const toolCallAcc = new Map();
+		let textAcc = "";
+		let usage;
+		(async () => {
+			try {
+				let result = first;
+				while (!result.done) {
+					const wireChunk = result.value;
+					if (wireChunk.type === "ping") {} else if (wireChunk.type === "text-delta") {
+						textAcc += wireChunk.delta;
+						push({
+							type: "text-delta",
+							delta: wireChunk.delta
+						});
+					} else if (wireChunk.type === "tool_call_delta") {
+						const entry = toolCallAcc.get(wireChunk.index) ?? { args: "" };
+						entry.id ??= wireChunk.id;
+						entry.name ??= wireChunk.name;
+						entry.args += wireChunk.argumentsDelta ?? "";
+						toolCallAcc.set(wireChunk.index, entry);
+						push({
+							type: "tool_call_delta",
+							index: wireChunk.index,
+							id: wireChunk.id,
+							name: wireChunk.name,
+							argsDelta: wireChunk.argumentsDelta,
+							complete: wireChunk.complete
+						});
+					} else if (wireChunk.type === "usage") {
+						usage = {
+							promptTokens: wireChunk.usage.prompt_tokens ?? 0,
+							completionTokens: wireChunk.usage.completion_tokens ?? 0,
+							totalTokens: wireChunk.usage.total_tokens ?? 0,
+							requestId,
+							model
+						};
+						push({
+							type: "usage",
+							usage
+						});
+					}
+					result = await withChunkIdleTimeout(() => iterator.next(), params.chunkIdleTimeoutMs ?? this.chunkIdleTimeoutMs, () => streamController.abort(), this.logger);
+				}
+			} catch (error) {
+				try {
+					await iterator.return?.();
+				} catch {}
+				streamController.abort();
+				const normalized = normalizeError(error, params.signal);
+				if (normalized.type === "timeout") this.breaker?.recordFailure();
+				if (usage && normalized.type !== "aborted") this.reportUsageFailure(usage, normalized, attempt, true);
+				fail(normalized);
+				rejectFinal(normalized);
+				return;
+			}
+			finish();
+			this.breaker?.recordSuccess();
+			try {
+				const wireToolCalls = toolCallAcc.size ? [...toolCallAcc.entries()].sort(([indexA], [indexB]) => indexA - indexB).map(([, entry]) => ({
+					id: entry.id ?? "",
+					type: "function",
+					function: {
+						name: entry.name ?? "",
+						arguments: entry.args
+					}
+				})) : void 0;
+				const finalized = this.finalizeResponse(textAcc, wireToolCalls, params, useJson, usage, requestId, attempt);
+				resolveFinal(finalized);
+			} catch (error) {
+				rejectFinal(error);
+			}
+		})();
+		return {
+			chunks,
+			finalResult
+		};
+	}
+	/**
+	* 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.
+	*/
+	validateToolCallArguments(toolCalls, tools) {
+		const knownNames = new Set(tools.map((t) => t.name));
+		for (const call of toolCalls) {
+			if (!knownNames.has(call.name)) throw new LLMError(`Model requested tool "${call.name}", which was not in the tools offered ([${[...knownNames].join(", ")}]).`, "api");
+			const definition = tools.find((t) => t.name === call.name);
+			if (!definition?.argumentsSchema) continue;
+			const result = definition.argumentsSchema.safeParse(call.arguments);
+			if (!result.success) throw new LLMError(`Arguments for tool call "${call.name}" failed validation`, "validation", void 0, result.error);
+		}
+	}
 	/** Runs `fn`, retrying with backoff according to `shouldRetry`. */
 	async retryWithBackoff(fn, requestId, signal) {
 		let lastError;
 		for (let attempt = 0; attempt <= this.maxRetries; attempt++) try {
 			if (attempt > 0) await this.recoverDelay(requestId, attempt, lastError, signal);
-			return await fn();
+			return await fn(attempt);
 		} catch (error) {
 			lastError = error;
 			if (!this.shouldRetry(error, signal)) break;
@@ -496,60 +1034,73 @@ var VernLLM = class {
 		throw lastError;
 	}
 	/**
-	* Performs a single attempt: builds the request, dispatches it with a
-	* timeout, and shapes the response. Throws on an empty response so the
-	* retry loop treats it like any other transient failure.
-	*/
-	async executeCall(params, requestId) {
-		const { useJson, model, request } = this.buildRequestPayload(params);
-		const response = await withTimeout((attemptSignal) => this.client.chat.completions.create(request, { signal: attemptSignal }), this.timeoutMs, params.signal);
-		const content = response.choices?.[0]?.message?.content?.trim();
-		if (!content) throw new LLMError("Empty LLM response", "api");
-		this.logger.debug(`[vern:${requestId}] output:\n${content.slice(0, 800)}`);
-		this.recordUsage(response, requestId, model);
-		if (!useJson) {
-			this.breaker?.recordSuccess();
-			return content;
-		}
-		const result = this.parseAndValidate(content, params.schema);
-		this.breaker?.recordSuccess();
-		return result;
-	}
-	/**
 	* Validates `history` alternates user/assistant turns, since providers
 	* like Anthropic/Gemini reject or mishandle consecutive same-role turns.
 	*/
 	validateHistory(history) {
-		let previousRole;
+		let previousTurn;
 		for (const [index, turn] of history.entries()) {
-			if (turn.role !== "user" && turn.role !== "assistant") throw new LLMError(`Invalid history[${index}].role "${turn.role}": must be "user" or "assistant"`, "validation");
-			if (turn.role === previousRole) throw new LLMError(`history must alternate user/assistant turns: consecutive "${turn.role}" turns at history[${index - 1}] and history[${index}]`, "validation");
-			previousRole = turn.role;
+			if (turn.role === "tool") {
+				if (previousTurn?.role !== "assistant" || !previousTurn.toolCalls?.length) throw new LLMError(`history[${index}] is a "tool" turn, but must immediately follow an "assistant" turn that requested tools`, "validation");
+				if (!turn.toolResults?.length) throw new LLMError(`history[${index}] is a "tool" turn but has no toolResults`, "validation");
+				const requestedIds = new Set(previousTurn.toolCalls.map((tc) => tc.id));
+				const resultIds = turn.toolResults.map((tr) => tr.toolCallId);
+				const unknownIds = resultIds.filter((id) => !requestedIds.has(id));
+				if (unknownIds.length) throw new LLMError(`history[${index}].toolResults references unknown toolCallId(s) [${unknownIds.join(", ")}]`, "validation");
+				const seenIds = new Set();
+				const duplicateIds = new Set();
+				for (const id of resultIds) {
+					if (seenIds.has(id)) duplicateIds.add(id);
+					seenIds.add(id);
+				}
+				if (duplicateIds.size) throw new LLMError(`history[${index}].toolResults has duplicate toolCallId(s) [${[...duplicateIds].join(", ")}]`, "validation");
+				const missingIds = [...requestedIds].filter((id) => !resultIds.includes(id));
+				if (missingIds.length) throw new LLMError(`history[${index}] is missing toolResults for toolCallId(s) [${missingIds.join(", ")}]`, "validation");
+			} else {
+				if (turn.role === previousTurn?.role) throw new LLMError(`history must alternate user/assistant turns: consecutive "${turn.role}" turns at history[${index - 1}] and history[${index}]`, "validation");
+				if (previousTurn?.role === "assistant" && previousTurn.toolCalls?.length) throw new LLMError(`history[${index}] follows an assistant tool request without tool results`, "validation");
+			}
+			previousTurn = turn;
 		}
-		if (previousRole === "user") throw new LLMError("The last entry in history is a \"user\" turn, which would collide with the current userContent turn. history must end with an \"assistant\" turn (or be empty).", "validation");
+		if (previousTurn?.role === "assistant" && previousTurn.toolCalls?.length) throw new LLMError("The last entry in history is an assistant tool request without tool results", "validation");
+		if (previousTurn?.role === "user") throw new LLMError("The last entry in history is a \"user\" turn, which would collide with the current userContent turn.", "validation");
 	}
 	/** Applies per-call defaults and shapes params into the client's request object. */
 	buildRequestPayload(params) {
-		const { systemPrompt, userContent, history = [], temperature = .2, jsonMode = true, maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema } = params;
+		const { systemPrompt, userContent, history = [], maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema, tools, toolChoice } = params;
+		const temperature = params.temperature === void 0 ? this.defaultTemperature : params.temperature;
+		if (tools && (jsonSchema || params.schema)) throw new LLMError("`tools` cannot be combined with `jsonSchema`/`schema`: on Anthropic and Bedrock, jsonSchema is implemented internally as a forced single-tool call, which would collide with real tools. Use one or the other.", "validation");
+		if (tools && tools.length === 0) throw new LLMError("`tools` was an empty array. This is almost always a bug (e.g. a filtered tool list that ended up empty). An empty `tools` array still switches on tool-call mode (response shape, jsonMode default, wire format) with nothing for the model to call. Omit `tools` entirely for a normal call, or make sure the array is non-empty.", "validation");
+		if (tools) {
+			const seen = new Set();
+			const duplicates = new Set();
+			for (const tool of tools) {
+				if (seen.has(tool.name)) duplicates.add(tool.name);
+				seen.add(tool.name);
+			}
+			if (duplicates.size) throw new LLMError(`\`tools\` has duplicate name(s): [${[...duplicates].join(", ")}]. Tool names must be unique.`, "validation");
+		}
+		if (toolChoice && !tools) throw new LLMError("`toolChoice` was set without `tools`. There is nothing for it to choose between. Set `tools`, or remove `toolChoice`.", "validation");
+		if (tools && typeof toolChoice === "object" && !tools.some((t) => t.name === toolChoice.name)) throw new LLMError(`toolChoice names "${toolChoice.name}", which is not in \`tools\` ([${tools.map((t) => t.name).join(", ")}]).`, "validation");
+		const jsonMode = params.jsonMode ?? (tools ? false : true);
 		const useJson = jsonMode || Boolean(jsonSchema);
 		if (params.schema && !useJson) throw new LLMError("schema was provided but jsonMode: false disables JSON parsing, so nothing would validate it. Remove jsonMode: false, set jsonSchema, or remove schema.", "validation");
 		const responseFormat = this.buildResponseFormat(jsonSchema, useJson);
 		this.validateHistory(history);
 		const request = {
 			model,
-			temperature,
+			...temperature !== null ? { temperature } : {},
 			max_tokens: maxTokens,
 			...responseFormat ? { response_format: responseFormat } : {},
 			...reasoningEffort ? { reasoning_effort: reasoningEffort } : {},
+			...tools ? { tools: toWireTools(tools) } : {},
+			...tools ? { tool_choice: this.buildWireToolChoice(toolChoice) } : {},
 			messages: [
 				...systemPrompt ? [{
 					role: "system",
 					content: systemPrompt
 				}] : [],
-				...history.map((turn) => ({
-					role: turn.role,
-					content: turn.content
-				})),
+				...history.flatMap((turn) => this.turnToWireMessages(turn)),
 				{
 					role: "user",
 					content: userContent
@@ -562,6 +1113,39 @@ var VernLLM = class {
 			request
 		};
 	}
+	/** Maps VernLLM's app-facing `ToolChoice` onto the OpenAI-shaped wire `tool_choice`. */
+	buildWireToolChoice(toolChoice) {
+		if (!toolChoice || toolChoice === "auto") return "auto";
+		if (toolChoice === "none" || toolChoice === "required") return toolChoice;
+		return {
+			type: "function",
+			function: { name: toolChoice.name }
+		};
+	}
+	/**
+	* 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.
+	*/
+	turnToWireMessages(turn) {
+		if (turn.role === "tool") return (turn.toolResults ?? []).map((tr) => ({
+			role: "tool",
+			tool_call_id: tr.toolCallId,
+			content: typeof tr.content === "string" ? tr.content : JSON.stringify(tr.content ?? null),
+			...tr.isError ? { is_error: true } : {}
+		}));
+		if (turn.role === "assistant" && turn.toolCalls?.length) return [{
+			role: "assistant",
+			...turn.content ? { content: turn.content } : {},
+			tool_calls: toWireToolCalls(turn.toolCalls)
+		}];
+		return [{
+			role: turn.role,
+			content: turn.content ?? ""
+		}];
+	}
 	/**
 	* Chooses the response format: a provider-native `jsonSchema` takes
 	* priority when supplied (constrains generation directly), otherwise
@@ -580,21 +1164,49 @@ var VernLLM = class {
 		};
 		return useJson ? { type: "json_object" } : void 0;
 	}
-	/** Reports token usage to `onUsage`, swallowing and logging any error it throws. */
-	recordUsage(response, requestId, model) {
-		if (!response.usage || !this.onUsage) return;
+	/**
+	* 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.
+	*/
+	extractUsage(response, requestId, model) {
+		if (!response.usage) return void 0;
+		return {
+			promptTokens: response.usage.prompt_tokens ?? 0,
+			completionTokens: response.usage.completion_tokens ?? 0,
+			totalTokens: response.usage.total_tokens ?? 0,
+			requestId,
+			model
+		};
+	}
+	/** Reports token usage for a successful call, swallowing and logging any error `onUsage` throws. */
+	reportUsage(usage) {
+		if (!usage || !this.onUsage) return;
 		try {
-			this.onUsage({
-				promptTokens: response.usage.prompt_tokens ?? 0,
-				completionTokens: response.usage.completion_tokens ?? 0,
-				totalTokens: response.usage.total_tokens ?? 0,
-				requestId,
-				model
-			});
+			this.onUsage(usage);
 		} catch (error) {
 			this.logger.error("[VernLLM] onUsage failed", { message: error instanceof Error ? error.message : "unknown" });
 		}
 	}
+	/**
+	* 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.
+	*/
+	reportUsageFailure(usage, error, attempt, terminal = false) {
+		const displayTokens = usage.totalTokens || usage.promptTokens + usage.completionTokens;
+		const attemptText = terminal ? "mid-stream failure (terminal, no further attempts)" : `attempt ${attempt + 1}/${this.maxRetries + 1}`;
+		this.logger.warn(`[VernLLM:${usage.requestId}] usage failure, ${attemptText}: type=${error.type} tokens=${displayTokens}`);
+		if (!this.onUsageFailure) return;
+		try {
+			this.onUsageFailure(usage, error);
+		} catch (hookError) {
+			this.logger.error("[VernLLM] onUsageFailure failed", { message: hookError instanceof Error ? hookError.message : "unknown" });
+		}
+	}
 	/** Parses response content as JSON and validates it against `schema` when supplied. */
 	parseAndValidate(content, schema) {
 		let parsed;
@@ -618,7 +1230,7 @@ var VernLLM = class {
 	async recoverDelay(requestId, attempt, error, signal) {
 		const retryAfterMs = extractRetryAfterMs(error);
 		const delay = retryAfterMs ?? getBackoffDelay(this.baseDelayMs, attempt);
-		this.logger.warn(`[vern:${requestId}] recovery attempt ${attempt}/${this.maxRetries}, waiting ${delay}ms` + (retryAfterMs !== void 0 ? " (honoring Retry-After)" : ""));
+		this.logger.warn(`[VernLLM:${requestId}] recovery attempt ${attempt}/${this.maxRetries}, waiting ${delay}ms` + (retryAfterMs !== void 0 ? " (honoring Retry-After)" : ""));
 		await waitForRetry(delay, signal);
 	}
 	/** Decides whether a failed attempt is worth retrying. */
@@ -633,7 +1245,7 @@ var VernLLM = class {
 	* 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).
 	*/
 	async deleteCache(key) {
@@ -641,15 +1253,20 @@ var VernLLM = class {
 		await this.cache.delete(await this.resolveCacheKey(key));
 	}
 	/**
-	* 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.
 	*
-	* @param params - `cacheKey`, `ttl`, `fn` (the work to run on a cache
+	* Not part of the public API. Backs the public `cachedCall()`, which
+	* always composes this with `call()` so cached results get the same
+	* retry/timeout/circuit-breaker guarantees as any other LLM call.
+	*
+	* @param params `cacheKey`, `ttl`, `fn` (the work to run on a cache
 	* miss, typically `() => this.call(...)`), and optional
-	* `reserveUsage`/`refundUsage`/`signal`. See `CachedCallParams`.
+	* `reserveUsage`/`refundUsage`/`signal`. See `InternalCacheParams`.
 	* @returns The cached value on a hit, or the result of `fn()` on a miss.
 	*/
-	async cachedCall(params) {
+	async runCached(params) {
 		const resolvedKey = await this.resolveCacheKey(params.cacheKey);
 		const resolvedParams = resolvedKey === params.cacheKey ? params : {
 			...params,
@@ -680,24 +1297,113 @@ var VernLLM = class {
 		}
 		return result;
 	}
-	/** Logs a failed refundUsage attempt via the configured logger. */
-	logRefundError(logMessage, error) {
-		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
+	/**
+	* 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.
+	*/
+	async runCachedStream(params, hasTools) {
+		const resolvedKey = await this.resolveCacheKey(params.cacheKey);
+		const resolvedParams = resolvedKey === params.cacheKey ? params : {
+			...params,
+			cacheKey: resolvedKey
+		};
+		const cached = await this.cache.get(resolvedKey);
+		if (cached.hit) {
+			const value = cached.value;
+			return {
+				chunks: buildReplayChunks(value, hasTools),
+				finalResult: Promise.resolve(value)
+			};
+		}
+		const existing = this.inFlight.get(resolvedKey);
+		if (existing) {
+			const finalResult = withReservedUsage(resolvedParams, true, () => existing, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+			return {
+				chunks: buildReplayChunksFromPromise(finalResult, hasTools),
+				finalResult
+			};
+		}
+		return this.registerStreamTrigger(resolvedParams);
 	}
 	/**
-	* Convenience wrapper composing `call` + `cachedCall`, so cached LLM calls
-	* automatically get retry/timeout/circuit-breaker behavior. `reserveUsage`/
-	* `refundUsage` are read from the top-level params only.
+	* 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`.
 	*
-	* @param params - `cachedCall` params (`cacheKey`, `ttl`, etc, minus `fn`)
-	* plus `call`, the `CallParams` to pass through to `this.call(...)`.
-	* @returns The cached value on a hit, or the freshly-called result on a miss.
+	* 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.
 	*/
-	async cachedLLMCall(params) {
+	registerStreamTrigger(params) {
+		let resolveInFlight;
+		let rejectInFlight;
+		const inFlightResult = new Promise((resolve, reject) => {
+			resolveInFlight = resolve;
+			rejectInFlight = reject;
+		});
+		this.inFlight.set(params.cacheKey, inFlightResult);
+		inFlightResult.catch(() => {}).finally(() => {
+			this.inFlight.delete(params.cacheKey);
+		});
+		const streamPromise = withReservedUsageForStream(params, async () => {
+			const opened = await params.openStream();
+			const trackedResult = opened.finalResult.then(async (value) => {
+				try {
+					await this.cache.set(params.cacheKey, value, params.ttl);
+				} catch (error) {
+					this.logger.error("[VernLLM] cache write failed", { message: error instanceof Error ? error.message : "unknown" });
+				}
+				return value;
+			}, (error) => {
+				throw error;
+			});
+			return {
+				chunks: opened.chunks,
+				finalResult: trackedResult
+			};
+		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+		streamPromise.then((opened) => {
+			opened.finalResult.then(resolveInFlight, rejectInFlight);
+		}, (error) => {
+			rejectInFlight(error);
+		});
+		return streamPromise;
+	}
+	/** Logs a failed refundUsage attempt via the configured logger. */
+	logRefundError(logMessage, error) {
+		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
+	}
+	async cachedCall(params) {
 		const { call: callParams,...cacheParams } = params;
-		const { reserveUsage: innerReserveUsage, refundUsage: innerRefundUsage,...restCallParams } = callParams;
-		if (innerReserveUsage || innerRefundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedLLMCall; set them at the top level instead.");
-		return this.cachedCall({
+		const { reserveUsage, refundUsage,...restCallParams } = callParams;
+		if (reserveUsage || refundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedCall; set them at the top level instead.");
+		if (restCallParams.stream) {
+			const streamParams = restCallParams;
+			return this.runCachedStream({
+				...cacheParams,
+				openStream: () => this.call(streamParams)
+			}, Boolean(restCallParams.tools));
+		}
+		return this.runCached({
 			...cacheParams,
 			fn: () => this.call(restCallParams)
 		});
@@ -711,6 +1417,108 @@ var VernLLM = class {
 	}
 };
 
+//#endregion
+//#region src/internal/sse.ts
+/**
+* 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.
+*/
+async function* parseSseStream(source) {
+	const decoder = new TextDecoder("utf-8", { fatal: true });
+	let buffer = "";
+	for await (const chunk of source) {
+		let text;
+		try {
+			text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+		} catch (cause) {
+			throw new LLMError("Invalid UTF-8 in SSE stream", "parse", void 0, void 0, cause);
+		}
+		buffer = (buffer + text).replace(/\r\n/g, "\n").replace(/\r(?!$)/g, "\n");
+		let boundary$1 = buffer.indexOf("\n\n");
+		while (boundary$1 !== -1) {
+			const frame = buffer.slice(0, boundary$1);
+			buffer = buffer.slice(boundary$1 + 2);
+			const event = parseSseFrame(frame);
+			if (event === DONE) return;
+			if (event !== NO_DATA) yield event;
+			boundary$1 = buffer.indexOf("\n\n");
+		}
+	}
+	try {
+		buffer += decoder.decode();
+	} catch (cause) {
+		throw new LLMError("Invalid UTF-8 in SSE stream", "parse", void 0, void 0, cause);
+	}
+	buffer = buffer.replace(/\r$/, "\n");
+	let boundary = buffer.indexOf("\n\n");
+	while (boundary !== -1) {
+		const frame = buffer.slice(0, boundary);
+		buffer = buffer.slice(boundary + 2);
+		const event = parseSseFrame(frame);
+		if (event === DONE) return;
+		if (event !== NO_DATA) yield event;
+		boundary = buffer.indexOf("\n\n");
+	}
+	const trailing = buffer.trim();
+	if (trailing) {
+		const event = parseSseFrame(trailing);
+		if (event !== DONE && event !== NO_DATA) yield event;
+	}
+}
+const DONE = Symbol("sse-stream-done");
+const NO_DATA = Symbol("sse-frame-no-data");
+/**
+* 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).
+*/
+const SSE_PING = Symbol("sse-frame-ping");
+/** Extracts and JSON-parses the `data:` payload of one SSE frame (the text between two blank lines). */
+function parseSseFrame(frame) {
+	const dataLines = [];
+	let sawComment = false;
+	for (const line of frame.split("\n")) {
+		if (line.startsWith(":")) {
+			sawComment = true;
+			continue;
+		}
+		if (!line.startsWith("data:")) continue;
+		dataLines.push(line.startsWith("data: ") ? line.slice(6) : line.slice(5));
+	}
+	if (!dataLines.length) return sawComment ? SSE_PING : NO_DATA;
+	const data = dataLines.join("\n");
+	if (data === "[DONE]") return DONE;
+	try {
+		return JSON.parse(data);
+	} catch (cause) {
+		throw new LLMError(`Invalid JSON in SSE frame: ${data.slice(0, 200)}`, "parse", void 0, void 0, cause);
+	}
+}
+
 //#endregion
 //#region src/internal/imageFormat.ts
 /**
@@ -758,6 +1566,93 @@ function toAnthropicContent(blocks) {
 	});
 }
 /**
+* Asserts a caller-supplied JSON Schema is an object schema before it's
+* used as Anthropic's `Tool.input_schema`, which (like every other
+* provider's function-calling API) requires `type: 'object'`. VernLLM's own
+* public `tools`/`jsonSchema` APIs accept freeform `Record<string,
+* unknown>` JSON Schema, so nothing upstream guarantees this at compile
+* time; this is the runtime check that stands in for that, so a schema
+* missing (or mistyping) `type: 'object'` fails loudly and immediately
+* instead of being silently forwarded to Anthropic malformed.
+*/
+function assertObjectSchema(schema, toolName) {
+	if (schema.type !== "object") throw new LLMError(`Tool "${toolName}"'s schema must have "type": "object" (Anthropic requires object-shaped tool parameters).`, "validation");
+	return schema;
+}
+/**
+* Translates VernLLM's OpenAI-shaped wire `tool_choice` into Anthropic's
+* `{ type: 'auto' | 'any' | 'none' | 'tool', name? }` shape. `'required'`
+* maps to `'any'` (Anthropic's "must call some tool" equivalent).
+*/
+function toAnthropicToolChoice(toolChoice) {
+	if (!toolChoice || toolChoice === "auto") return { type: "auto" };
+	if (toolChoice === "none") return { type: "none" };
+	if (toolChoice === "required") return { type: "any" };
+	return {
+		type: "tool",
+		name: toolChoice.function.name
+	};
+}
+/**
+* Builds the Anthropic-shaped request body from VernLLM's wire params,
+* shared between `create` and `createStream` so both go through identical
+* translation (system prompt, message shaping, and the jsonSchema →
+* forced-single-tool mapping all happen exactly once, not once per entry
+* point).
+*
+* Returns `toolName` alongside the body: when set, the model was forced to
+* call a single synthetic tool standing in for `jsonSchema` output, and
+* both `create` and `createStream` need to know this so they can unwrap
+* that tool call back into plain text content instead of treating it like
+* a real tool call.
+*/
+function buildAnthropicRequestBody(params) {
+	const systemMessage = params.messages.find((m) => m.role === "system");
+	const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "tool");
+	const toolName = params.response_format?.type === "json_schema" ? params.response_format.json_schema.name.trim() : void 0;
+	if (params.response_format?.type === "json_schema" && !toolName) throw new LLMError("json_schema.name must not be empty.", "validation");
+	let jsonInstruction;
+	let tools;
+	let toolChoice;
+	if (params.response_format?.type === "json_schema" && toolName) {
+		const { schema, description, strict } = params.response_format.json_schema;
+		tools = [{
+			name: toolName,
+			description,
+			input_schema: assertObjectSchema(schema, toolName),
+			strict
+		}];
+		toolChoice = {
+			type: "tool",
+			name: toolName
+		};
+	} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
+	else if (params.tools?.length) {
+		tools = params.tools.map((t) => ({
+			name: t.function.name,
+			description: t.function.description,
+			input_schema: assertObjectSchema(t.function.parameters, t.function.name)
+		}));
+		toolChoice = toAnthropicToolChoice(params.tool_choice);
+	}
+	const system = [systemMessage?.content, jsonInstruction].filter(Boolean).join("\n\n");
+	const body = {
+		model: params.model,
+		max_tokens: params.max_tokens,
+		...params.temperature !== void 0 ? { temperature: params.temperature } : {},
+		system: system || void 0,
+		messages: mergeConsecutiveToolResults$1(conversationMessages.map((m) => toAnthropicMessage(m))),
+		...tools ? {
+			tools,
+			tool_choice: toolChoice
+		} : {}
+	};
+	return {
+		body,
+		toolName
+	};
+}
+/**
 * Wraps an Anthropic SDK client so it satisfies the same `LLMClient`
 * interface VernLLM uses for OpenAI/Groq.
 *
@@ -772,53 +1667,161 @@ function toAnthropicContent(blocks) {
 * generation against.
 */
 function fromAnthropic(anthropicClient) {
-	return { chat: { completions: { async create(params, options) {
-		const systemMessage = params.messages.find((m) => m.role === "system");
-		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
-		const toolName = params.response_format?.type === "json_schema" ? params.response_format.json_schema.name : void 0;
-		let jsonInstruction;
-		let tools;
-		if (params.response_format?.type === "json_schema" && toolName) {
-			const { schema, description, strict } = params.response_format.json_schema;
-			tools = [{
-				name: toolName,
-				description,
-				input_schema: schema,
-				strict
-			}];
-		} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
-		const system = [systemMessage?.content, jsonInstruction].filter(Boolean).join("\n\n");
-		const response = await anthropicClient.messages.create({
-			model: params.model,
-			max_tokens: params.max_tokens,
-			temperature: params.temperature,
-			system: system || void 0,
-			messages: conversationMessages.map((m) => ({
-				role: m.role,
-				content: Array.isArray(m.content) ? toAnthropicContent(m.content) : m.content
-			})),
-			...tools ? {
-				tools,
-				tool_choice: {
-					type: "tool",
-					name: toolName
+	const rawMessagesCreate = anthropicClient.messages.create.bind(anthropicClient.messages);
+	return { chat: { completions: {
+		async create(params, options) {
+			const { body, toolName } = buildAnthropicRequestBody(params);
+			const response = await anthropicClient.messages.create(body, options);
+			let text;
+			let wireToolCalls;
+			if (toolName) {
+				const toolUse = response.content.find((block) => block.type === "tool_use" && block.name === toolName);
+				if (!toolUse) throw new LLMError(`Anthropic did not return the required structured output tool "${toolName}".`, "validation");
+				if (!toolUse.input || typeof toolUse.input !== "object" || Array.isArray(toolUse.input)) throw new LLMError(`Anthropic returned invalid structured output for tool "${toolName}". Expected an object.`, "validation");
+				text = JSON.stringify(toolUse.input);
+			} else {
+				text = response.content.filter((block) => block.type === "text").map((block) => block.text ?? "").join("");
+				const toolUses = response.content.filter((block) => block.type === "tool_use");
+				if (toolUses.length) wireToolCalls = toolUses.map((block) => ({
+					id: block.id,
+					type: "function",
+					function: {
+						name: block.name,
+						arguments: JSON.stringify(block.input ?? {})
+					}
+				}));
+			}
+			return {
+				choices: [{ message: {
+					content: text,
+					...wireToolCalls ? { tool_calls: wireToolCalls } : {}
+				} }],
+				usage: {
+					prompt_tokens: response.usage?.input_tokens,
+					completion_tokens: response.usage?.output_tokens,
+					total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0)
 				}
-			} : {}
-		}, options);
-		let text;
-		if (toolName) {
-			const toolUse = response.content.find((block) => block.type === "tool_use" && block.name === toolName);
-			text = toolUse ? JSON.stringify(toolUse.input) : "";
-		} else text = response.content.find((block) => block.type === "text")?.text ?? "";
-		return {
-			choices: [{ message: { content: text } }],
-			usage: {
-				prompt_tokens: response.usage?.input_tokens,
-				completion_tokens: response.usage?.output_tokens,
-				total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0)
+			};
+		},
+		async *createStream(params, options) {
+			const { body, toolName } = buildAnthropicRequestBody(params);
+			const stream = await rawMessagesCreate({
+				...body,
+				stream: true
+			}, options);
+			const blockKinds = new Map();
+			let inputTokens = 0;
+			let sawJsonTool = false;
+			for await (const event of stream) if (event.type === "message_start") inputTokens = event.message.usage?.input_tokens ?? 0;
+			else if (event.type === "content_block_start") if (event.content_block.type === "tool_use") {
+				const kind = event.content_block.name === toolName ? "json-tool" : "tool_use";
+				blockKinds.set(event.index, kind);
+				if (kind === "json-tool") sawJsonTool = true;
+				else if (!toolName) yield {
+					type: "tool_call_delta",
+					index: event.index,
+					id: event.content_block.id,
+					name: event.content_block.name
+				};
+			} else blockKinds.set(event.index, "text");
+			else if (event.type === "content_block_delta") {
+				if (event.delta.type === "text_delta") {
+					if (!toolName) yield {
+						type: "text-delta",
+						delta: event.delta.text
+					};
+				} else if (event.delta.type === "input_json_delta") {
+					const kind = blockKinds.get(event.index);
+					if (kind === "json-tool") yield {
+						type: "text-delta",
+						delta: event.delta.partial_json
+					};
+					else if (!toolName) yield {
+						type: "tool_call_delta",
+						index: event.index,
+						argumentsDelta: event.delta.partial_json
+					};
+				}
+			} else if (event.type === "message_delta") {
+				const outputTokens = event.usage?.output_tokens ?? 0;
+				yield {
+					type: "usage",
+					usage: {
+						prompt_tokens: inputTokens,
+						completion_tokens: outputTokens,
+						total_tokens: inputTokens + outputTokens
+					}
+				};
+			} else if (event.type === "ping") yield { type: "ping" };
+			if (toolName && !sawJsonTool) throw new LLMError(`Anthropic did not return the required structured output tool "${toolName}".`, "validation");
+		}
+	} } };
+}
+/**
+* Anthropic requires strict role alternation, so the per-wire-message
+* mapping above (one `{role:'user', content:[tool_result]}` per VernLLM
+* wire tool message) needs merging back together when an assistant turn
+* requested more than one tool: multiple consecutive user turns would
+* violate that alternation, and Anthropic's API rejects it outright. This
+* merges any run of tool-result-only user messages into one, with all
+* their tool_result blocks combined, the shape Anthropic expects for "here
+* are the results of everything you just asked for."
+*/
+function mergeConsecutiveToolResults$1(messages) {
+	const isToolResultOnly = (m) => m.role === "user" && Array.isArray(m.content) && m.content.length > 0 && m.content.every((b) => b.type === "tool_result");
+	const merged = [];
+	for (const m of messages) {
+		const prev = merged.at(-1);
+		if (isToolResultOnly(m) && prev && isToolResultOnly(prev)) prev.content.push(...m.content);
+		else merged.push(m);
+	}
+	return merged;
+}
+/**
+* Translates one VernLLM wire message (OpenAI-shaped: plain user/assistant
+* turns, an assistant turn with `tool_calls`, or a `tool` turn) into
+* Anthropic's `{ role: 'user' | 'assistant', content }` shape.
+*/
+function toAnthropicMessage(m) {
+	if (m.role === "tool") return {
+		role: "user",
+		content: [{
+			type: "tool_result",
+			tool_use_id: m.tool_call_id,
+			content: m.content,
+			...m.is_error ? { is_error: true } : {}
+		}]
+	};
+	if (m.role === "assistant" && m.tool_calls?.length) {
+		const blocks = [];
+		if (m.content) blocks.push({
+			type: "text",
+			text: m.content
+		});
+		for (const tc of m.tool_calls) {
+			let input;
+			try {
+				input = tc.function.arguments.trim() ? JSON.parse(tc.function.arguments) : {};
+			} catch (cause) {
+				throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) has arguments that are not valid JSON.`, "validation", void 0, void 0, cause);
 			}
+			if (input === null || Array.isArray(input) || typeof input !== "object") throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) arguments must be a JSON object.`, "validation");
+			blocks.push({
+				type: "tool_use",
+				id: tc.id,
+				name: tc.function.name,
+				input
+			});
+		}
+		return {
+			role: "assistant",
+			content: blocks
 		};
-	} } } };
+	}
+	return {
+		role: m.role,
+		content: Array.isArray(m.content) ? toAnthropicContent(m.content) : m.content ?? ""
+	};
 }
 
 //#endregion
@@ -835,6 +1838,122 @@ function toGeminiParts(blocks) {
 		data: block.data
 	} } : { text: block.text });
 }
+/** Maps VernLLM's OpenAI-shaped wire `tool_choice` onto Gemini's `functionCallingConfig`. */
+function toGeminiToolConfig(toolChoice) {
+	if (!toolChoice || toolChoice === "auto") return { functionCallingConfig: { mode: "AUTO" } };
+	if (toolChoice === "none") return { functionCallingConfig: { mode: "NONE" } };
+	if (toolChoice === "required") return { functionCallingConfig: { mode: "ANY" } };
+	return { functionCallingConfig: {
+		mode: "ANY",
+		allowedFunctionNames: [toolChoice.function.name]
+	} };
+}
+/**
+* Translates one VernLLM wire message into a Gemini `contents` entry.
+* Gemini has no separate 'tool' role: a prior assistant tool request
+* becomes a `'model'` turn with `functionCall` parts, and its result
+* becomes a `'user'` turn with `functionResponse` parts.
+*/
+function toGeminiContent(m) {
+	if (m.role === "tool") return {
+		role: "user",
+		parts: [{ functionResponse: {
+			name: m.tool_call_id,
+			response: parseToolResult(m.content)
+		} }]
+	};
+	if (m.role === "assistant" && m.tool_calls?.length) {
+		const parts = [];
+		if (typeof m.content === "string" && m.content) parts.push({ text: m.content });
+		parts.push(...m.tool_calls.map((tc) => ({ functionCall: {
+			name: tc.function.name,
+			args: parseToolArguments(tc.function.arguments, tc.function.name)
+		} })));
+		return {
+			role: "model",
+			parts
+		};
+	}
+	return {
+		role: m.role === "assistant" ? "model" : "user",
+		parts: Array.isArray(m.content) ? toGeminiParts(m.content) : [{ text: m.content ?? "" }]
+	};
+}
+function parseToolArguments(text, toolName) {
+	let parsed;
+	try {
+		parsed = text.trim() ? JSON.parse(text) : {};
+	} catch (cause) {
+		throw new LLMError(`Tool call "${toolName}" arguments are not valid JSON.`, "validation", void 0, void 0, cause);
+	}
+	if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") throw new LLMError(`Tool call "${toolName}" arguments must be a JSON object.`, "validation");
+	return parsed;
+}
+function parseToolResult(text) {
+	try {
+		return text.trim() ? JSON.parse(text) : "";
+	} catch {
+		return text;
+	}
+}
+/**
+* Gemini expects the results of everything the model asked for in one turn
+* to arrive together as multiple `functionResponse` parts on a single
+* `'user'` entry, not as separate consecutive `'user'` entries. The
+* per-wire-message mapping above produces one `'user'` entry per VernLLM
+* wire tool message, so when an assistant turn requested more than one
+* tool, this merges the resulting run of functionResponse-only `'user'`
+* entries back into one.
+*/
+function mergeConsecutiveFunctionResponses(contents) {
+	const isFunctionResponseOnly = (c) => c.role === "user" && c.parts.length > 0 && c.parts.every((p) => "functionResponse" in p);
+	const merged = [];
+	for (const c of contents) {
+		const prev = merged.at(-1);
+		if (isFunctionResponseOnly(c) && prev && isFunctionResponseOnly(prev)) prev.parts.push(...c.parts);
+		else merged.push(c);
+	}
+	return merged;
+}
+/**
+* Builds the Gemini-shaped request from VernLLM's wire params, shared
+* between `create` and `createStream` so both go through identical
+* translation (contents shaping, `responseSchema`/`responseMimeType`
+* mapping, and tool/toolConfig translation all happen exactly once).
+* `abortSignal` is folded into `config` by the caller (`create`/
+* `createStream`), once the request options are available.
+*/
+function buildGeminiRequest(params) {
+	const systemMessage = params.messages.find((m) => m.role === "system");
+	const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "tool");
+	const wantsJson = Boolean(params.response_format);
+	const config = {
+		...params.temperature !== void 0 ? { temperature: params.temperature } : {},
+		maxOutputTokens: params.max_tokens,
+		...systemMessage ? { systemInstruction: { parts: [{ text: systemMessage.content }] } } : {}
+	};
+	if (wantsJson) config.responseMimeType = "application/json";
+	if (params.response_format?.type === "json_schema") {
+		const { schema, description } = params.response_format.json_schema;
+		config.responseSchema = {
+			...schema,
+			...description ? { description } : {}
+		};
+	}
+	if (params.tools?.length) {
+		config.tools = [{ functionDeclarations: params.tools.map((t) => ({
+			name: t.function.name,
+			description: t.function.description,
+			parameters: t.function.parameters
+		})) }];
+		config.toolConfig = toGeminiToolConfig(params.tool_choice);
+	}
+	return {
+		model: params.model,
+		contents: mergeConsecutiveFunctionResponses(conversationMessages.map((m) => toGeminiContent(m))),
+		config
+	};
+}
 /**
 * Wraps a Gemini client so it satisfies the `LLMClient` interface VernLLM
 * uses for OpenAI-compatible APIs. Gemini's shape differs on nearly every
@@ -845,43 +1964,100 @@ function toGeminiParts(blocks) {
 * `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.
 */
 function fromGemini(geminiClient) {
-	return { chat: { completions: { async create(params, options) {
-		const systemMessage = params.messages.find((m) => m.role === "system");
-		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
-		const wantsJson = Boolean(params.response_format);
-		const generationConfig = {
-			temperature: params.temperature,
-			maxOutputTokens: params.max_tokens
-		};
-		if (wantsJson) generationConfig.responseMimeType = "application/json";
-		if (params.response_format?.type === "json_schema") {
-			const { schema, description } = params.response_format.json_schema;
-			generationConfig.responseSchema = {
-				...schema,
-				...description ? { description } : {}
+	return { chat: { completions: {
+		async create(params, options) {
+			const request = buildGeminiRequest(params);
+			request.config = {
+				...request.config,
+				abortSignal: options.signal
 			};
-		}
-		const response = await geminiClient.generateContent({
-			model: params.model,
-			contents: conversationMessages.map((m) => ({
-				role: m.role === "assistant" ? "model" : "user",
-				parts: Array.isArray(m.content) ? toGeminiParts(m.content) : [{ text: m.content }]
-			})),
-			systemInstruction: systemMessage ? { parts: [{ text: systemMessage.content }] } : void 0,
-			generationConfig
-		}, options);
-		const text = response.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("") ?? "";
-		return {
-			choices: [{ message: { content: text } }],
-			usage: {
-				prompt_tokens: response.usageMetadata?.promptTokenCount,
-				completion_tokens: response.usageMetadata?.candidatesTokenCount,
-				total_tokens: response.usageMetadata?.totalTokenCount
+			const response = await geminiClient.generateContent(request);
+			const parts = response.candidates?.[0]?.content?.parts ?? [];
+			const text = parts.map((p) => p.text ?? "").join("");
+			const functionCalls = parts.filter((p) => p.functionCall);
+			let wireToolCalls;
+			if (functionCalls.length) wireToolCalls = functionCalls.map((p) => ({
+				id: p.functionCall.name,
+				type: "function",
+				function: {
+					name: p.functionCall.name,
+					arguments: JSON.stringify(p.functionCall.args ?? {})
+				}
+			}));
+			return {
+				choices: [{ message: {
+					content: text,
+					...wireToolCalls ? { tool_calls: wireToolCalls } : {}
+				} }],
+				usage: {
+					prompt_tokens: response.usageMetadata?.promptTokenCount,
+					completion_tokens: response.usageMetadata?.candidatesTokenCount,
+					total_tokens: response.usageMetadata?.totalTokenCount
+				}
+			};
+		},
+		async *createStream(params, options) {
+			if (!geminiClient.generateContentStream) throw new LLMError("stream: true requires a Gemini client with generateContentStream", "validation");
+			const request = buildGeminiRequest(params);
+			request.config = {
+				...request.config,
+				abortSignal: options.signal
+			};
+			const stream = await geminiClient.generateContentStream(request);
+			let toolCallIndex = 0;
+			let lastUsage;
+			for await (const chunk of stream) {
+				const parts = chunk.candidates?.[0]?.content?.parts ?? [];
+				for (const part of parts) {
+					if (part.text) yield {
+						type: "text-delta",
+						delta: part.text
+					};
+					if (part.functionCall) {
+						yield {
+							type: "tool_call_delta",
+							index: toolCallIndex,
+							id: part.functionCall.name,
+							name: part.functionCall.name,
+							argumentsDelta: JSON.stringify(part.functionCall.args ?? {}),
+							complete: true
+						};
+						toolCallIndex++;
+					}
+				}
+				if (chunk.usageMetadata) lastUsage = chunk.usageMetadata;
 			}
-		};
-	} } } };
+			if (lastUsage) yield {
+				type: "usage",
+				usage: {
+					prompt_tokens: lastUsage.promptTokenCount,
+					completion_tokens: lastUsage.candidatesTokenCount,
+					total_tokens: lastUsage.totalTokenCount
+				}
+			};
+		}
+	} } };
 }
 
 //#endregion
@@ -917,6 +2093,67 @@ function toBedrockContent(blocks) {
 	} } : { text: block.text });
 }
 /**
+* Builds the Converse-shaped request from VernLLM's wire params, shared
+* between `create` and `createStream` so both go through identical
+* translation (system prompt, message shaping, the jsonSchema →
+* forced-single-tool mapping, and the `toolUseSupportedModels` preflight
+* check all happen exactly once).
+*
+* Returns `toolName` alongside the request: when set, the model was forced
+* to call a single synthetic tool standing in for `jsonSchema` output, and
+* both `create` and `createStream` need to know this so they can unwrap
+* that tool call back into plain text content instead of treating it like
+* a real tool call.
+*/
+function buildBedrockRequest(params, toolUseSupportedModels) {
+	const systemMessage = params.messages.find((m) => m.role === "system");
+	const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "tool");
+	const jsonSchema = params.response_format?.type === "json_schema" ? params.response_format.json_schema : void 0;
+	const toolName = jsonSchema?.name.trim();
+	if (jsonSchema && !toolName) throw new LLMError("json_schema.name must not be empty.", "validation");
+	let jsonInstruction;
+	let toolConfig;
+	if (jsonSchema) {
+		const { schema, description, strict } = jsonSchema;
+		toolConfig = {
+			tools: [{ toolSpec: {
+				name: toolName,
+				description,
+				inputSchema: { json: schema },
+				strict
+			} }],
+			toolChoice: { tool: { name: toolName } }
+		};
+	} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
+	else if (params.tools?.length) toolConfig = {
+		tools: params.tools.map((t) => ({ toolSpec: {
+			name: t.function.name,
+			description: t.function.description,
+			inputSchema: { json: t.function.parameters }
+		} })),
+		toolChoice: toBedrockToolChoice(params.tool_choice)
+	};
+	if (jsonSchema && toolUseSupportedModels) {
+		const isSupported = Array.isArray(toolUseSupportedModels) ? toolUseSupportedModels.includes(params.model) : toolUseSupportedModels(params.model);
+		if (!isSupported) throw new LLMError(`Bedrock model "${params.model}" is not listed in toolUseSupportedModels, but jsonSchema structured output requires Converse tool use.`, "validation");
+	}
+	const systemParts = [systemMessage?.content, jsonInstruction].filter((s) => Boolean(s));
+	const request = {
+		modelId: params.model,
+		messages: mergeConsecutiveToolResults(conversationMessages.map((m) => toBedrockMessage(m))),
+		system: systemParts.length ? systemParts.map((text) => ({ text })) : void 0,
+		inferenceConfig: {
+			...params.temperature !== void 0 ? { temperature: params.temperature } : {},
+			maxTokens: params.max_tokens
+		},
+		...toolConfig ? { toolConfig } : {}
+	};
+	return {
+		request,
+		toolName
+	};
+}
+/**
 * Wraps a Bedrock Converse-API client so it satisfies the `LLMClient`
 * interface VernLLM uses for OpenAI/Groq. The Converse API is unified
 * across Bedrock's model families (Anthropic, Titan, Llama, Mistral, etc.),
@@ -936,66 +2173,237 @@ function toBedrockContent(blocks) {
 * `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.
 */
 function fromBedrock(bedrockClient, options) {
 	const toolUseSupportedModels = options?.toolUseSupportedModels;
-	return { chat: { completions: { async create(params, requestOptions) {
-		const systemMessage = params.messages.find((m) => m.role === "system");
-		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
-		const jsonSchema = params.response_format?.type === "json_schema" ? params.response_format.json_schema : void 0;
-		const toolName = jsonSchema?.name.trim();
-		if (jsonSchema && !toolName) throw new LLMError("json_schema.name must not be empty.", "validation");
-		let jsonInstruction;
-		let toolConfig;
-		if (jsonSchema) {
-			const { schema, description, strict } = jsonSchema;
-			toolConfig = {
-				tools: [{ toolSpec: {
-					name: toolName,
-					description,
-					inputSchema: { json: schema },
-					strict
+	return { chat: { completions: {
+		async create(params, requestOptions) {
+			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels);
+			const response = await bedrockClient.converse(request, requestOptions);
+			let text;
+			let wireToolCalls;
+			if (toolName) {
+				const toolUseBlock = response.output?.message?.content?.find((block) => block.toolUse?.name === toolName);
+				text = toolUseBlock?.toolUse ? JSON.stringify(toolUseBlock.toolUse.input) : "";
+			} else {
+				const blocks = response.output?.message?.content ?? [];
+				text = blocks.map((c) => c.text ?? "").join("");
+				const toolUses = blocks.filter((block) => Boolean(block.toolUse));
+				if (toolUses.length) wireToolCalls = toolUses.map((block, i) => {
+					const toolUse = block.toolUse;
+					if (!toolUse.name) throw new LLMError(`Bedrock returned a toolUse block without a name at index ${i}.`, "validation");
+					return {
+						id: toolUse.toolUseId ?? `${toolUse.name}_${i}`,
+						type: "function",
+						function: {
+							name: toolUse.name,
+							arguments: JSON.stringify(toolUse.input ?? {})
+						}
+					};
+				});
+			}
+			return {
+				choices: [{ message: {
+					content: text,
+					...wireToolCalls ? { tool_calls: wireToolCalls } : {}
 				} }],
-				toolChoice: { tool: { name: toolName } }
+				usage: {
+					prompt_tokens: response.usage?.inputTokens,
+					completion_tokens: response.usage?.outputTokens,
+					total_tokens: response.usage?.totalTokens
+				}
+			};
+		},
+		async *createStream(params, requestOptions) {
+			if (!bedrockClient.converseStream) throw new LLMError("stream: true requires a Bedrock client with converseStream", "validation");
+			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels);
+			const { stream } = await bedrockClient.converseStream(request, requestOptions);
+			const blockKinds = new Map();
+			for await (const event of stream) if ("contentBlockStart" in event) {
+				const { contentBlockIndex, start } = event.contentBlockStart;
+				if (start?.toolUse) {
+					const kind = start.toolUse.name === toolName ? "json-tool" : "tool_use";
+					blockKinds.set(contentBlockIndex, kind);
+					if (kind === "tool_use" && !toolName) yield {
+						type: "tool_call_delta",
+						index: contentBlockIndex,
+						id: start.toolUse.toolUseId,
+						name: start.toolUse.name
+					};
+				} else blockKinds.set(contentBlockIndex, "text");
+			} else if ("contentBlockDelta" in event) {
+				const { contentBlockIndex, delta } = event.contentBlockDelta;
+				if (delta && "text" in delta && delta.text !== void 0 && !toolName) yield {
+					type: "text-delta",
+					delta: delta.text
+				};
+				else if (delta && "toolUse" in delta && delta.toolUse?.input !== void 0) {
+					const kind = blockKinds.get(contentBlockIndex);
+					if (kind === "json-tool") yield {
+						type: "text-delta",
+						delta: delta.toolUse.input
+					};
+					else if (!toolName) yield {
+						type: "tool_call_delta",
+						index: contentBlockIndex,
+						argumentsDelta: delta.toolUse.input
+					};
+				}
+			} else if ("metadata" in event && event.metadata.usage) yield {
+				type: "usage",
+				usage: {
+					prompt_tokens: event.metadata.usage.inputTokens,
+					completion_tokens: event.metadata.usage.outputTokens,
+					total_tokens: event.metadata.usage.totalTokens
+				}
 			};
-		} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
-		if (jsonSchema && toolUseSupportedModels) {
-			const isSupported = Array.isArray(toolUseSupportedModels) ? toolUseSupportedModels.includes(params.model) : toolUseSupportedModels(params.model);
-			if (!isSupported) throw new LLMError(`Bedrock model "${params.model}" is not listed in toolUseSupportedModels, but jsonSchema structured output requires Converse tool use.`, "validation");
+			else if ("throttlingException" in event) throw new LLMError(event.throttlingException.message ?? "Bedrock throttled the request mid-stream", "api", 429);
+			else if ("validationException" in event) throw new LLMError(event.validationException.message ?? "Bedrock rejected the request mid-stream", "validation");
+			else if ("internalServerException" in event || "serviceUnavailableException" in event || "modelStreamErrorException" in event) {
+				const detail = "internalServerException" in event && event.internalServerException.message || "serviceUnavailableException" in event && event.serviceUnavailableException.message || "modelStreamErrorException" in event && event.modelStreamErrorException.message || "Bedrock reported a mid-stream error";
+				const status = "modelStreamErrorException" in event && event.modelStreamErrorException.originalStatusCode || "serviceUnavailableException" in event && 503 || 500;
+				throw new LLMError(detail, "api", status);
+			}
 		}
-		const systemParts = [systemMessage?.content, jsonInstruction].filter((s) => Boolean(s));
-		const response = await bedrockClient.converse({
-			modelId: params.model,
-			messages: conversationMessages.map((m) => ({
-				role: m.role,
-				content: Array.isArray(m.content) ? toBedrockContent(m.content) : [{ text: m.content }]
-			})),
-			system: systemParts.length ? systemParts.map((text$1) => ({ text: text$1 })) : void 0,
-			inferenceConfig: {
-				temperature: params.temperature,
-				maxTokens: params.max_tokens
-			},
-			...toolConfig ? { toolConfig } : {}
-		}, requestOptions);
-		let text;
-		if (toolName) {
-			const toolUseBlock = response.output?.message?.content?.find((block) => block.toolUse?.name === toolName);
-			text = toolUseBlock?.toolUse ? JSON.stringify(toolUseBlock.toolUse.input) : "";
-		} else text = response.output?.message?.content?.map((c) => c.text ?? "").join("") ?? "";
-		return {
-			choices: [{ message: { content: text } }],
-			usage: {
-				prompt_tokens: response.usage?.inputTokens,
-				completion_tokens: response.usage?.outputTokens,
-				total_tokens: response.usage?.totalTokens
+	} } };
+}
+/** Maps VernLLM's OpenAI-shaped wire `tool_choice` onto Converse's `toolChoice`. */
+function toBedrockToolChoice(toolChoice) {
+	if (!toolChoice || toolChoice === "auto") return { auto: {} };
+	if (toolChoice === "required") return { any: {} };
+	if (toolChoice === "none") throw new LLMError("'none' is not supported by fromBedrock: Bedrock Converse has no `tool_choice` equivalent to forbidding tool use while tools are still offered. Omit `tools` entirely for this call instead.", "validation");
+	return { tool: { name: toolChoice.function.name } };
+}
+/**
+* Translates one VernLLM wire message into Converse's
+* `{ role: 'user' | 'assistant', content }` shape.
+*/
+function toBedrockMessage(m) {
+	if (m.role === "tool") return {
+		role: "user",
+		content: [{ toolResult: {
+			toolUseId: m.tool_call_id,
+			content: [{ text: m.content }],
+			status: m.is_error ? "error" : "success"
+		} }]
+	};
+	if (m.role === "assistant" && m.tool_calls?.length) {
+		const blocks = [];
+		if (m.content) blocks.push({ text: m.content });
+		for (const tc of m.tool_calls) {
+			let input;
+			if (!tc.function.arguments.trim()) input = {};
+			else try {
+				input = JSON.parse(tc.function.arguments);
+			} catch (cause) {
+				throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) has arguments that are not valid JSON.`, "validation", void 0, void 0, cause);
 			}
+			blocks.push({ toolUse: {
+				toolUseId: tc.id,
+				name: tc.function.name,
+				input
+			} });
+		}
+		return {
+			role: "assistant",
+			content: blocks
 		};
-	} } } };
+	}
+	return {
+		role: m.role,
+		content: Array.isArray(m.content) ? toBedrockContent(m.content) : [{ text: m.content ?? "" }]
+	};
+}
+/**
+* Converse expects the results of everything the model asked for in one
+* turn to arrive together as multiple `toolResult` content blocks on a
+* single `'user'` message, not as separate consecutive `'user'` messages.
+* The per-wire-message mapping above produces one `'user'` message per
+* VernLLM wire tool message, so when an assistant turn requested more than
+* one tool, this merges the resulting run of toolResult-only `'user'`
+* messages back into one.
+*/
+function mergeConsecutiveToolResults(messages) {
+	const isToolResultOnly = (m) => m.role === "user" && m.content.length > 0 && m.content.every((b) => "toolResult" in b);
+	const merged = [];
+	for (const m of messages) {
+		const prev = merged.at(-1);
+		if (isToolResultOnly(m) && prev && isToolResultOnly(prev)) prev.content.push(...m.content);
+		else merged.push(m);
+	}
+	return merged;
 }
 
 //#endregion
 //#region src/adapters/fetch.ts
 /**
+* Wraps a WHATWG `ReadableStream` (what `response.body` is) so it can be
+* consumed with `for await`. Implemented via `getReader()` rather than
+* relying on `ReadableStream` having a native `Symbol.asyncIterator`,
+* that support varies across runtimes/versions, and this works everywhere
+* a `ReadableStream` does.
+*/
+async function* webStreamToAsyncIterable(stream) {
+	const reader = stream.getReader();
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) return;
+			if (value) yield value;
+		}
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {}
+		reader.releaseLock();
+	}
+}
+/** Default `requestStream`: native `fetch`, with the same error/`.status` contract non-streaming errors get. */
+async function defaultRequestStream(url, init) {
+	const res = await fetch(url, init);
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		const err = new Error(`Fetch adapter stream request failed (${res.status}): ${body.slice(0, 500)}`);
+		err.status = res.status;
+		err.headers = res.headers;
+		throw err;
+	}
+	if (!res.body) throw new Error("Fetch adapter stream request received a response with no body.");
+	return webStreamToAsyncIterable(res.body);
+}
+/** Builds the shared `{ method, headers, body? }` request-init for both `create` and `createStream`. */
+async function buildRequestInit(config, params, requestBody) {
+	const url = typeof config.url === "function" ? config.url(params) : config.url;
+	const headers = typeof config.headers === "function" ? await config.headers() : config.headers;
+	const method = config.method ?? "POST";
+	const supportsBody = !["GET", "HEAD"].includes(method.toUpperCase());
+	return {
+		url,
+		method,
+		headers: supportsBody ? {
+			"Content-Type": "application/json",
+			...headers
+		} : { ...headers },
+		...supportsBody ? { body: JSON.stringify(requestBody) } : {}
+	};
+}
+/**
 * A fetch-based escape hatch for providers with no SDK, or where pulling one
 * in isnt worth it. You supply the URL, headers, and two small mapping
 * functions; this handles the HTTP call and slots the result into the same
@@ -1005,41 +2413,99 @@ function fromBedrock(bedrockClient, options) {
 * 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`.
 */
 function fromFetch(config) {
-	return { chat: { completions: { async create(params, options) {
-		const url = typeof config.url === "function" ? config.url(params) : config.url;
-		const headers = typeof config.headers === "function" ? await config.headers() : config.headers;
-		const method = config.method ?? "POST";
-		const request = config.request ?? fetch;
-		const supportsBody = !["GET", "HEAD"].includes(method.toUpperCase());
-		const res = await request(url, {
-			method,
-			headers: supportsBody ? {
-				"Content-Type": "application/json",
-				...headers
-			} : { ...headers },
-			...supportsBody ? { body: JSON.stringify(config.mapRequest(params)) } : {},
-			signal: options.signal
-		});
-		if (!res.ok) {
-			const body = await res.text().catch(() => "");
-			const err = new Error(`Fetch adapter request failed (${res.status}): ${body.slice(0, 500)}`);
-			err.status = res.status;
-			err.headers = res.headers;
-			throw err;
+	return { chat: { completions: {
+		async create(params, options) {
+			const { url, method, headers, body } = await buildRequestInit(config, params, config.mapRequest(params));
+			const request = config.request ?? fetch;
+			const res = await request(url, {
+				method,
+				headers,
+				body,
+				signal: options.signal
+			});
+			if (!res.ok) {
+				const responseBody = await res.text().catch(() => "");
+				const err = new Error(`Fetch adapter request failed (${res.status}): ${responseBody.slice(0, 500)}`);
+				err.status = res.status;
+				err.headers = res.headers;
+				throw err;
+			}
+			const json = await res.json();
+			const { content, usage, toolCalls } = config.mapResponse(json);
+			const wireToolCalls = toolCalls?.length ? toolCalls.map((tc) => ({
+				id: tc.id,
+				type: "function",
+				function: {
+					name: tc.name,
+					arguments: tc.arguments
+				}
+			})) : void 0;
+			return {
+				choices: [{ message: {
+					content,
+					...wireToolCalls ? { tool_calls: wireToolCalls } : {}
+				} }],
+				usage: usage ? {
+					prompt_tokens: usage.promptTokens,
+					completion_tokens: usage.completionTokens,
+					total_tokens: usage.totalTokens
+				} : void 0
+			};
+		},
+		async *createStream(params, options) {
+			if (!config.mapStreamEvent) throw new LLMError("stream: true requires mapStreamEvent to be configured on fromFetch", "validation");
+			if (config.request && !config.requestStream) throw new LLMError("`stream: true` requires `requestStream` to be configured on fromFetch when a custom `request` transport is set. `requestStream` does not fall back to `request` (it needs an async-iterable byte stream, which `RequestLike`'s buffered `ResponseLike` has no way to provide), without it, `stream: true` would silently use plain native `fetch` instead of your configured transport. Add a `requestStream` that opens the same connection your `request` does, or omit `request` if native `fetch` is fine for both.", "validation");
+			const { url, method, headers, body } = await buildRequestInit(config, params, config.mapRequest(params));
+			const requestStream = config.requestStream ?? defaultRequestStream;
+			const parseFrames = config.parseStreamFrames ?? parseSseStream;
+			const byteStream = await requestStream(url, {
+				method,
+				headers,
+				body,
+				signal: options.signal
+			});
+			for await (const event of parseFrames(byteStream)) {
+				if (event === SSE_PING) {
+					yield { type: "ping" };
+					continue;
+				}
+				const wireChunks = config.mapStreamEvent(event);
+				if (!wireChunks) continue;
+				if (Array.isArray(wireChunks)) yield* wireChunks;
+				else yield wireChunks;
+			}
 		}
-		const json = await res.json();
-		const { content, usage } = config.mapResponse(json);
-		return {
-			choices: [{ message: { content } }],
-			usage: usage ? {
-				prompt_tokens: usage.promptTokens,
-				completion_tokens: usage.completionTokens,
-				total_tokens: usage.totalTokens
-			} : void 0
-		};
-	} } } };
+	} } };
 }
 
 //#endregion
@@ -1062,41 +2528,84 @@ function toOpenAIContent(blocks) {
 	});
 }
 /**
-* Adapter for any SDK/client whose `chat.completions.create` already
-* matches the OpenAI wire format: this covers most hosted inference
-* providers, since "OpenAI-compatible" is a de facto standard for chat
-* completion APIs. Almost everything passes straight through untouched,
-* this exists purely so call sites read clearly (`fromMistral(client)` vs
-* handing a Mistral client to something typed for OpenAI) and so a real
-* transformation could be added later, per-provider, without a breaking
-* change.
-*
-* The one thing that isn't a pure passthrough: a `ContentBlock[]`
-* `userContent` is translated into OpenAI's native `image_url` content-part
-* shape, since VernLLM's `ContentBlock` is intentionally provider-agnostic
-* rather than a copy of any one provider's wire format.
-*
-* Not every SDKs own TypeScript types line up exactly with `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.
+* Translates VernLLM's provider-agnostic `messages` (the one part of a
+* request that isn't a pure passthrough for OpenAI-compatible clients) into
+* OpenAI's native wire shape. Shared between `create` and `createStream` so
+* both go through identical message translation.
 */
-function fromOpenAICompatible(client) {
-	const raw = client;
-	return { chat: { completions: { async create(params, options) {
-		const messages = params.messages.map((m) => m.role === "user" && Array.isArray(m.content) ? {
+function toOpenAIMessages(params) {
+	return params.messages.map((m) => {
+		if (m.role === "user" && Array.isArray(m.content)) return {
 			...m,
 			content: toOpenAIContent(m.content)
-		} : m);
-		return raw.chat.completions.create({
-			...params,
-			messages
-		}, options);
-	} } } };
+		};
+		if (m.role === "tool") {
+			const { is_error: _isError,...openAIToolMessage } = m;
+			return openAIToolMessage;
+		}
+		return m;
+	});
+}
+/**
+* Translates one OpenAI-shaped SSE chunk into zero or more `WireStreamChunk`s.
+* A single chunk can carry a text delta, one or more tool-call argument
+* deltas (each keyed by `index`, OpenAI's own convention for streaming
+* parallel tool calls, mirrored directly by VernLLM's `tool_call_delta`
+* shape so accumulation composes without translation), and/or a final
+* usage block (present only when `stream_options.include_usage` is set,
+* which this adapter always sets).
+*/
+function* toWireStreamChunks(chunk) {
+	const delta = chunk.choices?.[0]?.delta;
+	if (delta?.content) yield {
+		type: "text-delta",
+		delta: delta.content
+	};
+	if (delta?.tool_calls?.length) for (const toolCall of delta.tool_calls) yield {
+		type: "tool_call_delta",
+		index: toolCall.index,
+		id: toolCall.id,
+		name: toolCall.function?.name,
+		argumentsDelta: toolCall.function?.arguments
+	};
+	if (chunk.usage) yield {
+		type: "usage",
+		usage: chunk.usage
+	};
+}
+function fromOpenAICompatible(client, options = {}) {
+	const raw = client;
+	const { supportsStreamUsage = true } = options;
+	const rawCreate = raw.chat.completions.create.bind(raw.chat.completions);
+	return { chat: { completions: {
+		async create(params, options$1) {
+			const messages = toOpenAIMessages(params);
+			return raw.chat.completions.create({
+				...params,
+				messages
+			}, options$1);
+		},
+		async *createStream(params, options$1) {
+			const messages = toOpenAIMessages(params);
+			const stream = await rawCreate({
+				...params,
+				messages,
+				stream: true,
+				...supportsStreamUsage ? { stream_options: { include_usage: true } } : {}
+			}, options$1);
+			for await (const chunk of stream) yield* toWireStreamChunks(chunk);
+		}
+	} } };
 }
 /** Groqs SDK matches the OpenAI wire format */
 const fromGroq = 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`.
+*/
 const fromMistral = fromOpenAICompatible;
 /** DeepSeeks API is OpenAI-compatible */
 const fromDeepSeek = fromOpenAICompatible;
@@ -1185,5 +2694,5 @@ const fromAtlasCloud = fromOpenAICompatible;
 const from01AI = fromOpenAICompatible;
 
 //#endregion
-export { CircuitBreaker, ConsoleLogger, InMemoryCacheAdapter, LLMError, NormalizedCacheAdapter, TieredCacheAdapter, VernLLM, 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 { CircuitBreaker, ConsoleLogger, InMemoryCacheAdapter, LLMError, NormalizedCacheAdapter, SSE_PING, TieredCacheAdapter, VernLLM, 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.js.map