vern-llm 1.7.1 → 2.1.0

package/dist/index.js

@@ -2,297 +2,23 @@ import { randomUUID } from "crypto";
 
 //#region src/types/errors.ts
 var LLMError = class extends Error {
-	constructor(message, type, status, issues, cause, retryAfterMs) {
+	constructor(message, type, status, issues, cause, retryAfterMs, code) {
 		super(message);
 		this.type = type;
 		this.status = status;
 		this.issues = issues;
 		this.cause = cause;
 		this.retryAfterMs = retryAfterMs;
+		this.code = code;
 		this.name = "LLMError";
 	}
+	/** Every tool contract failure in one response, when there is more than one. */
+	toolIssues;
 };
 function isLLMError(err) {
 	return err instanceof LLMError;
 }
 
-//#endregion
-//#region src/circuitBreaker.ts
-/**
-* Per retry VernLLM-instance circuit breaker. Tracks consecutive failures across
-* calls. Once the threshold is hit, short-circuits new calls with an
-* LLMError('circuit_open') instead of hitting the provider, until the
-* cooldown elapses and a single trial call is allowed through
-*/
-var CircuitBreaker = class {
-	state = "closed";
-	consecutiveFailures = 0;
-	openedAt = 0;
-	threshold;
-	cooldownMs;
-	/**
-	* True while a single half-open trial call is in flight. Guards against
-	* multiple concurrent callers all treating themselves as "the" trial once
-	* the cooldown elapses
-	*/
-	trialInFlight = false;
-	constructor(options = {}) {
-		this.threshold = options.threshold ?? 5;
-		this.cooldownMs = options.cooldownMs ?? 3e4;
-	}
-	/**
-	* Throws if the circuit is open and the cooldown hasn't elapsed, or if
-	* the circuit is half-open and a trial call is already in flight.
-	* Otherwise, if the circuit just became eligible for a trial (cooldown
-	* elapsed, or half-open with no trial currently running), this call
-	* becomes that trial
-	*/
-	assertClosed() {
-		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");
-			this.state = "half-open";
-			this.trialInFlight = true;
-			return;
-		}
-		if (this.trialInFlight) throw new LLMError("Circuit half-open. A trial request is already in flight. Try again shortly.", "circuit_open");
-		this.trialInFlight = true;
-	}
-	recordSuccess() {
-		this.consecutiveFailures = 0;
-		this.state = "closed";
-		this.trialInFlight = false;
-	}
-	recordFailure() {
-		this.consecutiveFailures += 1;
-		this.trialInFlight = false;
-		if (this.state === "half-open") {
-			this.state = "open";
-			this.openedAt = Date.now();
-			return;
-		}
-		if (this.consecutiveFailures >= this.threshold) {
-			this.state = "open";
-			this.openedAt = Date.now();
-		}
-	}
-	getState() {
-		return this.state;
-	}
-};
-
-//#endregion
-//#region src/internal/vernLLM.utils.ts
-function defaultParseJson(content) {
-	try {
-		return JSON.parse(content);
-	} catch {
-		return void 0;
-	}
-}
-/**
-* 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.
-* Returns undefined when the error is not an object or carries no status
-*/
-function extractStatus(err) {
-	if (!err || typeof err !== "object") return void 0;
-	const error = err;
-	if (typeof error.status === "number") return error.status;
-	if (typeof error.statusCode === "number") return error.statusCode;
-	return void 0;
-}
-function formatSafely(value) {
-	try {
-		return JSON.stringify(value, null, 2) ?? String(value);
-	} catch {
-		try {
-			return String(value);
-		} catch {
-			return "[unprintable error]";
-		}
-	}
-}
-/**
-* Looks inside an unknown thrown value and pulls out a human-readable
-* description of it. Checks the `error` field first (the provider's raw
-* rejection body, JSON-stringified if possible) then falls back to the
-* message` field. Always returns a safe string, even when the thrown value
-* has hostile properties or cannot be serialized normally.
-*/
-function describeError(err) {
-	if (err && typeof err === "object") try {
-		const error = err;
-		if (error.error !== void 0) return formatSafely(error.error);
-		if (typeof error.message === "string") return error.message;
-	} catch {}
-	return formatSafely(err);
-}
-/**
-* 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
-* passed in so either one can cancel the underlying call. If the internal
-* timeout triggers and the underlying operation aborts, the error is
-* converted into an LLMError with type "timeout". External cancellations
-* 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.
-*/
-async function withTimeout(fn, timeoutMs, externalSignal) {
-	const controller = new AbortController();
-	const timer = setTimeout(() => {
-		controller.abort();
-	}, timeoutMs);
-	const signal = externalSignal ? AbortSignal.any([externalSignal, controller.signal]) : controller.signal;
-	try {
-		return await fn(signal);
-	} catch (err) {
-		if (controller.signal.aborted && !externalSignal?.aborted && err instanceof DOMException && err.name === "AbortError") throw new LLMError("Request timed out", "timeout");
-		throw err;
-	} finally {
-		clearTimeout(timer);
-	}
-}
-/**
-* Default cap (ms) for both exponential backoff and honored Retry-After
-* values, so a misbehaving/adversarial Retry-After can't stall a caller
-* indefinitely
-*/
-const DEFAULT_MAX_DELAY_MS = 1e4;
-/**
-* Looks inside an unknown error value for a Retry-After header and
-* converts it to milliseconds. Checks `.headers` first (fetch-style,
-* Headers-like with `.get()`), then `.response.headers` (axios-style,
-* plain object) since different client libraries surface headers
-* differently. Supports both the delta-seconds form ("30") and the
-* HTTP-date form ("Wed, 21 Oct 2015 07:28:00 GMT"). The result is capped
-* at maxDelayMs. Returns undefined when no usable Retry-After is present
-*/
-function extractRetryAfterMs(err, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
-	if (!err || typeof err !== "object") return void 0;
-	const error = err;
-	const headers = error.headers ?? error.response?.headers;
-	if (!headers || typeof headers !== "object") return void 0;
-	const getter = headers;
-	const raw = typeof getter.get === "function" ? getter.get("Retry-After") : Object.entries(headers).find(([name]) => name.toLowerCase() === "retry-after")?.at(1);
-	if (typeof raw !== "string" || raw.trim() === "") return void 0;
-	const trimmed = raw.trim();
-	if (/^\d+$/.test(trimmed)) return Math.max(0, Math.min(Number(trimmed) * 1e3, maxDelayMs));
-	const dateMs = Date.parse(trimmed);
-	if (!Number.isNaN(dateMs)) return Math.max(0, Math.min(dateMs - Date.now(), maxDelayMs));
-	return void 0;
-}
-/** Converts any thrown value into a well-typed LLMError. */
-function normalizeError(error, signal) {
-	if (signal?.aborted) return new LLMError("LLM request aborted", "aborted");
-	if (error instanceof LLMError) return error;
-	const status = extractStatus(error);
-	const retryAfterMs = extractRetryAfterMs(error);
-	if (status !== void 0) return new LLMError("LLM request failed", "api", status, void 0, error, retryAfterMs);
-	return new LLMError("LLM request failed", "unknown", void 0, void 0, error, retryAfterMs);
-}
-/**
-* Exponential backoff with jitter, capped at maxDelayMs.
-* Jitter avoids thundering-herd retries when many callers back off in lockstep,
-* the cap prevents unbounded delays when maxRetries is high
-*/
-function getBackoffDelay(baseDelayMs, attempt, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
-	const exp = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-	return exp / 2 + Math.random() * (exp / 2);
-}
-/**
-* Pauses execution for the given delay before a retry attempt. If an
-* abort signal is provided and it fires while waiting, the pending
-* timer is cancelled immediately and the wait rejects right away with
-* an aborted error instead of continuing to sit idle until the delay
-* would have finished on its own
-*/
-async function waitForRetry(delay, signal) {
-	await new Promise((resolve, reject) => {
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(new LLMError("Operation aborted", "aborted"));
-		};
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, delay);
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
-/**
-* Runs `getResult` after reserving usage, if a `reserveUsage` hook was
-* provided. `refundUsage` fires only if a reservation was actually made.
-* `onRefundError` is called (instead of throwing) whenever a refund attempt
-* itself fails, so a broken refund hook never masks the original error.
-*/
-async function withReservedUsage(params, coalesced, getResult, signal, onRefundError) {
-	if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
-	let reserved = false;
-	try {
-		if (params.reserveUsage) {
-			await params.reserveUsage({
-				coalesced,
-				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,
-				signal
-			});
-		} catch (refundError) {
-			onRefundError(logMessage, refundError);
-		}
-	};
-	if (signal?.aborted) {
-		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
-		throw new LLMError("LLM request aborted", "aborted");
-	}
-	let result;
-	try {
-		result = await getResult();
-	} catch (error) {
-		if (reserved) await refund("[VernLLM] refundUsage failed");
-		throw error;
-	}
-	if (signal?.aborted) {
-		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
-		throw new LLMError("LLM request aborted", "aborted");
-	}
-	return result;
-}
-
-//#endregion
-//#region src/logger.ts
-/**
-* Default logger. `debug` is gated by the `debug` option on VernLLM
-* warn/error always fire since they indicate real problems (retries, cache failures)
-*/
-var ConsoleLogger = class {
-	constructor(debugEnabled) {
-		this.debugEnabled = debugEnabled;
-	}
-	debug(message) {
-		if (this.debugEnabled) console.debug(message);
-	}
-	warn(message) {
-		console.warn(message);
-	}
-	error(message, meta) {
-		console.error(message, meta ?? "");
-	}
-};
-
 //#endregion
 //#region src/types/cache.ts
 /**
@@ -404,91 +130,1495 @@ var TieredCacheAdapter = class {
 };
 
 //#endregion
-//#region src/vernLLM.ts
+//#region src/types/tools.ts
 /**
-* 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.
+* 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.
 */
-var VernLLM = class {
-	client;
-	model;
-	maxRetries;
-	timeoutMs;
-	baseDelayMs;
-	defaultMaxTokens;
-	cache;
-	nonRetryableStatus;
-	inFlight = new Map();
-	parseJson;
-	onUsage;
-	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,
-	* `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
-	*/
-	constructor(options) {
-		this.client = options.client;
-		this.model = options.model;
-		this.maxRetries = options.maxRetries ?? 1;
-		this.timeoutMs = options.timeoutMs ?? 25e3;
-		this.baseDelayMs = options.baseDelayMs ?? 500;
-		this.defaultMaxTokens = options.defaultMaxTokens ?? 1e3;
-		this.cache = options.cache ?? new InMemoryCacheAdapter();
-		this.nonRetryableStatus = options.nonRetryableStatus ?? [
-			400,
-			401,
-			403,
-			404,
-			422
-		];
-		this.parseJson = options.parseJson ?? defaultParseJson;
-		this.onUsage = options.onUsage;
-		this.logger = options.logger ?? new ConsoleLogger(options.debug ?? false);
-		this.breaker = options.circuitBreaker ? new CircuitBreaker(options.circuitBreaker === true ? void 0 : options.circuitBreaker) : void 0;
-	}
+function isToolCallResult(result) {
+	return typeof result === "object" && result !== null && "type" in result && result.type === "tool_calls" && Array.isArray(result.toolCalls);
+}
+
+//#endregion
+//#region src/types/fallback.ts
+/** Tool contract failures are the model ignoring the request, not a sick provider: repeating it elsewhere can't help. */
+const TOOL_CONTRACT_CODES = new Set(["unknown_tool", "duplicate_tool_call_id"]);
+/**
+* The default `fallbackOn` policy. Exported so a caller can wrap rather
+* than replace it, e.g. `fallbackOn: (e, ctx) => myCheck(e) ? 'stop' : defaultFallbackOn(e, ctx)`.
+*/
+const defaultFallbackOn = (error) => {
+	if (error.type === "parse" || error.type === "validation" || error.type === "aborted") return "stop";
+	if (error.type === "quota_exceeded") return "stop";
+	if (error.code && TOOL_CONTRACT_CODES.has(error.code)) return "stop";
+	return "next";
+};
+/**
+* Thrown when the chain gives up, whether because the last target failed
+* or `fallbackOn` chose to stop early. Carries each attempt in order so
+* an outage across providers stays debuggable without reproducing it.
+* Extends `LLMError` so `isLLMError` and any `instanceof LLMError` check
+* still passes, inheriting the last failure's `type` so existing
+* type-based handling keeps working on a fallback-exhausted error too.
+*/
+var FallbackExhaustedError = class extends LLMError {
+	constructor(attempts) {
+		const last = attempts[attempts.length - 1]?.error;
+		super(`${attempts.length} provider${attempts.length === 1 ? "" : "s"} attempted and failed: ${attempts.map((a) => `${a.provider}(${a.error.type})`).join(" then ")}`, last?.type ?? "unknown", last?.status, void 0, last, void 0, "fallback_exhausted");
+		this.attempts = attempts;
+	}
+};
+
+//#endregion
+//#region src/internal/execution/usage.utils.ts
+/**
+* Calls `params.reserveUsage`, if present, mapping any failure to a
+* `quota_exceeded` LLMError (or an aborted error, if the signal fired
+* during reservation). Returns whether a reservation was actually made,
+* so callers know whether a later refund is needed. Shared by
+* `withReservedUsage` and `withReservedUsageForStream`, which differ only
+* in whether `coalesced` is caller-supplied or always `false`.
+*/
+async function reserve(params, coalesced, signal) {
+	if (!params.reserveUsage) return false;
+	try {
+		await params.reserveUsage({
+			coalesced,
+			signal
+		});
+		return 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);
+	}
+}
+/**
+* Builds a `(logMessage) => Promise<void>` refund function bound to the
+* given hooks/coalesced/signal, reporting (instead of throwing) any error
+* the refund hook itself raises, so a broken refund hook never masks the
+* original error it was called to clean up after.
+*/
+function makeRefund(params, coalesced, signal, onRefundError) {
+	return async (logMessage) => {
+		try {
+			await params.refundUsage?.({
+				coalesced,
+				signal
+			});
+		} catch (refundError) {
+			onRefundError(logMessage, refundError);
+		}
+	};
+}
+/**
+* Runs `getResult` after reserving usage, if a `reserveUsage` hook was
+* provided. `refundUsage` fires only if a reservation was actually made.
+* `onRefundError` is called (instead of throwing) whenever a refund attempt
+* itself fails, so a broken refund hook never masks the original error.
+*/
+async function withReservedUsage(params, coalesced, getResult, signal, onRefundError) {
+	if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+	const reserved = await reserve(params, coalesced, signal);
+	const refund = makeRefund(params, coalesced, signal, onRefundError);
+	if (signal?.aborted) {
+		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
+		throw new LLMError("LLM request aborted", "aborted");
+	}
+	let result;
+	try {
+		result = await getResult();
+	} catch (error) {
+		if (reserved) await refund("[VernLLM] refundUsage failed");
+		throw error;
+	}
+	if (signal?.aborted) {
+		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
+		throw new LLMError("LLM request aborted", "aborted");
+	}
+	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");
+	const reserved = await reserve(params, false, signal);
+	const refund = makeRefund(params, false, signal, onRefundError);
+	if (signal?.aborted) {
+		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
+		throw new LLMError("LLM request aborted", "aborted");
+	}
+	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
+	};
+}
+
+//#endregion
+//#region src/internal/cache/replay.utils.ts
+/**
+* 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/internal/cache/cacheOrchestrator.ts
+/**
+* Owns cache key resolution, cache reads/writes, and in-flight coalescing
+* for concurrent misses on the same key. Doesn't know about `CallExecutor`,
+* retries, or providers at all: `fn`/`openStream` are opaque callbacks
+* (`VernLLM.cachedCall` passes `() => this.call(...)`), so this class only
+* needs the cache adapter and a logger. Extracted from `VernLLM` since
+* caching and per-target call mechanics are independent concerns that
+* happened to live on the same class.
+*/
+var CacheOrchestrator = class {
+	inFlight = new Map();
+	constructor(cache, logger) {
+		this.cache = cache;
+		this.logger = logger;
+	}
 	/** Resolves a cache key through the adapter when it supports normalization. */
 	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.
+	* Removes a cached response by key when the configured cache adapter
+	* supports deletion. Cache invalidation is the caller's responsibility;
+	* only the application knows when cached data is stale.
+	*/
+	async deleteCache(key) {
+		if (!this.cache.delete) return;
+		await this.cache.delete(await this.resolveCacheKey(key));
+	}
+	/** Logs a failed refundUsage attempt via the configured logger. */
+	logRefundError(logMessage, error) {
+		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
+	}
+	/**
+	* Internal cache primitive around caller-supplied logic. Concurrent misses
+	* for the same `cacheKey` share a single in-flight call, avoiding cache
+	* stampedes.
+	*
+	* Backs the public `VernLLM.cachedCall()`, which always composes this
+	* with `call()` so cached results get the same retry/timeout/
+	* circuit-breaker guarantees as any other LLM call.
+	*
+	* @param params `cacheKey`, `ttl`, `fn` (the work to run on a cache
+	* miss, typically `() => this.call(...)`), and optional
+	* `reserveUsage`/`refundUsage`/`signal`. See `InternalCacheParams`.
+	* @returns The cached value on a hit, or the result of `fn()` on a miss.
+	*/
+	async runCached(params) {
+		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) return cached.value;
+		const existing = this.inFlight.get(resolvedKey);
+		if (existing) return withReservedUsage(resolvedParams, true, () => existing, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+		return this.registerTrigger(resolvedParams);
+	}
+	/** Starts the shared fn() call for a cache miss and tracks it in the in-flight map until it settles. */
+	registerTrigger(params) {
+		const resultPromise = withReservedUsage(params, false, () => this.runAndCache(params), params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+		this.inFlight.set(params.cacheKey, resultPromise);
+		resultPromise.catch(() => {}).finally(() => {
+			this.inFlight.delete(params.cacheKey);
+		});
+		return resultPromise;
+	}
+	/** Runs `fn` and writes its result to the cache. */
+	async runAndCache(params) {
+		const result = await params.fn();
+		try {
+			await this.cache.set(params.cacheKey, result, params.ttl);
+		} catch (error) {
+			this.logger.error("[VernLLM] cache write failed", { message: error instanceof Error ? error.message : "unknown" });
+		}
+		return result;
+	}
+	/**
+	* 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 in-flight map non-streaming `runCached` uses, so
+	*   streaming and non-streaming calls 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));
+			finalResult.catch(() => {});
+			return {
+				chunks: buildReplayChunksFromPromise(finalResult, hasTools),
+				finalResult
+			};
+		}
+		return this.registerStreamTrigger(resolvedParams);
+	}
+	/**
+	* Opens the shared stream for a cache miss and tracks its settled value
+	* in the in-flight map until it resolves or rejects. Writes to the cache
+	* on success only, matching `runAndCache`.
+	*
+	* Registers the in-flight promise synchronously, before anything async
+	* runs, so a concurrent `cachedCall` for the same key always sees it in
+	* time to join instead of triggering its own stream. Settlement is
+	* wired onto the whole `withReservedUsageForStream` call rather than a
+	* line inside its callback, so any failure point (reserving usage,
+	* opening the stream, or the stream itself) reliably settles the
+	* in-flight entry instead of leaving it stuck.
+	*/
+	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;
+	}
+};
+
+//#endregion
+//#region src/circuitBreaker.ts
+function newBucket() {
+	return {
+		state: "closed",
+		consecutiveFailures: 0,
+		openedAt: 0,
+		trialInFlight: false
+	};
+}
+/** Key a bucket lookup falls into when the call omitted `model` under `isolateByModel`. */
+const UNLABELED_MODEL = "";
+/**
+* Per retry VernLLM-instance circuit breaker. Tracks consecutive failures across
+* calls. Once the threshold is hit, short-circuits new calls with an
+* LLMError('circuit_open') instead of hitting the provider, until the
+* cooldown elapses and a single trial call is allowed through
+*/
+var CircuitBreaker = class {
+	threshold;
+	cooldownMs;
+	onStateChange;
+	isolateByModel;
+	sharedBucket = newBucket();
+	bucketsByModel = new Map();
+	constructor(options = {}) {
+		this.threshold = options.threshold ?? 5;
+		this.cooldownMs = options.cooldownMs ?? 3e4;
+		this.onStateChange = options.onStateChange;
+		this.isolateByModel = options.isolateByModel ?? false;
+	}
+	/** Returns the bucket for a model if one already exists, without allocating. */
+	lookupBucket(model) {
+		if (!this.isolateByModel) return this.sharedBucket;
+		const key = model ?? UNLABELED_MODEL;
+		return this.bucketsByModel.get(key);
+	}
+	/** Creates and stores a bucket for a model when the first mutation needs one. */
+	ensureBucketFor(model) {
+		if (!this.isolateByModel) return this.sharedBucket;
+		const key = model ?? UNLABELED_MODEL;
+		let bucket = this.bucketsByModel.get(key);
+		if (!bucket) {
+			bucket = newBucket();
+			this.bucketsByModel.set(key, bucket);
+		}
+		return bucket;
+	}
+	/** Every state mutation routes through here, so `onStateChange` fires exactly once per real change. */
+	transition(bucket, to, model) {
+		if (to === bucket.state) return;
+		const from = bucket.state;
+		bucket.state = to;
+		this.onStateChange?.(from, to, bucket.consecutiveFailures, model);
+	}
+	/**
+	* Throws if the circuit is open and the cooldown hasn't elapsed, or if
+	* the circuit is half-open and a trial call is already in flight.
+	* Otherwise, if the circuit just became eligible for a trial (cooldown
+	* elapsed, or half-open with no trial currently running), this call
+	* becomes that trial
+	*/
+	assertClosed(model) {
+		const bucket = this.ensureBucketFor(model);
+		if (bucket.state === "closed") return;
+		if (bucket.state === "open") {
+			const elapsed = Date.now() - bucket.openedAt;
+			if (elapsed < this.cooldownMs) throw new LLMError(`Circuit open, provider has failed ${bucket.consecutiveFailures} times in a row. Retry in ${Math.ceil((this.cooldownMs - elapsed) / 1e3)}s.`, "circuit_open");
+			bucket.trialInFlight = true;
+			this.transition(bucket, "half-open", model);
+			return;
+		}
+		if (bucket.trialInFlight) throw new LLMError("Circuit half-open. A trial request is already in flight. Try again shortly.", "circuit_open");
+		bucket.trialInFlight = true;
+	}
+	recordSuccess(model) {
+		const bucket = this.lookupBucket(model);
+		if (!bucket) return;
+		bucket.consecutiveFailures = 0;
+		bucket.trialInFlight = false;
+		this.transition(bucket, "closed", model);
+		if (this.isolateByModel && bucket.state === "closed" && bucket.consecutiveFailures === 0) this.bucketsByModel.delete(model ?? UNLABELED_MODEL);
+	}
+	recordFailure(model) {
+		const bucket = this.ensureBucketFor(model);
+		bucket.consecutiveFailures += 1;
+		bucket.trialInFlight = false;
+		if (bucket.state === "half-open") {
+			bucket.openedAt = Date.now();
+			this.transition(bucket, "open", model);
+			return;
+		}
+		if (bucket.consecutiveFailures >= this.threshold) {
+			bucket.openedAt = Date.now();
+			this.transition(bucket, "open", model);
+		}
+	}
+	/**
+	* With `isolateByModel` off (the default), `model` is ignored and the
+	* one shared circuit's state is returned, unchanged from every version
+	* before this option existed. With `isolateByModel` on, returns that
+	* model's own state, `'closed'` for a model never seen yet, same as a
+	* fresh breaker.
+	*/
+	getState(model) {
+		return this.lookupBucket(model)?.state ?? "closed";
+	}
+};
+
+//#endregion
+//#region src/internal/circuitBreaker.utils.ts
+/**
+* Builds a `(event) => void` reporter that no-ops when `onEvent` is unset,
+* and otherwise calls it, swallowing and logging any error the handler
+* throws so a broken `onEvent` can't break the call that triggered it.
+* Shared by `buildCircuitBreaker` (which needs to report before any
+* executor exists) and `CallExecutor.reportEvent`, kept independent of the
+* executor for that reason.
+*/
+function makeEventReporter(onEvent, logger) {
+	return (event) => {
+		if (!onEvent) return;
+		try {
+			onEvent(event);
+		} catch (error) {
+			logger.error("[VernLLM] onEvent failed", { message: error instanceof Error ? error.message : "unknown" });
+		}
+	};
+}
+/**
+* Builds the optional circuit breaker for one provider target, wiring its
+* `onStateChange` to emit a `circuit_state` event and chain any
+* caller-supplied `onStateChange`. Returns `undefined` when
+* `circuitBreakerOption` is falsy, matching the option's own semantics.
+*
+* Lives outside `CallExecutor` (and outside `VernLLM`, once this were
+* inlined) because the breaker has to exist *before* the executor it's
+* passed into, so its construction can't be an executor concern.
+* `onEvent` is called directly rather than through the executor for the
+* same reason: nothing executor-shaped exists yet at this point.
+*
+* Takes the specific fields it needs (rather than a full `VernLLMOptions`)
+* so it works identically for the primary target and for each fallback
+* target, which carry their own `circuitBreaker` override alongside the
+* shared `onEvent`.
+*/
+function buildCircuitBreaker(circuitBreakerOption, providerName, defaultModel, onEvent, logger) {
+	if (!circuitBreakerOption) return void 0;
+	const breakerOptions = typeof circuitBreakerOption === "object" ? circuitBreakerOption : void 0;
+	const userOnStateChange = breakerOptions?.onStateChange;
+	const reportEvent = makeEventReporter(onEvent, logger);
+	return new CircuitBreaker({
+		...breakerOptions,
+		onStateChange: (from, to, consecutiveFailures, model) => {
+			reportEvent({
+				kind: "circuit_state",
+				provider: providerName,
+				model: model ?? defaultModel,
+				from,
+				to,
+				consecutiveFailures
+			});
+			if (!userOnStateChange) return;
+			try {
+				userOnStateChange(from, to, consecutiveFailures, model);
+			} catch (error) {
+				logger.error("[VernLLM] circuitBreaker.onStateChange failed", { message: error instanceof Error ? error.message : "unknown" });
+			}
+		}
+	});
+}
+
+//#endregion
+//#region src/internal/execution/retry.utils.ts
+/**
+* Default cap (ms) for both exponential backoff and honored Retry-After
+* values, so a misbehaving/adversarial Retry-After can't stall a caller
+* indefinitely
+*/
+const DEFAULT_MAX_DELAY_MS = 1e4;
+/**
+* `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;
+/**
+* Resolves a timeout value to the number `setTimeout` should actually use,
+* or `undefined` when the timeout should be treated as disabled (0,
+* negative, or `Infinity`). Returning the resolved value directly, rather
+* than a boolean, lets callers narrow `number | undefined` to `number`
+* without an `as number` cast.
+*/
+function resolveActiveTimeoutMs(ms) {
+	return !ms || ms <= 0 || ms === Infinity ? void 0 : ms;
+}
+/** 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
+* passed in so either one can cancel the underlying call. If the internal
+* timeout triggers and the underlying operation aborts, the error is
+* converted into an LLMError with type "timeout". External cancellations
+* 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 activeTimeoutMs = resolveActiveTimeoutMs(timeoutMs);
+	const timer = activeTimeoutMs === void 0 ? void 0 : setTimeout(() => {
+		controller.abort();
+	}, clampTimeoutMs(activeTimeoutMs));
+	const signal = externalSignal ? AbortSignal.any([externalSignal, controller.signal]) : controller.signal;
+	try {
+		return await fn(signal);
+	} catch (err) {
+		if (controller.signal.aborted && !externalSignal?.aborted && err instanceof DOMException && err.name === "AbortError") throw new LLMError("Request timed out", "timeout");
+		throw err;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* 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) {
+	const activeTimeoutMs = resolveActiveTimeoutMs(timeoutMs);
+	if (activeTimeoutMs === void 0) return next();
+	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);
+		});
+	});
+}
+/**
+* Looks inside an unknown error value for a Retry-After header and
+* converts it to milliseconds. Checks `.headers` first (fetch-style,
+* Headers-like with `.get()`), then `.response.headers` (axios-style,
+* plain object) since different client libraries surface headers
+* differently. Supports both the delta-seconds form ("30") and the
+* HTTP-date form ("Wed, 21 Oct 2015 07:28:00 GMT"). The result is capped
+* at maxDelayMs. Returns undefined when no usable Retry-After is present
+*/
+function extractRetryAfterMs(err, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
+	if (!err || typeof err !== "object") return void 0;
+	const error = err;
+	const headers = error.headers ?? error.response?.headers;
+	if (!headers || typeof headers !== "object") return void 0;
+	const getter = headers;
+	const raw = typeof getter.get === "function" ? getter.get("Retry-After") : Object.entries(headers).find(([name]) => name.toLowerCase() === "retry-after")?.at(1);
+	if (typeof raw !== "string" || raw.trim() === "") return void 0;
+	const trimmed = raw.trim();
+	if (/^\d+$/.test(trimmed)) return Math.max(0, Math.min(Number(trimmed) * 1e3, maxDelayMs));
+	const dateMs = Date.parse(trimmed);
+	if (!Number.isNaN(dateMs)) return Math.max(0, Math.min(dateMs - Date.now(), maxDelayMs));
+	return void 0;
+}
+/**
+* Exponential backoff with jitter, capped at maxDelayMs.
+* Jitter avoids thundering-herd retries when many callers back off in lockstep,
+* the cap prevents unbounded delays when maxRetries is high
+*/
+function getBackoffDelay(baseDelayMs, attempt, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
+	const exp = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+	return exp / 2 + Math.random() * (exp / 2);
+}
+/**
+* Pauses execution for the given delay before a retry attempt. If an
+* abort signal is provided and it fires while waiting, the pending
+* timer is cancelled immediately and the wait rejects right away with
+* an aborted error instead of continuing to sit idle until the delay
+* would have finished on its own
+*/
+async function waitForRetry(delay, signal) {
+	if (signal?.aborted) throw new LLMError("Operation aborted", "aborted");
+	await new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new LLMError("Operation aborted", "aborted"));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, delay);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+//#endregion
+//#region src/internal/execution/errors.utils.ts
+/**
+* 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,
+* 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) {
+	if (!err || typeof err !== "object") return void 0;
+	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) {
+	try {
+		return JSON.stringify(value, null, 2) ?? String(value);
+	} catch {
+		try {
+			return String(value);
+		} catch {
+			return "[unprintable error]";
+		}
+	}
+}
+/**
+* Looks inside an unknown thrown value and pulls out a human-readable
+* description of it. Checks the `error` field first (the provider's raw
+* rejection body, JSON-stringified if possible) then falls back to the
+* message` field. Always returns a safe string, even when the thrown value
+* has hostile properties or cannot be serialized normally.
+*/
+function describeError(err) {
+	if (err && typeof err === "object") try {
+		const error = err;
+		if (error.error !== void 0) return formatSafely(error.error);
+		if (typeof error.message === "string") return error.message;
+	} catch {}
+	return formatSafely(err);
+}
+/** Converts any thrown value into a well-typed LLMError. */
+function normalizeError(error, signal) {
+	if (signal?.aborted) return new LLMError("LLM request aborted", "aborted");
+	if (error instanceof LLMError) {
+		if (error.status === 429 && error.code === void 0) error.code = "provider_rate_limited";
+		return error;
+	}
+	const status = extractStatus(error);
+	const retryAfterMs = extractRetryAfterMs(error);
+	if (status !== void 0) return new LLMError("LLM request failed", "api", status, void 0, error, retryAfterMs, status === 429 ? "provider_rate_limited" : void 0);
+	return new LLMError("LLM request failed", "unknown", void 0, void 0, error, retryAfterMs);
+}
+
+//#endregion
+//#region src/internal/execution/parse.utils.ts
+/** Default `parseJson`: `JSON.parse` wrapped in try/catch, returning `undefined` on failure. */
+function defaultParseJson(content) {
+	try {
+		return JSON.parse(content);
+	} catch {
+		return void 0;
+	}
+}
+
+//#endregion
+//#region src/internal/execution/wire.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
+		};
+	});
+}
+
+//#endregion
+//#region src/internal/execution/requestBuilder.ts
+/**
+* Builds the wire request object for one call, applying per-instance
+* defaults (model, max tokens, temperature) and per-call overrides.
+* Owns every validation that depends only on shape, not on execution:
+* history alternation, duplicate/empty tool lists, `toolChoice` naming a
+* real tool. Has no knowledge of retry, timeouts, or the breaker, only
+* the three defaults a `FallbackTarget` can override per-target (see the
+* `defaultMaxTokens`/`defaultTemperature` overrides in the fallback
+* design), which is what keeps it separable from `CallExecutor`.
+*/
+var RequestBuilder = class {
+	model;
+	defaultMaxTokens;
+	defaultTemperature;
+	constructor(options) {
+		this.model = options.model;
+		this.defaultMaxTokens = options.defaultMaxTokens;
+		this.defaultTemperature = options.defaultTemperature;
+	}
+	/** Applies per-call defaults and shapes params into the client's request object. */
+	build(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 && 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 !== 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.flatMap((turn) => this.turnToWireMessages(turn)),
+				{
+					role: "user",
+					content: userContent
+				}
+			]
+		};
+		return {
+			useJson,
+			model,
+			request
+		};
+	}
+	/**
+	* Validates `history` alternates user/assistant turns, since providers
+	* like Anthropic/Gemini reject or mishandle consecutive same-role turns.
+	*/
+	validateHistory(history) {
+		let previousTurn;
+		for (const [index, turn] of history.entries()) {
+			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 (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");
+	}
+	/** 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
+	* falls back to the looser `json_object` mode when JSON output is
+	* requested, or no format at all for plain text responses.
+	*/
+	buildResponseFormat(jsonSchema, useJson) {
+		if (jsonSchema) return {
+			type: "json_schema",
+			json_schema: {
+				name: jsonSchema.name,
+				schema: jsonSchema.schema,
+				strict: jsonSchema.strict ?? true,
+				description: jsonSchema.description
+			}
+		};
+		return useJson ? { type: "json_object" } : void 0;
+	}
+};
+
+//#endregion
+//#region src/internal/execution/streamAccumulator.ts
+/**
+* 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
+* `finalize` 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, alongside the one `onStreamFailure` call for them. The
+* second catch, around `finalize`, does not re-normalize or re-report,
+* since `finalize`'s caller (`finalizeResponse`) already does both
+* internally.
+*/
+function buildStreamResult(iterator, first, options) {
+	const { requestId, model, providerName, isFallback, chunkIdleTimeoutMs, streamController, logger, signal } = options;
+	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;
+				logger.warn(`[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,
+						provider: providerName,
+						usedFallback: isFallback
+					};
+					push({
+						type: "usage",
+						usage
+					});
+				}
+				result = await withChunkIdleTimeout(() => iterator.next(), chunkIdleTimeoutMs, () => streamController.abort(), logger);
+			}
+		} catch (error) {
+			try {
+				await iterator.return?.();
+			} catch {}
+			streamController.abort();
+			const normalized = normalizeError(error, signal);
+			try {
+				options.onStreamFailure(normalized, usage);
+			} catch {}
+			fail(normalized);
+			rejectFinal(normalized);
+			return;
+		}
+		finish();
+		try {
+			options.onStreamSuccess(usage);
+		} catch {}
+		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 = options.finalize(textAcc, wireToolCalls, usage);
+			resolveFinal(finalized);
+		} catch (error) {
+			rejectFinal(error);
+		}
+	})();
+	return {
+		chunks,
+		finalResult
+	};
+}
+
+//#endregion
+//#region src/internal/execution/callExecutor.ts
+/**
+* Everything one provider target needs to attempt a call: request
+* building, retry with backoff, the per-target breaker, the per-target
+* limiter. Never exported publicly. `VernLLM` holds one per target and
+* owns the fallback loop and caching on top.
+*/
+var CallExecutor = class {
+	maxRetries;
+	timeoutMs;
+	chunkIdleTimeoutMs;
+	baseDelayMs;
+	nonRetryableStatus;
+	parseJson;
+	logger;
+	redact;
+	onUsage;
+	onUsageFailure;
+	reportEvent;
+	breaker;
+	limiter;
+	isFallback;
+	requestBuilder;
+	constructor(providerName, client, model, options) {
+		this.providerName = providerName;
+		this.client = client;
+		this.model = model;
+		this.maxRetries = options.maxRetries;
+		this.timeoutMs = options.timeoutMs;
+		this.chunkIdleTimeoutMs = options.chunkIdleTimeoutMs;
+		this.baseDelayMs = options.baseDelayMs;
+		this.nonRetryableStatus = options.nonRetryableStatus;
+		this.parseJson = options.parseJson ?? defaultParseJson;
+		this.logger = options.logger;
+		this.redact = options.redact;
+		this.onUsage = options.onUsage;
+		this.onUsageFailure = options.onUsageFailure;
+		this.reportEvent = makeEventReporter(options.onEvent, this.logger);
+		this.breaker = options.breaker;
+		this.limiter = options.limiter;
+		this.isFallback = options.isFallback ?? false;
+		this.requestBuilder = new RequestBuilder({
+			model,
+			defaultMaxTokens: options.defaultMaxTokens,
+			defaultTemperature: options.defaultTemperature
+		});
+	}
+	getCircuitState(model) {
+		return this.breaker?.getState(model);
+	}
+	/**
+	* Throws if the breaker is open for this target/model, exactly like the
+	* check `run`/`runStream` used to make internally. Exposed so `VernLLM`
+	* can gate on it before reserving usage, avoiding a reserve-then-refund
+	* round trip on a call that was never going to be attempted. `assertClosed`
+	* has a stateful side effect (claiming a half-open trial slot), so it must
+	* run exactly once per logical call: `run`/`runStream` no longer call it
+	* themselves, this is now the only call site.
+	*/
+	assertBreakerClosed(model) {
+		this.breaker?.assertClosed(model ?? this.model);
+	}
+	/**
+	* Runs a single logical call against this target: retry with backoff,
+	* normalized error on exhaustion. Mirrors the old `VernLLM.call`'s
+	* non-streaming branch, minus cache/usage-reservation and the breaker
+	* check, which stay one layer up since they aren't per-target concerns
+	* (see `assertBreakerClosed`).
+	*/
+	async run(params, requestId, onAttempt) {
+		const model = params.model ?? this.model;
+		try {
+			return await this.retryWithBackoff((attempt) => this.executeCall(params, requestId, attempt), requestId, model, params.signal, onAttempt);
+		} catch (error) {
+			const normalized = normalizeError(error, params.signal);
+			if (this.countsTowardBreaker(normalized)) this.breaker?.recordFailure(model);
+			this.logger.debug(`[VernLLM:${requestId}] error:\n${this.redactText(describeError(error))}`);
+			throw normalized;
+		}
+	}
+	/** Streaming counterpart to `run`. Mirrors the old streaming branch of `VernLLM.call`. */
+	async runStream(params, requestId, onAttempt) {
+		const model = params.model ?? this.model;
+		try {
+			return await this.retryWithBackoff((attempt) => this.executeStreamCall(params, requestId, attempt), requestId, model, params.signal, onAttempt);
+		} catch (error) {
+			const normalized = normalizeError(error, params.signal);
+			if (this.countsTowardBreaker(normalized)) this.breaker?.recordFailure(model);
+			this.logger.debug(`[VernLLM:${requestId}] stream-open error:\n${this.redactText(describeError(error))}`);
+			throw normalized;
+		}
+	}
+	/**
+	* 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.requestBuilder.build(params);
+		let release;
+		if (this.limiter) {
+			const acquired = await this.limiter.acquire(this.limiter.estimate(request), params.signal);
+			release = acquired.release;
+			if (acquired.waitedMs > 0) this.reportEvent({
+				kind: "rate_limited",
+				requestId,
+				provider: this.providerName,
+				model,
+				waitedMs: acquired.waitedMs,
+				reason: acquired.reason ?? "rpm"
+			});
+		}
+		try {
+			const response = await withTimeout((attemptSignal) => this.client.chat.completions.create(request, { signal: attemptSignal }), this.timeoutMs, params.signal);
+			const usage = this.extractUsage(response, requestId, model);
+			release?.(this.actualTokensFor(usage));
+			release = void 0;
+			const rawContent = response.choices?.[0]?.message?.content;
+			const wireToolCalls = response.choices?.[0]?.message?.tool_calls;
+			return this.finalizeResponse(rawContent, wireToolCalls, params, useJson, model, usage, requestId, attempt);
+		} finally {
+			release?.();
+		}
+	}
+	/** Applies `redact` (if configured); otherwise returns `text` unchanged. */
+	redactText(text) {
+		return this.redact ? this.redact(text) : text;
+	}
+	/**
+	* Applies `redact` (if configured) to whatever the debug log is about
+	* to show: real content when there is any, otherwise the tool-call
+	* placeholder, which carries no user data and passes through
+	* `redact` unchanged in practice but is included for a caller whose
+	* `redact` does something structural (e.g. adding a marker) rather
+	* than just scrubbing PII.
+	*/
+	redactedOutput(content, wireToolCalls) {
+		return this.redactText(content ?? `[${wireToolCalls?.length ?? 0} tool call(s)]`);
+	}
+	/**
+	* 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.
 	*
-	* @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.
+	* Normalizes and reports usage failure on error itself, so every caller
+	* gets identical error handling without duplicating it.
 	*/
-	async call(params) {
-		this.breaker?.assertClosed();
-		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
-		const requestId = params.requestId ?? randomUUID();
-		return withReservedUsage(params, false, async () => {
-			try {
-				return await this.retryWithBackoff(() => this.executeCall(params, requestId), 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)}`);
-				throw normalized;
+	finalizeResponse(rawContent, wireToolCalls, params, useJson, model, 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${this.redactedOutput(content, wireToolCalls).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(model);
+				this.reportUsage(usage);
+				return {
+					type: "tool_calls",
+					toolCalls,
+					...content ? { content } : {}
+				};
 			}
-		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+			const textContent = content ?? "";
+			if (!useJson) {
+				this.breaker?.recordSuccess(model);
+				this.reportUsage(usage);
+				return params.tools ? {
+					type: "content",
+					content: textContent
+				} : textContent;
+			}
+			const result = this.parseAndValidate(textContent, params.schema);
+			this.breaker?.recordSuccess(model);
+			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.requestBuilder.build(params);
+		const completions = this.client.chat.completions;
+		if (!completions.createStream) throw new LLMError("stream: true requires a client/adapter with createStream", "validation");
+		const createStream = completions.createStream.bind(completions);
+		let release;
+		if (this.limiter) {
+			const acquired = await this.limiter.acquire(this.limiter.estimate(request), params.signal);
+			release = acquired.release;
+			if (acquired.waitedMs > 0) this.reportEvent({
+				kind: "rate_limited",
+				requestId,
+				provider: this.providerName,
+				model,
+				waitedMs: acquired.waitedMs,
+				reason: acquired.reason ?? "rpm"
+			});
+		}
+		const streamController = new AbortController();
+		const combinedExternal = params.signal ? AbortSignal.any([params.signal, streamController.signal]) : streamController.signal;
+		try {
+			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");
+			const releaseAtOpen = release;
+			const result = buildStreamResult(iterator, first, {
+				requestId,
+				model,
+				providerName: this.providerName,
+				isFallback: this.isFallback,
+				chunkIdleTimeoutMs: params.chunkIdleTimeoutMs ?? this.chunkIdleTimeoutMs,
+				streamController,
+				logger: this.logger,
+				signal: params.signal,
+				onStreamSuccess: (usage) => {
+					this.breaker?.recordSuccess(model);
+					releaseAtOpen?.(this.actualTokensFor(usage));
+				},
+				onStreamFailure: (normalized, usage) => {
+					if (normalized.type === "timeout") this.breaker?.recordFailure(model);
+					if (usage && normalized.type !== "aborted") this.reportUsageFailure(usage, normalized, attempt, true);
+					releaseAtOpen?.(this.actualTokensFor(usage));
+				},
+				finalize: (textAcc, wireToolCalls, usage) => this.finalizeResponse(textAcc, wireToolCalls, params, useJson, model, usage, requestId, attempt)
+			});
+			release = void 0;
+			return result;
+		} finally {
+			release?.();
+		}
+	}
+	/**
+	* Checks every `ToolCall` against the `tools` that were offered, catching
+	* a hallucinated tool name and a duplicate call id before either reaches
+	* the application's dispatch table, then runs each tool's
+	* `argumentsSchema`, if present.
+	*
+	* Contract failures (unknown name, duplicate id) are collected across
+	* every call and thrown together, since retrying a request that already
+	* has these errors cannot help (`shouldRetry` excludes them by `code`)
+	* and a caller fixing them wants to see every one, not just the first.
+	* Schema failures keep the original single-error, `type: 'validation'`
+	* shape rather than being folded into the aggregate, since they're a
+	* distinct failure kind from the contract failures above (also excluded
+	* from retry, by `type` rather than `code`; see `shouldRetry`).
+	*/
+	validateToolCallArguments(toolCalls, tools) {
+		const known = new Map(tools.map((t) => [t.name, t]));
+		const seenIds = new Set();
+		const toolIssues = [];
+		for (const call of toolCalls) {
+			if (seenIds.has(call.id)) toolIssues.push({
+				name: call.name,
+				toolCallId: call.id,
+				code: "duplicate_tool_call_id"
+			});
+			seenIds.add(call.id);
+			if (!known.has(call.name)) toolIssues.push({
+				name: call.name,
+				toolCallId: call.id,
+				code: "unknown_tool"
+			});
+		}
+		if (toolIssues.length > 0) {
+			const unknownTool = toolIssues.find((i) => i.code === "unknown_tool");
+			const primary = unknownTool ? `Model requested tool "${unknownTool.name}", which was not in the tools offered ([${[...known.keys()].join(", ")}]).` : `Duplicate tool call id "${toolIssues[0].toolCallId}" in the model's response.`;
+			const message = toolIssues.length > 1 ? `${primary} (${toolIssues.length} tool call issues total, see toolIssues.)` : primary;
+			const error = new LLMError(message, "api", void 0, void 0, void 0, void 0, unknownTool ? "unknown_tool" : "duplicate_tool_call_id");
+			error.toolIssues = toolIssues;
+			throw error;
+		}
+		for (const call of toolCalls) {
+			const definition = known.get(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) {
+	async retryWithBackoff(fn, requestId, model, signal, onAttempt) {
 		let lastError;
 		for (let attempt = 0; attempt <= this.maxRetries; attempt++) try {
-			if (attempt > 0) await this.recoverDelay(requestId, attempt, lastError, signal);
-			return await fn();
+			if (attempt > 0) await this.recoverDelay(requestId, model, attempt, lastError, signal);
+			onAttempt?.();
+			return await fn(attempt);
 		} catch (error) {
 			lastError = error;
 			if (!this.shouldRetry(error, signal)) break;
@@ -496,105 +1626,60 @@ 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.
+	* 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.
 	*/
-	validateHistory(history) {
-		let previousRole;
-		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 (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");
-	}
-	/** 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 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,
-			max_tokens: maxTokens,
-			...responseFormat ? { response_format: responseFormat } : {},
-			...reasoningEffort ? { reasoning_effort: reasoningEffort } : {},
-			messages: [
-				...systemPrompt ? [{
-					role: "system",
-					content: systemPrompt
-				}] : [],
-				...history.map((turn) => ({
-					role: turn.role,
-					content: turn.content
-				})),
-				{
-					role: "user",
-					content: userContent
-				}
-			]
-		};
+	extractUsage(response, requestId, model) {
+		if (!response.usage) return void 0;
 		return {
-			useJson,
+			promptTokens: response.usage.prompt_tokens ?? 0,
+			completionTokens: response.usage.completion_tokens ?? 0,
+			totalTokens: response.usage.total_tokens ?? 0,
+			requestId,
 			model,
-			request
+			provider: this.providerName,
+			usedFallback: this.isFallback
 		};
 	}
 	/**
-	* Chooses the response format: a provider-native `jsonSchema` takes
-	* priority when supplied (constrains generation directly), otherwise
-	* falls back to the looser `json_object` mode when JSON output is
-	* requested, or no format at all for plain text responses.
+	* The token count to reconcile the rate limiter against for a finished
+	* attempt: `totalTokens` when reported, otherwise the sum of prompt and
+	* completion tokens, matching `reportUsageFailure`'s own fallback below
+	* for a hand-rolled client that reports the parts but omits the total.
 	*/
-	buildResponseFormat(jsonSchema, useJson) {
-		if (jsonSchema) return {
-			type: "json_schema",
-			json_schema: {
-				name: jsonSchema.name,
-				schema: jsonSchema.schema,
-				strict: jsonSchema.strict ?? true,
-				description: jsonSchema.description
-			}
-		};
-		return useJson ? { type: "json_object" } : void 0;
+	actualTokensFor(usage) {
+		if (!usage) return void 0;
+		return usage.totalTokens || usage.promptTokens + usage.completionTokens;
 	}
-	/** Reports token usage to `onUsage`, swallowing and logging any error it throws. */
-	recordUsage(response, requestId, model) {
-		if (!response.usage || !this.onUsage) return;
+	/** 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;
@@ -613,106 +1698,681 @@ var VernLLM = class {
 	* Waits out the backoff delay for a retry attempt, honoring a
 	* Retry-After header on the failed attempt's error when present.
 	* Both Retry-After and plain exponential backoff are capped at the same
-	* max delay (see `DEFAULT_MAX_DELAY_MS` in `vernLLM.utils.ts`).
+	* max delay (see `DEFAULT_MAX_DELAY_MS` in `retry.utils.ts`).
 	*/
-	async recoverDelay(requestId, attempt, error, signal) {
+	async recoverDelay(requestId, model, 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)" : ""));
+		const retryAfterHonored = retryAfterMs !== void 0;
+		this.logger.warn(`[VernLLM:${requestId}] recovery attempt ${attempt}/${this.maxRetries}, waiting ${delay}ms` + (retryAfterHonored ? " (honoring Retry-After)" : ""));
+		this.reportEvent({
+			kind: "retry",
+			requestId,
+			provider: this.providerName,
+			model,
+			attempt,
+			maxRetries: this.maxRetries,
+			delayMs: delay,
+			retryAfterHonored,
+			error: normalizeError(error, signal)
+		});
 		await waitForRetry(delay, signal);
 	}
+	isNonRetryableToolContractError(error) {
+		return error instanceof LLMError && (error.code === "unknown_tool" || error.code === "duplicate_tool_call_id");
+	}
 	/** Decides whether a failed attempt is worth retrying. */
 	shouldRetry(error, signal) {
 		if (signal?.aborted) return false;
 		if (error instanceof LLMError && (error.type === "parse" || error.type === "validation")) return false;
+		if (error instanceof LLMError && error.code === "local_rate_limit") return false;
+		if (this.isNonRetryableToolContractError(error)) return false;
 		const status = extractStatus(error);
 		return !(status !== void 0 && this.nonRetryableStatus.includes(status));
 	}
 	/**
+	* Decides whether a failed attempt should count toward the circuit
+	* breaker's failure threshold. A model hallucinating a tool name or
+	* reusing a call id isn't the provider being unhealthy, it's a model
+	* response defect that will very likely recur regardless of provider
+	* health, so it shouldn't push a healthy provider's circuit toward
+	* opening. Mirrors the same reasoning `shouldRetry` already applies to
+	* `parse`/`validation`/these same tool-contract codes.
+	*/
+	countsTowardBreaker(error) {
+		if (error.type === "validation" || error.type === "parse" || error.type === "aborted" || error.code === "local_rate_limit" || this.isNonRetryableToolContractError(error)) return false;
+		return true;
+	}
+};
+
+//#endregion
+//#region src/logger.ts
+/**
+* Default logger. `debug` is gated by the `debug` option on VernLLM
+* warn/error always fire since they indicate real problems (retries, cache failures)
+*/
+var ConsoleLogger = class {
+	constructor(debugEnabled) {
+		this.debugEnabled = debugEnabled;
+	}
+	debug(message) {
+		if (this.debugEnabled) console.debug(message);
+	}
+	warn(message) {
+		console.warn(message);
+	}
+	error(message, meta) {
+		console.error(message, meta ?? "");
+	}
+};
+
+//#endregion
+//#region src/rateLimit.ts
+/** Default `estimateTokens`: chars/4 over every message's content, plus the requested `max_tokens`. */
+function defaultEstimateTokens(request) {
+	const messagesChars = request.messages.reduce((sum, message) => {
+		const content = message.content;
+		if (typeof content === "string") return sum + content.length;
+		if (content === void 0 || content === null) return sum;
+		try {
+			return sum + JSON.stringify(content).length;
+		} catch {
+			return sum;
+		}
+	}, 0);
+	return Math.ceil(messagesChars / 4) + (request.max_tokens ?? 0);
+}
+/**
+* A capacity that refills continuously. Used for requests per minute and
+* tokens per minute, where `refillPerMs` is `capacity / 60000`, and for
+* concurrency, where `refillPerMs` is 0 and every release calls
+* `give(1)` instead of relying on the clock.
+*/
+var TokenBucket = class {
+	available;
+	lastRefill = Date.now();
+	constructor(capacity, refillPerMs) {
+		this.capacity = capacity;
+		this.refillPerMs = refillPerMs;
+		this.available = capacity;
+	}
+	refill() {
+		if (this.refillPerMs === 0) return;
+		const now = Date.now();
+		this.available = Math.min(this.capacity, this.available + (now - this.lastRefill) * this.refillPerMs);
+		this.lastRefill = now;
+	}
+	/** Refills, then takes `amount` if available. Leaves the bucket untouched if it can't. */
+	tryTake(amount) {
+		this.refill();
+		if (this.available < amount) return false;
+		this.available -= amount;
+		return true;
+	}
+	/**
+	* Refills, then reports how many ms until this bucket could supply
+	* `amount`, assuming nothing else takes from it meanwhile. Returns 0 if
+	* it already can, `Infinity` if it never will on its own (a
+	* concurrency bucket, `refillPerMs === 0`, only frees via `give`).
+	*/
+	msUntilAvailable(amount) {
+		this.refill();
+		if (this.available >= amount) return 0;
+		if (this.refillPerMs === 0) return Infinity;
+		return (amount - this.available) / this.refillPerMs;
+	}
+	/**
+	* Gives capacity back. Not floored at 0: a bad token-usage estimate can
+	* push `available` negative, and it self-corrects on the next refill
+	* rather than being clamped away immediately. Only ceilinged at
+	* `capacity`, so a give can never overfill the bucket.
+	*/
+	give(amount) {
+		this.available = Math.min(this.capacity, this.available + amount);
+	}
+	/** The bucket's ceiling, e.g. so a request that could never fit can fail fast instead of queueing forever. */
+	getCapacity() {
+		return this.capacity;
+	}
+};
+/**
+* `setTimeout` silently clamps any delay above this (~24.8 days) instead
+* of erroring, so an uncapped delay derived from a very small
+* `requestsPerMinute`/`tokensPerMinute` could wrap around to firing
+* almost immediately instead of waiting. Mirrors the same guard in
+* `withTimeout`/`withChunkIdleTimeout`.
+*/
+const MAX_WAKE_DELAY_MS = 2147483647;
+/**
+* Per-target rate limiter. Up to three buckets (requests/min, tokens/min,
+* concurrency) behind one FIFO queue, so a large call isn't starved by a
+* stream of small ones. Any bucket omitted from `options` has infinite
+* capacity and never blocks.
+*/
+var RateLimiter = class {
+	requests;
+	tokens;
+	concurrency;
+	maxQueueMs;
+	maxQueueSize;
+	estimateTokensFn;
+	queue = [];
+	/**
+	* A single scheduled re-check for the head of the queue when it's
+	* blocked on a bucket that refills on its own clock (rpm/tpm), so a
+	* queue that nobody calls `acquire`/`release` on again isn't stuck
+	* forever waiting for an external trigger to re-drain it. Not needed
+	* for a concurrency block, which only clears via `release`.
+	*/
+	wakeTimer;
+	constructor(options) {
+		if (options.requestsPerMinute) this.requests = new TokenBucket(options.requestsPerMinute, options.requestsPerMinute / 6e4);
+		if (options.tokensPerMinute) this.tokens = new TokenBucket(options.tokensPerMinute, options.tokensPerMinute / 6e4);
+		if (options.maxConcurrent) this.concurrency = new TokenBucket(options.maxConcurrent, 0);
+		this.maxQueueMs = options.maxQueueMs ?? 3e4;
+		this.maxQueueSize = options.maxQueueSize ?? 0;
+		this.estimateTokensFn = options.estimateTokens ?? defaultEstimateTokens;
+	}
+	/** Pre-flight token estimate for a request, per the configured (or default) heuristic. */
+	estimate(request) {
+		return this.estimateTokensFn(request);
+	}
+	/**
+	* Waits for capacity in every configured bucket, then takes from each.
+	* The returned `release` gives the concurrency slot back and reconciles
+	* the token bucket against real usage; it must run in a `finally` block.
+	*/
+	async acquire(estimatedTokens, signal) {
+		if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+		if (!Number.isFinite(estimatedTokens) || estimatedTokens < 0) throw new LLMError(`estimatedTokens must be a finite, non-negative number, got ${String(estimatedTokens)}`, "validation");
+		if (this.tokens && estimatedTokens > this.tokens.getCapacity()) throw new LLMError(`estimatedTokens (${estimatedTokens}) exceeds the configured tokensPerMinute capacity (${this.tokens.getCapacity()}); this call could never acquire capacity.`, "quota_exceeded", void 0, void 0, void 0, void 0, "local_rate_limit");
+		if (this.queue.length === 0) {
+			const attempt = this.tryAcquireBuckets(estimatedTokens);
+			if (attempt.ok) return {
+				release: this.makeRelease(estimatedTokens),
+				waitedMs: 0
+			};
+			if (this.maxQueueSize > 0 && this.queue.length >= this.maxQueueSize) throw this.queueFullError();
+			return this.enqueue(estimatedTokens, attempt.reason, signal);
+		}
+		if (this.maxQueueSize > 0 && this.queue.length >= this.maxQueueSize) throw this.queueFullError();
+		return this.enqueue(estimatedTokens, void 0, signal);
+	}
+	queueFullError() {
+		return new LLMError("Rate limit queue is full", "quota_exceeded", void 0, void 0, void 0, void 0, "local_rate_limit");
+	}
+	enqueue(estimatedTokens, initialReason, signal) {
+		return new Promise((resolvePromise, rejectPromise) => {
+			const waiter = {
+				estimatedTokens,
+				enqueuedAt: Date.now(),
+				lastReason: initialReason,
+				resolve: (result) => {
+					cleanup();
+					resolvePromise(result);
+				},
+				reject: (error) => {
+					cleanup();
+					if (this.wakeTimer) {
+						clearTimeout(this.wakeTimer);
+						this.wakeTimer = void 0;
+					}
+					this.drain();
+					rejectPromise(error);
+				}
+			};
+			let queueTimer;
+			const onAbort = () => {
+				waiter.reject(new LLMError("LLM request aborted", "aborted"));
+			};
+			const cleanup = () => {
+				if (queueTimer) clearTimeout(queueTimer);
+				signal?.removeEventListener("abort", onAbort);
+				const index = this.queue.indexOf(waiter);
+				if (index !== -1) this.queue.splice(index, 1);
+			};
+			if (this.maxQueueMs > 0) queueTimer = setTimeout(() => {
+				waiter.reject(new LLMError("Rate limit queue timed out before capacity was available", "quota_exceeded", void 0, void 0, void 0, void 0, "local_rate_limit"));
+			}, this.maxQueueMs);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.queue.push(waiter);
+			this.drain();
+		});
+	}
+	/**
+	* Checks and takes from every configured bucket as one atomic unit: if
+	* any bucket lacks capacity, whatever was already taken from the
+	* earlier ones in this attempt is rolled back before reporting which
+	* bucket blocked.
+	*/
+	tryAcquireBuckets(estimatedTokens) {
+		const taken = [];
+		const take = (bucket, amount) => {
+			if (!bucket) return true;
+			if (!bucket.tryTake(amount)) return false;
+			taken.push({
+				bucket,
+				amount
+			});
+			return true;
+		};
+		if (!take(this.concurrency, 1)) return {
+			ok: false,
+			reason: "concurrency"
+		};
+		if (!take(this.requests, 1)) {
+			for (const entry of taken) entry.bucket.give(entry.amount);
+			return {
+				ok: false,
+				reason: "rpm"
+			};
+		}
+		if (!take(this.tokens, estimatedTokens)) {
+			for (const entry of taken) entry.bucket.give(entry.amount);
+			return {
+				ok: false,
+				reason: "tpm"
+			};
+		}
+		return { ok: true };
+	}
+	/** Drains the queue head first. Stops at the first waiter that still can't proceed, so no one is starved out of turn. */
+	drain() {
+		while (this.queue.length > 0) {
+			const waiter = this.queue[0];
+			const attempt = this.tryAcquireBuckets(waiter.estimatedTokens);
+			if (!attempt.ok) {
+				waiter.lastReason = attempt.reason;
+				this.scheduleWake(attempt.reason, waiter.estimatedTokens);
+				return;
+			}
+			const waitedMs = Date.now() - waiter.enqueuedAt;
+			waiter.resolve({
+				release: this.makeRelease(waiter.estimatedTokens),
+				waitedMs,
+				reason: waiter.lastReason
+			});
+		}
+	}
+	/**
+	* Schedules a one-shot re-check of the queue for whenever the bucket
+	* that's currently blocking the head waiter should next have enough
+	* capacity. A no-op for a concurrency block (only `release` can clear
+	* that) or while a wake is already pending.
+	*/
+	scheduleWake(reason, estimatedTokens) {
+		if (this.wakeTimer) return;
+		const ms = reason === "rpm" ? this.requests?.msUntilAvailable(1) : reason === "tpm" ? this.tokens?.msUntilAvailable(estimatedTokens) : void 0;
+		if (ms === void 0 || !Number.isFinite(ms)) return;
+		const delay = Math.min(Math.max(1, Math.ceil(ms)), MAX_WAKE_DELAY_MS);
+		this.wakeTimer = setTimeout(() => {
+			this.wakeTimer = void 0;
+			this.drain();
+		}, delay);
+	}
+	/**
+	* Builds the one-shot release closure for an acquired slot. Only the
+	* concurrency bucket is given back on release; the requests-per-minute
+	* bucket is a real spend that only recovers via its own refill, and the
+	* tokens bucket is reconciled against `actualTokens` rather than fully
+	* refunded, since real tokens really were spent.
+	*/
+	makeRelease(estimatedTokens) {
+		let released = false;
+		return (actualTokens) => {
+			if (released) return;
+			released = true;
+			this.concurrency?.give(1);
+			if (this.tokens && actualTokens !== void 0 && Number.isFinite(actualTokens)) this.tokens.give(estimatedTokens - actualTokens);
+			this.drain();
+		};
+	}
+};
+
+//#endregion
+//#region src/vernLLM.ts
+/**
+* A resilient layer around an LLM chat completions client. This is VernLLM!
+*
+* 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 {
+	logger;
+	/**
+	* One `CallExecutor` per provider target: index 0 is the primary,
+	* everything after it is a `fallback` target, in the order declared.
+	* Each owns its own request building, retry/timeout, circuit breaker,
+	* and rate limiter. `call()` walks this array in `runFallbackChain`,
+	* moving to the next entry only when `fallbackOn` says to.
+	*/
+	executors;
+	/** Decides whether a failed target is followed by the next one or the chain stops. See `VernLLMOptions['fallbackOn']`. */
+	fallbackOn;
+	/** Reports a `'fallback'` event when the chain moves to the next target. Shared `onEvent` plumbing, same as every executor's. */
+	reportEvent;
+	/**
+	* Owns cache key resolution, cache reads/writes, and in-flight
+	* coalescing for `cachedCall()`. Independent of `executor`: it only
+	* ever calls back into `this.call()` as an opaque function.
+	*/
+	cacheOrchestrator;
+	/**
+	* @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) {
+		this.logger = options.logger ?? new ConsoleLogger(options.debug ?? false);
+		const providerName = options.name ?? "primary";
+		this.cacheOrchestrator = new CacheOrchestrator(options.cache ?? new InMemoryCacheAdapter(), this.logger);
+		this.fallbackOn = options.fallbackOn ?? defaultFallbackOn;
+		this.reportEvent = makeEventReporter(options.onEvent, this.logger);
+		const primaryDefaultTemperature = options.defaultTemperature === void 0 ? .2 : options.defaultTemperature;
+		const primaryTarget = {
+			client: options.client,
+			model: options.model,
+			name: providerName,
+			maxRetries: options.maxRetries,
+			timeoutMs: options.timeoutMs,
+			chunkIdleTimeoutMs: options.chunkIdleTimeoutMs,
+			baseDelayMs: options.baseDelayMs,
+			defaultMaxTokens: options.defaultMaxTokens,
+			defaultTemperature: primaryDefaultTemperature,
+			nonRetryableStatus: options.nonRetryableStatus,
+			circuitBreaker: options.circuitBreaker,
+			rateLimit: options.rateLimit
+		};
+		const declaredFallbacks = Array.isArray(options.fallback) ? options.fallback : options.fallback ? [options.fallback] : [];
+		const targets = [primaryTarget, ...declaredFallbacks];
+		this.executors = targets.map((target, i) => {
+			const isFallback = i > 0;
+			const name = target.name ?? (isFallback ? `fallback[${i - 1}]` : providerName);
+			const breaker = buildCircuitBreaker(target.circuitBreaker, name, target.model, options.onEvent, this.logger);
+			return new CallExecutor(name, target.client, target.model, {
+				maxRetries: target.maxRetries ?? options.maxRetries ?? 1,
+				timeoutMs: target.timeoutMs ?? options.timeoutMs ?? 25e3,
+				chunkIdleTimeoutMs: target.chunkIdleTimeoutMs ?? options.chunkIdleTimeoutMs ?? 3e4,
+				baseDelayMs: target.baseDelayMs ?? options.baseDelayMs ?? 500,
+				defaultMaxTokens: target.defaultMaxTokens ?? options.defaultMaxTokens ?? 1e3,
+				defaultTemperature: target.defaultTemperature === void 0 ? primaryDefaultTemperature : target.defaultTemperature,
+				nonRetryableStatus: target.nonRetryableStatus ?? options.nonRetryableStatus ?? [
+					400,
+					401,
+					403,
+					404,
+					422
+				],
+				parseJson: options.parseJson,
+				logger: this.logger,
+				redact: options.redact,
+				onUsage: options.onUsage,
+				onUsageFailure: options.onUsageFailure,
+				onEvent: options.onEvent,
+				breaker,
+				limiter: target.rateLimit ? new RateLimiter(target.rateLimit) : void 0,
+				isFallback
+			});
+		});
+	}
+	/** Logs a failed refundUsage attempt via the configured logger. */
+	logRefundError(logMessage, error) {
+		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
+	}
+	/**
+	* Walks `this.executors` in order, running `attempt` against each until
+	* one succeeds or every target has failed. `run` on a lone target
+	* (no `fallback` configured) throws exactly what it throws today: the
+	* loop's single iteration path is unchanged from pre-fallback behavior.
+	*
+	* For streaming, `attempt` is `executor.runStream`, whose own retries
+	* only cover *opening* the stream (see `CallExecutor.runStream`). A
+	* mid-stream failure surfaces through `finalResult` after this function
+	* has already returned, so it's never seen here and never falls over,
+	* per the streaming limitation: splicing a second model's output into a
+	* response the consumer has already partially rendered would corrupt
+	* it.
+	*/
+	async runFallbackChain(params, requestId, attempt, skipBreakerCheckForFirst = false) {
+		const attempts = [];
+		for (let i = 0; i < this.executors.length; i++) {
+			const executor = this.executors[i];
+			const startedAt = Date.now();
+			let attemptCount = 0;
+			try {
+				if (!(i === 0 && skipBreakerCheckForFirst)) executor.assertBreakerClosed(params.model);
+				const result = await attempt(executor, () => {
+					attemptCount += 1;
+				});
+				return {
+					result,
+					executor,
+					index: i,
+					attemptCount
+				};
+			} catch (error) {
+				const normalized = normalizeError(error, params.signal);
+				attempts.push({
+					index: i - 1,
+					provider: executor.providerName,
+					model: params.model ?? executor.model,
+					error: normalized
+				});
+				const isLast = i === this.executors.length - 1;
+				const policyDecision = this.fallbackOn(normalized, { isLastTarget: isLast });
+				const decision = isLast ? "stop" : policyDecision;
+				if (decision === "stop") throw attempts.length > 1 ? new FallbackExhaustedError(attempts) : normalized;
+				const next = this.executors[i + 1];
+				this.reportEvent({
+					kind: "fallback",
+					requestId,
+					from: executor.providerName,
+					to: next.providerName,
+					fromIndex: i - 1,
+					toIndex: i,
+					error: normalized,
+					elapsedMs: Date.now() - startedAt
+				});
+			}
+		}
+		throw new LLMError("No provider targets configured", "unknown");
+	}
+	async call(params) {
+		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+		const requestId = params.requestId ?? randomUUID();
+		const soleTarget = this.executors.length === 1;
+		if (soleTarget) this.executors[0].assertBreakerClosed(params.model);
+		if (params.stream) return withReservedUsageForStream(params, async () => {
+			const { result } = await this.runFallbackChain(params, requestId, (executor, onAttempt) => executor.runStream(params, requestId, onAttempt), soleTarget);
+			return result;
+		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+		return withReservedUsage(params, false, async () => {
+			const { result, executor, index, attemptCount } = await this.runFallbackChain(params, requestId, (target, onAttempt) => target.run(params, requestId, onAttempt), soleTarget);
+			if (params.meta) params.meta.current = {
+				provider: executor.providerName,
+				model: params.model ?? executor.model,
+				fallbackIndex: index - 1,
+				usedFallback: index > 0,
+				attempts: attemptCount
+			};
+			return result;
+		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+	}
+	/**
+	* Thin delegator kept private on `VernLLM` (rather than only existing on
+	* `CacheOrchestrator`) since it's the one caching primitive exercised
+	* directly by white-box tests, independent of the public `cachedCall()`
+	* surface.
+	*/
+	runCached(params) {
+		return this.cacheOrchestrator.runCached(params);
+	}
+	/**
 	* Removes a cached response by key when the configured cache adapter
 	* 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) {
-		if (!this.cache.delete) return;
-		await this.cache.delete(await this.resolveCacheKey(key));
+		await this.cacheOrchestrator.deleteCache(key);
 	}
-	/**
-	* Cache wrapper 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
-	* miss, typically `() => this.call(...)`), and optional
-	* `reserveUsage`/`refundUsage`/`signal`. See `CachedCallParams`.
-	* @returns The cached value on a hit, or the result of `fn()` on a miss.
-	*/
 	async cachedCall(params) {
-		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) return cached.value;
-		const existing = this.inFlight.get(resolvedKey);
-		if (existing) return withReservedUsage(resolvedParams, true, () => existing, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
-		return this.registerTrigger(resolvedParams, false);
-	}
-	/** Starts the shared fn() call for a cache miss and tracks it in the in-flight map until it settles. */
-	registerTrigger(params, coalesced) {
-		const resultPromise = withReservedUsage(params, coalesced, () => this.runAndCache(params), params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
-		this.inFlight.set(params.cacheKey, resultPromise);
-		resultPromise.catch(() => {}).finally(() => {
-			this.inFlight.delete(params.cacheKey);
-		});
-		return resultPromise;
-	}
-	/** Runs `fn` and writes its result to the cache. */
-	async runAndCache(params) {
-		const result = await params.fn();
-		try {
-			await this.cache.set(params.cacheKey, result, params.ttl);
-		} catch (error) {
-			this.logger.error("[VernLLM] cache write failed", { message: error instanceof Error ? error.message : "unknown" });
-		}
-		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" });
-	}
-	/**
-	* 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.
-	*
-	* @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.
-	*/
-	async cachedLLMCall(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.cacheOrchestrator.runCachedStream({
+				...cacheParams,
+				openStream: () => this.call(streamParams)
+			}, Boolean(restCallParams.tools));
+		}
+		return this.runCached({
 			...cacheParams,
 			fn: () => this.call(restCallParams)
 		});
 	}
 	/**
+	* @param model With `circuitBreaker.isolateByModel` on, returns that
+	* model's own circuit state instead of the shared one. Ignored
+	* otherwise. Omit for the shared circuit (the default) or, under
+	* isolation, the state of calls that didn't resolve a model.
 	* @returns The current circuit breaker state (`'closed' | 'open' |
 	* 'half-open'`), or undefined if no circuit breaker was configured.
 	*/
-	getCircuitState() {
-		return this.breaker?.getState();
+	getCircuitState(model) {
+		return this.executors[0].getCircuitState(model);
+	}
+	/**
+	* @param model With `circuitBreaker.isolateByModel` on, returns each
+	* target's circuit state for that model instead of its shared state.
+	* Ignored otherwise. Omit for the shared circuit (the default) or, under
+	* isolation, the state of calls that didn't resolve a model.
+	* @returns The current circuit state for every target in declaration
+	* order, including the primary and all fallback targets. Each entry
+	* includes the target's provider name, chain index, whether it is a
+	* fallback, and its circuit state, or undefined if that target has no
+	* circuit breaker configured.
+	*/
+	getCircuitStates(model) {
+		return this.executors.map((executor, index) => ({
+			provider: executor.providerName,
+			index,
+			isFallback: index > 0,
+			state: executor.getCircuitState(model)
+		}));
 	}
 };
 
 //#endregion
-//#region src/internal/imageFormat.ts
+//#region src/adapters/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/adapters/internal/imageFormat.ts
 /**
 * MIME types accepted for `ImageBlock.mimeType` across all adapters. This is
 * the intersection of what Anthropic, Gemini, OpenAI-compatible, and Bedrock
@@ -736,6 +2396,14 @@ function assertSupportedImageMimeType(mimeType) {
 	throw new LLMError(`Unsupported image mimeType "${mimeType}": expected one of ${SUPPORTED_IMAGE_MIME_TYPES.join(", ")}`, "validation");
 }
 
+//#endregion
+//#region src/adapters/internal/nativeStructuredOutput.ts
+/** Resolves whether `model` is covered by a caller-supplied allow-list/predicate. */
+function supportsNativeStructuredOutput(model, override) {
+	if (!override) return false;
+	return Array.isArray(override) ? override.includes(model) : override(model);
+}
+
 //#endregion
 //#region src/adapters/anthropic.ts
 /**
@@ -758,67 +2426,305 @@ 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
+	};
+}
+/**
+* Maps VernLLM's OpenAI-shaped wire `tools`/`tool_choice` into Anthropic's
+* `tools`/`tool_choice` shape. Shared by the two call sites that build real
+* (non-schema-forced) tool definitions: the plain tools-only branch, and
+* the native-structured-output branch, which sends real tools alongside
+* `output_config` rather than instead of it.
+*/
+function buildAnthropicTools(tools, toolChoiceParam) {
+	return {
+		tools: tools.map((t) => ({
+			name: t.function.name,
+			description: t.function.description,
+			input_schema: assertObjectSchema(t.function.parameters, t.function.name)
+		})),
+		toolChoice: toAnthropicToolChoice(toolChoiceParam)
+	};
+}
+/**
+* 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 (the
+* legacy path, for models without native structured-output support), 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. On the native path (model supports `output_config`),
+* `toolName` is `undefined`: the schema-conforming JSON already arrives as
+* ordinary text content, nothing to unwrap, and any real tool calls in
+* `params.tools` are left for the normal, non-forced tool-call handling
+* both `create` and `createStream` already do when `toolName` is unset.
+*/
+function buildAnthropicRequestBody(params, nativeStructuredOutputModels) {
+	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 schemaName = jsonSchema?.name.trim();
+	if (jsonSchema && !schemaName) throw new LLMError("json_schema.name must not be empty.", "validation");
+	const isNative = Boolean(jsonSchema) && supportsNativeStructuredOutput(params.model, nativeStructuredOutputModels);
+	if (jsonSchema && params.tools?.length && !isNative) throw new LLMError(`Anthropic model "${params.model}" is not covered by nativeStructuredOutputModels, so \`jsonSchema\` is emulated as a forced single tool call there, which collides with the \`tools\` you also provided. Either drop \`tools\` or \`jsonSchema\` for this call, or pass this model in fromAnthropic's \`nativeStructuredOutputModels\` option once you've confirmed it supports Anthropic's \`output_config.format\`.`, "validation");
+	let toolName;
+	let jsonInstruction;
+	let outputFormat;
+	let tools;
+	let toolChoice;
+	if (jsonSchema && isNative) {
+		outputFormat = {
+			type: "json_schema",
+			schema: jsonSchema.schema
+		};
+		if (params.tools?.length) ({tools, toolChoice} = buildAnthropicTools(params.tools, params.tool_choice));
+	} else if (jsonSchema && schemaName) {
+		const { schema, description, strict } = jsonSchema;
+		toolName = schemaName;
+		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.";
+	if (!jsonSchema && params.tools?.length) ({tools, toolChoice} = buildAnthropicTools(params.tools, 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
+		} : {},
+		...outputFormat ? { output_config: { format: outputFormat } } : {}
+	};
+	return {
+		body,
+		toolName
+	};
+}
+/**
 * Wraps an Anthropic SDK client so it satisfies the same `LLMClient`
 * interface VernLLM uses for OpenAI/Groq.
 *
-* `response_format: json_schema` is mapped to Anthropic's forced tool-use:
-* a single tool is defined with `input_schema` set to the caller's schema,
-* `description` forwarded when provided, and `strict` forwarded when set.
-* `tool_choice` forces the model to call it. Provider-constrained schema
-* matching applies only when `strict: true` is forwarded and supported.
+* `response_format: json_schema`, on a model covered by
+* `options.nativeStructuredOutputModels`, is sent as `output_config.format`,
+* its own request field, independent of `tools`/`tool_choice`, so it can be
+* combined with real, caller-supplied `tools` in the same request. Only
+* `type` and `schema` are sent on this path, the real Anthropic API's
+* `output_config.format` has no `name`/`description`/`strict` fields.
+*
+* On any other model (the default, since `nativeStructuredOutputModels` is
+* opt-in), `response_format: json_schema` is mapped to Anthropic's forced
+* tool-use instead: a single tool is defined with `input_schema` set to
+* the caller's schema, `description` forwarded when provided, and `strict`
+* forwarded when set, and `tool_choice` forces the model to call it. This
+* legacy path cannot be combined with real `tools` (both would need the
+* same `tools`/`tool_choice` field), and a call that tries throws
+* `LLMError('validation')` before reaching the API. Provider-constrained
+* schema matching applies only when `strict: true` is forwarded and
+* supported.
 *
 * `response_format: json_object` (no schema to build a tool from) falls
 * back to a system-prompt instruction, since there's nothing to constrain
-* generation against.
-*/
-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
+* generation against. Unlike `jsonSchema`, this combines with real `tools`
+* freely on every model: it's a prompt nudge, not a request field, so
+* there's nothing for it to collide with.
+*/
+function fromAnthropic(anthropicClient, options) {
+	const nativeStructuredOutputModels = options?.nativeStructuredOutputModels;
+	const rawMessagesCreate = anthropicClient.messages.create.bind(anthropicClient.messages);
+	return { chat: { completions: {
+		async create(params, options$1) {
+			const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels);
+			const response = await anthropicClient.messages.create(body, options$1);
+			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$1) {
+			const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels);
+			const stream = await rawMessagesCreate({
+				...body,
+				stream: true
+			}, options$1);
+			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 +2741,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 +2867,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`. Gemini accepts
+* `responseSchema` and `tools` in the same request natively, so both are
+* set independently here and no special-casing is needed for the
+* combination, unlike `fromAnthropic`/`fromBedrock`.
+*
+* `createStream` calls `generateContentStream` (optional on `GeminiClient`
+*, required only if the caller sets `stream: true`) and translates each
+* 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 +2996,99 @@ function toBedrockContent(blocks) {
 	} } : { text: block.text });
 }
 /**
+* Maps VernLLM's OpenAI-shaped wire `tools`/`tool_choice` into Converse's
+* `toolConfig` shape. Shared by the two call sites that build real
+* (non-schema-forced) tool definitions: the plain tools-only branch, and
+* the native-structured-output branch, which sends real tools alongside
+* `outputConfig` rather than instead of it.
+*/
+function buildBedrockToolConfig(tools, toolChoiceParam) {
+	return {
+		tools: tools.map((t) => ({ toolSpec: {
+			name: t.function.name,
+			description: t.function.description,
+			inputSchema: { json: t.function.parameters }
+		} })),
+		toolChoice: toBedrockToolChoice(toolChoiceParam)
+	};
+}
+/**
+* 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 (the
+* legacy path, for models not covered by `nativeStructuredOutputModels`),
+* 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. On the native path (model covered by
+* `nativeStructuredOutputModels`), `toolName` is `undefined`: the
+* schema-conforming JSON already arrives as ordinary text content, nothing
+* to unwrap, and any real tool calls in `params.tools` are left for the
+* normal, non-forced tool-call handling both `create` and `createStream`
+* already do when `toolName` is unset.
+*/
+function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels) {
+	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 schemaName = jsonSchema?.name.trim();
+	if (jsonSchema && !schemaName) throw new LLMError("json_schema.name must not be empty.", "validation");
+	const isNative = Boolean(jsonSchema) && supportsNativeStructuredOutput(params.model, nativeStructuredOutputModels);
+	if (jsonSchema && params.tools?.length && !isNative) throw new LLMError(`Bedrock model "${params.model}" is not covered by nativeStructuredOutputModels, so \`jsonSchema\` is emulated as a forced single tool call there (via \`toolConfig\`), which collides with the \`tools\` you also provided. Either drop \`tools\` or \`jsonSchema\` for this call, or pass this model in fromBedrock's \`nativeStructuredOutputModels\` option once you've confirmed it supports Converse's \`outputConfig.textFormat\`.`, "validation");
+	let toolName;
+	let jsonInstruction;
+	let toolConfig;
+	let outputConfig;
+	if (jsonSchema && isNative) {
+		const { schema, description } = jsonSchema;
+		outputConfig = { textFormat: {
+			type: "json_schema",
+			structure: { jsonSchema: {
+				schema: JSON.stringify(schema),
+				name: schemaName,
+				description
+			} }
+		} };
+	} else if (jsonSchema && schemaName) {
+		const { schema, description, strict } = jsonSchema;
+		toolName = schemaName;
+		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.";
+	if (params.tools?.length && !toolName) toolConfig = buildBedrockToolConfig(params.tools, params.tool_choice);
+	if (jsonSchema && toolConfig && 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 this call requires Converse tool use (either jsonSchema emulated as a forced tool call, or real \`tools\` sent alongside native structured output).`, "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 } : {},
+		...outputConfig ? { outputConfig } : {}
+	};
+	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.),
@@ -924,78 +3096,264 @@ function toBedrockContent(blocks) {
 * regardless of which underlying model `modelId` points at, as long as
 * that model supports Converse (most current-generation ones do)
 *
-* `response_format: json_schema` is mapped to Converse's `toolConfig`: a
-* single tool is defined from the schema, description, and strictness settings,
-* and `toolChoice` forces the model to call it. Provider-constrained schema
-* matching applies only when `strict: true` is forwarded and supported.
-* Native tool support varies by model family; pass
-* `toolUseSupportedModels` to preflight-check it (see
+* `response_format: json_schema`, on a model covered by
+* `options.nativeStructuredOutputModels` (opt-in, unset by default), is
+* sent as `outputConfig.textFormat`, its own request field, independent of
+* `toolConfig`, so it can be combined with real, caller-supplied `tools`
+* in the same request. Matches the real Converse API's shape exactly: the
+* schema is nested under `structure.jsonSchema` and JSON-encoded as a
+* string, not the parsed object `toolConfig`'s tool schemas use, and there
+* is no `strict` field on this path.
+*
+* On any other model (the default), `response_format: json_schema` is
+* mapped to Converse's `toolConfig` instead: a single tool is defined from
+* the schema, description, and strictness settings, and `toolChoice`
+* forces the model to call it. This legacy path cannot be combined with
+* real `tools` (both would need the same `toolConfig`), and a call that
+* tries throws `LLMError('validation')` before reaching the API.
+* Provider-constrained schema matching applies only when `strict: true` is
+* forwarded and supported. Native tool support varies by model family;
+* pass `toolUseSupportedModels` to preflight-check it (see
 * `BedrockAdapterOptions`), otherwise a `jsonSchema` call to an
 * unsupported model surfaces Bedrock's raw error unchanged.
 *
 * `response_format: json_object` (no schema to build a tool from) and
 * `reasoning_effort` (no Converse equivalent) fall back to a system-prompt
-* instruction and are dropped respectively.
+* instruction and are dropped respectively. Unlike `jsonSchema`,
+* `json_object` combines with real `tools` freely on every model: it's a
+* prompt nudge, not a request field, so there's nothing for it to collide
+* with.
+*
+* `tools` alone maps to Converse's native `toolConfig`/`toolUse`/
+* `toolResult`; `tool_choice` maps to `toolConfig.toolChoice`.
+*
+* `createStream` calls `converseStream` (optional on `BedrockConverseClient`
+*, required only if the caller sets `stream: true`) and translates its
+* `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
+	const nativeStructuredOutputModels = options?.nativeStructuredOutputModels;
+	return { chat: { completions: {
+		async create(params, requestOptions) {
+			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels);
+			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, nativeStructuredOutputModels);
+			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 +3363,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 +3478,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 +3644,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, FallbackExhaustedError, InMemoryCacheAdapter, LLMError, NormalizedCacheAdapter, RateLimiter, SSE_PING, TieredCacheAdapter, VernLLM, defaultEstimateTokens, defaultFallbackOn, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGitHubModels, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromKlusterAI, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, isLLMError, isToolCallResult, parseSseStream };
 //# sourceMappingURL=index.js.map