vern-llm 2.0.0 → 2.1.0

package/dist/index.js

@@ -2,385 +2,245 @@ 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
+//#region src/types/cache.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
+* Trivial default so the package works out of the box with no external deps
+* Not shared across processes, swap in Redis/Upstash/etc for production
 */
-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;
+var InMemoryCacheAdapter = class {
+	store = new Map();
+	constructor(maxSize = 1e3) {
+		this.maxSize = maxSize;
 	}
-	/**
-	* 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;
+	async get(key) {
+		const entry = this.store.get(key);
+		if (!entry) return {
+			hit: false,
+			value: null
+		};
+		if (Date.now() >= entry.expiresAt) {
+			this.store.delete(key);
+			return {
+				hit: false,
+				value: null
+			};
 		}
-		if (this.consecutiveFailures >= this.threshold) {
-			this.state = "open";
-			this.openedAt = Date.now();
+		return {
+			hit: true,
+			value: entry.value
+		};
+	}
+	async set(key, value, ttl) {
+		this.cleanupExpiredEntries();
+		this.store.set(key, {
+			value,
+			expiresAt: Date.now() + ttl * 1e3
+		});
+		this.enforceSizeLimit();
+	}
+	async delete(key) {
+		this.store.delete(key);
+	}
+	cleanupExpiredEntries() {
+		const now = Date.now();
+		for (const [key, entry] of this.store) if (now >= entry.expiresAt) this.store.delete(key);
+	}
+	enforceSizeLimit() {
+		while (this.store.size > this.maxSize) {
+			const oldestKey = this.store.keys().next().value;
+			if (oldestKey === void 0) break;
+			this.store.delete(oldestKey);
 		}
 	}
-	getState() {
-		return this.state;
+};
+/**
+* Normalizes keys before caching to avoid duplicate entries from formatting differences.
+*/
+var NormalizedCacheAdapter = class {
+	constructor(inner = new InMemoryCacheAdapter()) {
+		this.inner = inner;
+	}
+	normalize(key) {
+		return key.toLowerCase().trim().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
+	}
+	async resolveKey(key) {
+		return this.normalize(key);
+	}
+	async get(key) {
+		return this.inner.get(this.normalize(key));
+	}
+	async set(key, value, ttl) {
+		await this.inner.set(this.normalize(key), value, ttl);
+	}
+	async delete(key) {
+		await this.inner.delete?.(this.normalize(key));
+	}
+};
+/**
+* Two-tier cache with fast local L1 and shared L2.
+* L2 hits are promoted back to L1.
+*/
+var TieredCacheAdapter = class {
+	constructor(l1, l2, l1Ttl) {
+		this.l1 = l1;
+		this.l2 = l2;
+		this.l1Ttl = l1Ttl;
+	}
+	/**
+	* Forwards to L1's `resolveKey` if it has one, otherwise L2's. L1 is
+	* preferred since `get()` checks L1 first, so its notion of "the same
+	* key" is the one that determines whether a lookup can skip L2 entirely.
+	*/
+	async resolveKey(key) {
+		if (this.l1.resolveKey) return this.l1.resolveKey(key);
+		if (this.l2.resolveKey) return this.l2.resolveKey(key);
+		return key;
+	}
+	async get(key) {
+		const l1Result = await this.l1.get(key);
+		if (l1Result.hit) return l1Result;
+		const l2Result = await this.l2.get(key);
+		if (l2Result.hit) await this.l1.set(key, l2Result.value, this.l1Ttl ?? 60);
+		return l2Result;
+	}
+	async set(key, value, ttl) {
+		await Promise.all([this.l1.set(key, value, this.l1Ttl ?? ttl), this.l2.set(key, value, ttl)]);
+	}
+	async delete(key) {
+		await Promise.all([this.l1.delete?.(key), this.l2.delete?.(key)]);
 	}
 };
 
 //#endregion
-//#region src/internal/vernLLM.utils.ts
-/** Translates app-facing `ToolDefinition[]` into the OpenAI-shaped wire tools array. */
-function toWireTools(tools) {
-	return tools.map((tool) => ({
-		type: "function",
-		function: {
-			name: tool.name,
-			description: tool.description,
-			parameters: tool.parameters
-		}
-	}));
-}
-/** Translates app-facing `ToolCall[]` (e.g. from a replayed assistant turn) into wire tool_calls. */
-function toWireToolCalls(toolCalls) {
-	return toolCalls.map((tc) => ({
-		id: tc.id,
-		type: "function",
-		function: {
-			name: tc.name,
-			arguments: JSON.stringify(tc.arguments ?? {})
-		}
-	}));
-}
+//#region src/types/tools.ts
 /**
-* 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.
+* Runtime-safe check for whether a `call()` result is a `tool_calls`
+* result. Prefer this over relying on TypeScript's static narrowing
+* whenever `params` passed to `call()` wasn't a literal with `tools`
+* inlined (see the "note on the overload" in `VernLLM.call`'s docs), in
+* that case TS may have typed the result as plain `T` even though it's
+* actually a `CallWithToolsResult<T>` at runtime, and this check works
+* either way.
 */
-function parseWireToolCalls(wireToolCalls) {
-	return wireToolCalls.map((wc) => {
-		let parsedArgs;
-		try {
-			parsedArgs = wc.function.arguments.trim() ? JSON.parse(wc.function.arguments) : {};
-		} catch {
-			throw new LLMError(`Invalid JSON arguments for tool call "${wc.function.name}"`, "parse");
-		}
-		return {
-			id: wc.id,
-			name: wc.function.name,
-			arguments: parsedArgs
-		};
-	});
+function isToolCallResult(result) {
+	return typeof result === "object" && result !== null && "type" in result && result.type === "tool_calls" && Array.isArray(result.toolCalls);
 }
-function defaultParseJson(content) {
+
+//#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 {
-		return JSON.parse(content);
-	} catch {
-		return void 0;
+		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);
 	}
 }
 /**
-* 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
+* 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 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 {
+function makeRefund(params, coalesced, signal, onRefundError) {
+	return async (logMessage) => {
 		try {
-			return String(value);
-		} catch {
-			return "[unprintable error]";
+			await params.refundUsage?.({
+				coalesced,
+				signal
+			});
+		} catch (refundError) {
+			onRefundError(logMessage, refundError);
 		}
-	}
+	};
 }
 /**
-* 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.
+* 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.
 */
-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);
-}
-/**
-* `setTimeout` silently clamps any delay above this (~24.8 days) or
-* `Infinity` down to ~1ms instead of erroring, so a caller passing
-* `Infinity` as "no timeout" gets the opposite of what they asked for.
-* Both timeout helpers below guard against this explicitly.
-*/
-const MAX_SETTIMEOUT_MS = 2147483647;
-/** True when a timeout value should be treated as "disabled" rather than passed to `setTimeout`. */
-function isTimeoutDisabled(ms) {
-	return !ms || ms <= 0 || ms === Infinity;
-}
-/** Caps a timeout at the largest delay `setTimeout` actually honors. */
-function clampTimeoutMs(ms) {
-	return Math.min(ms, MAX_SETTIMEOUT_MS);
-}
-/**
-* Runs an async function and cancels it if it takes longer than the given
-* timeout. Creates an internal abort controller that fires after the
-* timeout elapses, and combines it with any external signal the caller
-* 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 timer = isTimeoutDisabled(timeoutMs) ? void 0 : setTimeout(() => {
-		controller.abort();
-	}, clampTimeoutMs(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);
-	}
-}
-/**
-* Races one `iterator.next()` call against a per-call idle timer, to
-* bound the gap *between* chunks (unlike `withTimeout`, which only bounds
-* opening the stream and its first chunk). Without this, a connection
-* that streams one chunk then hangs would never fail.
-*
-* `timeoutMs` of 0/undefined/`Infinity` disables the check. Otherwise
-* rejects with `LLMError('timeout')` if `next()` doesn't settle in time.
-* The clock resets on every call, so the window is measured from the most
-* recent chunk, not from stream start.
-*
-* `onIdle`, if given, is called the moment the timer fires (before the
-* rejection), so callers can abort the underlying transport instead of
-* just walking away from an unread promise. `logger`, if given, records a
-* debug line if `next()` still settles *after* the idle timeout already
-* rejected. `resolve`/`reject` on an already-settled promise is otherwise
-* a silent no-op, so without this the late chunk (possibly the final
-* usage chunk) would vanish with no trace.
-*/
-function withChunkIdleTimeout(next, timeoutMs, onIdle, logger) {
-	if (isTimeoutDisabled(timeoutMs)) return next();
-	const activeTimeoutMs = timeoutMs;
-	let settled = false;
-	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => {
-			settled = true;
-			onIdle?.();
-			reject(new LLMError(`No stream chunk received for ${activeTimeoutMs}ms (idle timeout)`, "timeout"));
-		}, clampTimeoutMs(activeTimeoutMs));
-		next().then((result) => {
-			clearTimeout(timer);
-			if (settled) {
-				logger?.debug("[VernLLM] chunk resolved after idle timeout already fired; discarding");
-				return;
-			}
-			settled = true;
-			resolve(result);
-		}, (error) => {
-			clearTimeout(timer);
-			if (settled) {
-				logger?.debug("[VernLLM] chunk rejection arrived after idle timeout already fired; discarding");
-				return;
-			}
-			settled = true;
-			reject(error);
-		});
-	});
-}
-/**
-* Default cap (ms) for both exponential backoff and honored Retry-After
-* values, so a misbehaving/adversarial Retry-After can't stall a caller
-* indefinitely
-*/
-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;
+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
@@ -402,29 +262,12 @@ async function withReservedUsage(params, coalesced, getResult, signal, onRefundE
 */
 async function withReservedUsageForStream(params, openStream, signal, onRefundError) {
 	if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
-	let reserved = false;
-	try {
-		if (params.reserveUsage) {
-			await params.reserveUsage({
-				coalesced: false,
-				signal
-			});
-			reserved = true;
-		}
-	} catch (error) {
-		if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
-		throw new LLMError(error instanceof Error ? error.message : "Usage reservation failed", "quota_exceeded", void 0, void 0, error);
+	const 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");
 	}
-	const refund = async (logMessage) => {
-		try {
-			await params.refundUsage?.({
-				coalesced: false,
-				signal
-			});
-		} catch (refundError) {
-			onRefundError(logMessage, refundError);
-		}
-	};
 	let opened;
 	try {
 		opened = await openStream();
@@ -442,6 +285,9 @@ async function withReservedUsageForStream(params, openStream, signal, onRefundEr
 		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
@@ -454,7 +300,7 @@ async function withReservedUsageForStream(params, openStream, signal, onRefundEr
 * to support.
 */
 function toReplayText(value) {
-	return typeof value === "string" ? value : JSON.stringify(value);
+	return typeof value === "string" ? value : JSON.stringify(value) ?? "";
 }
 /**
 * Builds a trivially-exhausted one-shot `chunks` iterable from an
@@ -521,235 +367,1031 @@ function buildReplayChunksFromPromise(promise, hasTools) {
 }
 
 //#endregion
-//#region src/logger.ts
+//#region src/internal/cache/cacheOrchestrator.ts
 /**
-* Default logger. `debug` is gated by the `debug` option on VernLLM
-* warn/error always fire since they indicate real problems (retries, cache failures)
+* 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 ConsoleLogger = class {
-	constructor(debugEnabled) {
-		this.debugEnabled = debugEnabled;
-	}
-	debug(message) {
-		if (this.debugEnabled) console.debug(message);
+var CacheOrchestrator = class {
+	inFlight = new Map();
+	constructor(cache, logger) {
+		this.cache = cache;
+		this.logger = logger;
 	}
-	warn(message) {
-		console.warn(message);
+	/** Resolves a cache key through the adapter when it supports normalization. */
+	async resolveCacheKey(key) {
+		return this.cache.resolveKey ? await this.cache.resolveKey(key) : key;
 	}
-	error(message, meta) {
-		console.error(message, meta ?? "");
+	/**
+	* 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));
 	}
-};
-
-//#endregion
-//#region src/types/cache.ts
-/**
-* Trivial default so the package works out of the box with no external deps
-* Not shared across processes, swap in Redis/Upstash/etc for production
-*/
-var InMemoryCacheAdapter = class {
-	store = new Map();
-	constructor(maxSize = 1e3) {
-		this.maxSize = maxSize;
+	/** Logs a failed refundUsage attempt via the configured logger. */
+	logRefundError(logMessage, error) {
+		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
 	}
-	async get(key) {
-		const entry = this.store.get(key);
-		if (!entry) return {
-			hit: false,
-			value: null
+	/**
+	* 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
+				}
+			]
 		};
-		if (Date.now() >= entry.expiresAt) {
-			this.store.delete(key);
-			return {
-				hit: false,
-				value: null
-			};
-		}
 		return {
-			hit: true,
-			value: entry.value
+			useJson,
+			model,
+			request
 		};
 	}
-	async set(key, value, ttl) {
-		this.cleanupExpiredEntries();
-		this.store.set(key, {
-			value,
-			expiresAt: Date.now() + ttl * 1e3
-		});
-		this.enforceSizeLimit();
-	}
-	async delete(key) {
-		this.store.delete(key);
-	}
-	cleanupExpiredEntries() {
-		const now = Date.now();
-		for (const [key, entry] of this.store) if (now >= entry.expiresAt) this.store.delete(key);
-	}
-	enforceSizeLimit() {
-		while (this.store.size > this.maxSize) {
-			const oldestKey = this.store.keys().next().value;
-			if (oldestKey === void 0) break;
-			this.store.delete(oldestKey);
+	/**
+	* 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");
 	}
-};
-/**
-* Normalizes keys before caching to avoid duplicate entries from formatting differences.
-*/
-var NormalizedCacheAdapter = class {
-	constructor(inner = new InMemoryCacheAdapter()) {
-		this.inner = inner;
-	}
-	normalize(key) {
-		return key.toLowerCase().trim().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
-	}
-	async resolveKey(key) {
-		return this.normalize(key);
-	}
-	async get(key) {
-		return this.inner.get(this.normalize(key));
-	}
-	async set(key, value, ttl) {
-		await this.inner.set(this.normalize(key), value, ttl);
-	}
-	async delete(key) {
-		await this.inner.delete?.(this.normalize(key));
-	}
-};
-/**
-* Two-tier cache with fast local L1 and shared L2.
-* L2 hits are promoted back to L1.
-*/
-var TieredCacheAdapter = class {
-	constructor(l1, l2, l1Ttl) {
-		this.l1 = l1;
-		this.l2 = l2;
-		this.l1Ttl = l1Ttl;
+	/** 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 }
+		};
 	}
 	/**
-	* Forwards to L1's `resolveKey` if it has one, otherwise L2's. L1 is
-	* preferred since `get()` checks L1 first, so its notion of "the same
-	* key" is the one that determines whether a lookup can skip L2 entirely.
+	* 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.
 	*/
-	async resolveKey(key) {
-		if (this.l1.resolveKey) return this.l1.resolveKey(key);
-		if (this.l2.resolveKey) return this.l2.resolveKey(key);
-		return key;
-	}
-	async get(key) {
-		const l1Result = await this.l1.get(key);
-		if (l1Result.hit) return l1Result;
-		const l2Result = await this.l2.get(key);
-		if (l2Result.hit) await this.l1.set(key, l2Result.value, this.l1Ttl ?? 60);
-		return l2Result;
-	}
-	async set(key, value, ttl) {
-		await Promise.all([this.l1.set(key, value, this.l1Ttl ?? ttl), this.l2.set(key, value, ttl)]);
+	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 ?? ""
+		}];
 	}
-	async delete(key) {
-		await Promise.all([this.l1.delete?.(key), this.l2.delete?.(key)]);
+	/**
+	* 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/types/tools.ts
+//#region src/internal/execution/streamAccumulator.ts
 /**
-* Runtime-safe check for whether a `call()` result is a `tool_calls`
-* result. Prefer this over relying on TypeScript's static narrowing
-* whenever `params` passed to `call()` wasn't a literal with `tools`
-* inlined (see the "note on the overload" in `VernLLM.call`'s docs), in
-* that case TS may have typed the result as plain `T` even though it's
-* actually a `CallWithToolsResult<T>` at runtime, and this check works
-* either way.
+* 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 isToolCallResult(result) {
-	return typeof result === "object" && result !== null && "type" in result && result.type === "tool_calls" && Array.isArray(result.toolCalls);
+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/vernLLM.ts
+//#region src/internal/execution/callExecutor.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.
+* 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 VernLLM = class {
-	client;
-	model;
+var CallExecutor = class {
 	maxRetries;
 	timeoutMs;
 	chunkIdleTimeoutMs;
 	baseDelayMs;
-	defaultMaxTokens;
-	defaultTemperature;
-	cache;
 	nonRetryableStatus;
-	inFlight = new Map();
 	parseJson;
+	logger;
+	redact;
 	onUsage;
 	onUsageFailure;
-	logger;
+	reportEvent;
 	breaker;
-	/**
-	* @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.client = options.client;
-		this.model = options.model;
-		this.maxRetries = options.maxRetries ?? 1;
-		this.timeoutMs = options.timeoutMs ?? 25e3;
-		this.chunkIdleTimeoutMs = options.chunkIdleTimeoutMs ?? 3e4;
-		this.baseDelayMs = options.baseDelayMs ?? 500;
-		this.defaultMaxTokens = options.defaultMaxTokens ?? 1e3;
-		this.defaultTemperature = options.defaultTemperature === void 0 ? .2 : options.defaultTemperature;
-		this.cache = options.cache ?? new InMemoryCacheAdapter();
-		this.nonRetryableStatus = options.nonRetryableStatus ?? [
-			400,
-			401,
-			403,
-			404,
-			422
-		];
+	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.logger = options.logger ?? new ConsoleLogger(options.debug ?? false);
-		this.breaker = options.circuitBreaker ? new CircuitBreaker(options.circuitBreaker === true ? void 0 : options.circuitBreaker) : void 0;
+		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
+		});
 	}
-	/** Resolves a cache key through the adapter when it supports normalization. */
-	async resolveCacheKey(key) {
-		return this.cache.resolveKey ? await this.cache.resolveKey(key) : key;
+	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;
+		}
 	}
-	async call(params) {
-		this.breaker?.assertClosed();
-		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
-		const requestId = params.requestId ?? randomUUID();
-		if (params.stream) return withReservedUsageForStream(params, async () => {
-			try {
-				return await this.retryWithBackoff((attempt) => this.executeStreamCall(params, requestId, attempt), requestId, params.signal);
-			} catch (error) {
-				const normalized = normalizeError(error, params.signal);
-				if (normalized.type !== "validation" && normalized.type !== "parse" && normalized.type !== "aborted") this.breaker?.recordFailure();
-				this.logger.debug(`[VernLLM:${requestId}] stream-open error:\n${describeError(error)}`);
-				throw normalized;
-			}
-		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
-		return withReservedUsage(params, false, async () => {
-			try {
-				return await this.retryWithBackoff((attempt) => this.executeCall(params, requestId, attempt), requestId, params.signal);
-			} catch (error) {
-				const normalized = normalizeError(error, params.signal);
-				if (normalized.type !== "validation" && normalized.type !== "parse" && normalized.type !== "aborted") this.breaker?.recordFailure();
-				this.logger.debug(`[VernLLM:${requestId}] error:\n${describeError(error)}`);
-				throw normalized;
-			}
-		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+	/** 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
@@ -759,12 +1401,46 @@ var VernLLM = class {
 	* retry loop treats it like any other transient failure.
 	*/
 	async executeCall(params, requestId, attempt) {
-		const { useJson, model, request } = this.buildRequestPayload(params);
-		const response = await withTimeout((attemptSignal) => this.client.chat.completions.create(request, { signal: attemptSignal }), this.timeoutMs, params.signal);
-		const usage = this.extractUsage(response, requestId, model);
-		const rawContent = response.choices?.[0]?.message?.content;
-		const wireToolCalls = response.choices?.[0]?.message?.tool_calls;
-		return this.finalizeResponse(rawContent, wireToolCalls, params, useJson, usage, requestId, attempt);
+		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
@@ -776,16 +1452,16 @@ var VernLLM = class {
 	* Normalizes and reports usage failure on error itself, so every caller
 	* gets identical error handling without duplicating it.
 	*/
-	finalizeResponse(rawContent, wireToolCalls, params, useJson, usage, requestId, attempt) {
+	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${(content ?? `[${wireToolCalls?.length ?? 0} tool call(s)]`).slice(0, 800)}`);
+			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();
+				this.breaker?.recordSuccess(model);
 				this.reportUsage(usage);
 				return {
 					type: "tool_calls",
@@ -795,7 +1471,7 @@ var VernLLM = class {
 			}
 			const textContent = content ?? "";
 			if (!useJson) {
-				this.breaker?.recordSuccess();
+				this.breaker?.recordSuccess(model);
 				this.reportUsage(usage);
 				return params.tools ? {
 					type: "content",
@@ -803,7 +1479,7 @@ var VernLLM = class {
 				} : textContent;
 			}
 			const result = this.parseAndValidate(textContent, params.schema);
-			this.breaker?.recordSuccess();
+			this.breaker?.recordSuccess(model);
 			this.reportUsage(usage);
 			return params.tools ? {
 				type: "content",
@@ -833,199 +1509,115 @@ var VernLLM = class {
 	* dies mid-stream isn't masked as a success (see `buildStreamResult`).
 	*/
 	async executeStreamCall(params, requestId, attempt) {
-		const { useJson, model, request } = this.buildRequestPayload(params);
-		const createStream = this.client.chat.completions.createStream;
-		if (!createStream) throw new LLMError("stream: true requires a client/adapter with createStream", "validation");
+		const { 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;
-		const { iterator, first } = await withTimeout(async (attemptSignal) => {
-			const streamIterator = createStream(request, { signal: attemptSignal })[Symbol.asyncIterator]();
-			const firstResult = await streamIterator.next();
-			return {
-				iterator: streamIterator,
-				first: firstResult
-			};
-		}, this.timeoutMs, combinedExternal);
-		if (first.done) throw new LLMError("Empty LLM response", "api");
-		return this.buildStreamResult(iterator, first, params, useJson, requestId, model, attempt, streamController);
-	}
-	/**
-	* The streaming accumulator: wraps the raw `WireStreamChunk` iterator in
-	* an async generator that yields translated `StreamChunk`s to the caller
-	* live, as they arrive, with no per-chunk timeout and no bound on total
-	* duration, and accumulates text/tool-call deltas internally so that
-	* `finalizeResponse` can produce `finalResult` once the stream completes.
-	*
-	* Two separate try/catches: the iteration loop's catch handles errors
-	* the transport itself throws, which aren't normalized yet, so that
-	* happens here along with the one `reportUsageFailure` call for them.
-	* The second catch, around `finalizeResponse`, does not re-normalize or
-	* re-report since `finalizeResponse` already does both internally.
-	* Circuit-breaker success is only recorded once the stream fully
-	* completes, not when the first chunk arrives, so a connection that
-	* opens and then dies mid-way still counts as a failure below instead
-	* of masking it.
-	*/
-	buildStreamResult(iterator, first, params, useJson, requestId, model, attempt, streamController) {
-		let resolveFinal;
-		let rejectFinal;
-		const finalResult = new Promise((resolve, reject) => {
-			resolveFinal = resolve;
-			rejectFinal = reject;
-		});
-		finalResult.catch(() => {});
-		const MAX_BUFFERED_CHUNKS = 1e4;
-		const buffered = [];
-		const pending = [];
-		let streamDone = false;
-		let streamError;
-		let hasLoggedEviction = false;
-		const push = (chunk) => {
-			const waiter = pending.shift();
-			if (waiter) {
-				waiter.resolve({
-					done: false,
-					value: chunk
-				});
-				return;
-			}
-			buffered.push(chunk);
-			if (buffered.length > MAX_BUFFERED_CHUNKS * 2) {
-				if (!hasLoggedEviction) {
-					hasLoggedEviction = true;
-					this.logger.debug(`[VernLLM] stream chunk buffer exceeded cap (${MAX_BUFFERED_CHUNKS}), evicting ${buffered.length - MAX_BUFFERED_CHUNKS} oldest chunk(s); buffered=${buffered.length}. The chunks iterable was never read (or fell far behind) for this stream.`);
-				}
-				buffered.splice(0, buffered.length - MAX_BUFFERED_CHUNKS);
-			}
-		};
-		const finish = () => {
-			streamDone = true;
-			for (const waiter of pending.splice(0)) waiter.resolve({
-				done: true,
-				value: void 0
+		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)
 			});
-		};
-		const fail = (error) => {
-			streamDone = true;
-			streamError = error;
-			for (const waiter of pending.splice(0)) waiter.reject(error);
-		};
-		const chunks = { [Symbol.asyncIterator]() {
-			return { next() {
-				if (buffered.length) return Promise.resolve({
-					done: false,
-					value: buffered.shift()
-				});
-				if (streamDone) return streamError ? Promise.reject(streamError) : Promise.resolve({
-					done: true,
-					value: void 0
-				});
-				return new Promise((resolve, reject) => {
-					pending.push({
-						resolve,
-						reject
-					});
-				});
-			} };
-		} };
-		const toolCallAcc = new Map();
-		let textAcc = "";
-		let usage;
-		(async () => {
-			try {
-				let result = first;
-				while (!result.done) {
-					const wireChunk = result.value;
-					if (wireChunk.type === "ping") {} else if (wireChunk.type === "text-delta") {
-						textAcc += wireChunk.delta;
-						push({
-							type: "text-delta",
-							delta: wireChunk.delta
-						});
-					} else if (wireChunk.type === "tool_call_delta") {
-						const entry = toolCallAcc.get(wireChunk.index) ?? { args: "" };
-						entry.id ??= wireChunk.id;
-						entry.name ??= wireChunk.name;
-						entry.args += wireChunk.argumentsDelta ?? "";
-						toolCallAcc.set(wireChunk.index, entry);
-						push({
-							type: "tool_call_delta",
-							index: wireChunk.index,
-							id: wireChunk.id,
-							name: wireChunk.name,
-							argsDelta: wireChunk.argumentsDelta,
-							complete: wireChunk.complete
-						});
-					} else if (wireChunk.type === "usage") {
-						usage = {
-							promptTokens: wireChunk.usage.prompt_tokens ?? 0,
-							completionTokens: wireChunk.usage.completion_tokens ?? 0,
-							totalTokens: wireChunk.usage.total_tokens ?? 0,
-							requestId,
-							model
-						};
-						push({
-							type: "usage",
-							usage
-						});
-					}
-					result = await withChunkIdleTimeout(() => iterator.next(), params.chunkIdleTimeoutMs ?? this.chunkIdleTimeoutMs, () => streamController.abort(), this.logger);
-				}
-			} catch (error) {
-				try {
-					await iterator.return?.();
-				} catch {}
-				streamController.abort();
-				const normalized = normalizeError(error, params.signal);
-				if (normalized.type === "timeout") this.breaker?.recordFailure();
-				if (usage && normalized.type !== "aborted") this.reportUsageFailure(usage, normalized, attempt, true);
-				fail(normalized);
-				rejectFinal(normalized);
-				return;
-			}
-			finish();
-			this.breaker?.recordSuccess();
-			try {
-				const wireToolCalls = toolCallAcc.size ? [...toolCallAcc.entries()].sort(([indexA], [indexB]) => indexA - indexB).map(([, entry]) => ({
-					id: entry.id ?? "",
-					type: "function",
-					function: {
-						name: entry.name ?? "",
-						arguments: entry.args
-					}
-				})) : void 0;
-				const finalized = this.finalizeResponse(textAcc, wireToolCalls, params, useJson, usage, requestId, attempt);
-				resolveFinal(finalized);
-			} catch (error) {
-				rejectFinal(error);
-			}
-		})();
-		return {
-			chunks,
-			finalResult
-		};
+			release = void 0;
+			return result;
+		} finally {
+			release?.();
+		}
 	}
 	/**
 	* Checks every `ToolCall` against the `tools` that were offered, catching
-	* a hallucinated tool name early instead of letting it reach the
-	* application's dispatch table. Then runs each tool's `argumentsSchema`,
-	* if present, throwing `LLMError('validation')` on failure.
+	* 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 knownNames = new Set(tools.map((t) => t.name));
+		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) {
-			if (!knownNames.has(call.name)) throw new LLMError(`Model requested tool "${call.name}", which was not in the tools offered ([${[...knownNames].join(", ")}]).`, "api");
-			const definition = tools.find((t) => t.name === call.name);
+			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);
+			if (attempt > 0) await this.recoverDelay(requestId, model, attempt, lastError, signal);
+			onAttempt?.();
 			return await fn(attempt);
 		} catch (error) {
 			lastError = error;
@@ -1034,137 +1626,6 @@ var VernLLM = class {
 		throw lastError;
 	}
 	/**
-	* 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");
-	}
-	/** Applies per-call defaults and shapes params into the client's request object. */
-	buildRequestPayload(params) {
-		const { systemPrompt, userContent, history = [], maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema, tools, toolChoice } = params;
-		const temperature = params.temperature === void 0 ? this.defaultTemperature : params.temperature;
-		if (tools && (jsonSchema || params.schema)) throw new LLMError("`tools` cannot be combined with `jsonSchema`/`schema`: on Anthropic and Bedrock, jsonSchema is implemented internally as a forced single-tool call, which would collide with real tools. Use one or the other.", "validation");
-		if (tools && tools.length === 0) throw new LLMError("`tools` was an empty array. This is almost always a bug (e.g. a filtered tool list that ended up empty). An empty `tools` array still switches on tool-call mode (response shape, jsonMode default, wire format) with nothing for the model to call. Omit `tools` entirely for a normal call, or make sure the array is non-empty.", "validation");
-		if (tools) {
-			const seen = new Set();
-			const duplicates = new Set();
-			for (const tool of tools) {
-				if (seen.has(tool.name)) duplicates.add(tool.name);
-				seen.add(tool.name);
-			}
-			if (duplicates.size) throw new LLMError(`\`tools\` has duplicate name(s): [${[...duplicates].join(", ")}]. Tool names must be unique.`, "validation");
-		}
-		if (toolChoice && !tools) throw new LLMError("`toolChoice` was set without `tools`. There is nothing for it to choose between. Set `tools`, or remove `toolChoice`.", "validation");
-		if (tools && typeof toolChoice === "object" && !tools.some((t) => t.name === toolChoice.name)) throw new LLMError(`toolChoice names "${toolChoice.name}", which is not in \`tools\` ([${tools.map((t) => t.name).join(", ")}]).`, "validation");
-		const jsonMode = params.jsonMode ?? (tools ? false : true);
-		const useJson = jsonMode || Boolean(jsonSchema);
-		if (params.schema && !useJson) throw new LLMError("schema was provided but jsonMode: false disables JSON parsing, so nothing would validate it. Remove jsonMode: false, set jsonSchema, or remove schema.", "validation");
-		const responseFormat = this.buildResponseFormat(jsonSchema, useJson);
-		this.validateHistory(history);
-		const request = {
-			model,
-			...temperature !== 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
-		};
-	}
-	/** 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;
-	}
-	/**
 	* 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
@@ -1177,9 +1638,21 @@ var VernLLM = class {
 			completionTokens: response.usage.completion_tokens ?? 0,
 			totalTokens: response.usage.total_tokens ?? 0,
 			requestId,
-			model
+			model,
+			provider: this.providerName,
+			usedFallback: this.isFallback
 		};
 	}
+	/**
+	* 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.
+	*/
+	actualTokensFor(usage) {
+		if (!usage) return void 0;
+		return usage.totalTokens || usage.promptTokens + usage.completionTokens;
+	}
 	/** Reports token usage for a successful call, swallowing and logging any error `onUsage` throws. */
 	reportUsage(usage) {
 		if (!usage || !this.onUsage) return;
@@ -1225,180 +1698,536 @@ 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(`[VernLLM:${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));
 	}
 	/**
-	* 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
-	* `resolveKey`, if any, before deletion).
+	* 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.
 	*/
-	async deleteCache(key) {
-		if (!this.cache.delete) return;
-		await this.cache.delete(await this.resolveCacheKey(key));
+	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 = [];
 	/**
-	* Internal cache primitive around caller-supplied logic. Concurrent misses
-	* for the same `cacheKey` share a single in-flight call, avoiding cache
-	* stampedes.
-	*
-	* Not part of the public API. Backs the public `cachedCall()`, which
-	* always composes this with `call()` so cached results get the same
-	* retry/timeout/circuit-breaker guarantees as any other LLM call.
-	*
-	* @param params `cacheKey`, `ttl`, `fn` (the work to run on a cache
-	* 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.
+	* 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`.
 	*/
-	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, false);
+	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;
 	}
-	/** 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;
+	/** Pre-flight token estimate for a request, per the configured (or default) heuristic. */
+	estimate(request) {
+		return this.estimateTokensFn(request);
 	}
-	/** 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" });
+	/**
+	* 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);
 		}
-		return result;
+		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();
+		});
 	}
 	/**
-	* Streaming counterpart to `runCached`. Three cases:
-	*
-	* - Hit: no live generation to relay. Returns immediately with
-	*   `finalResult` resolved to the cached value and a one-shot `chunks`
-	*   replay built from it, so `for await (const c of chunks)` call sites
-	*   work identically on a hit or a miss. No usage hooks fire, since
-	*   nothing was actually spent.
-	* - Miss, nothing else in flight for this key: delegates to
-	*   `registerStreamTrigger`, which opens the stream and relays its
-	*   `chunks` live.
-	* - Miss, but another call for the same key is already in flight: this
-	*   call has no live chunks of its own to relay, so it's treated like a
-	*   delayed hit. `finalResult` shares the trigger's in-flight promise
-	*   (the same `this.inFlight` map non-streaming `runCached` uses, so
-	*   streaming and non-streaming `cachedCall`s for the same key coalesce
-	*   against each other too), and `chunks` is a one-shot replay built
-	*   once that promise resolves.
+	* 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.
 	*/
-	async runCachedStream(params, hasTools) {
-		const resolvedKey = await this.resolveCacheKey(params.cacheKey);
-		const resolvedParams = resolvedKey === params.cacheKey ? params : {
-			...params,
-			cacheKey: resolvedKey
+	tryAcquireBuckets(estimatedTokens) {
+		const taken = [];
+		const take = (bucket, amount) => {
+			if (!bucket) return true;
+			if (!bucket.tryTake(amount)) return false;
+			taken.push({
+				bucket,
+				amount
+			});
+			return true;
 		};
-		const cached = await this.cache.get(resolvedKey);
-		if (cached.hit) {
-			const value = cached.value;
+		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 {
-				chunks: buildReplayChunks(value, hasTools),
-				finalResult: Promise.resolve(value)
+				ok: false,
+				reason: "rpm"
 			};
 		}
-		const existing = this.inFlight.get(resolvedKey);
-		if (existing) {
-			const finalResult = withReservedUsage(resolvedParams, true, () => existing, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+		if (!take(this.tokens, estimatedTokens)) {
+			for (const entry of taken) entry.bucket.give(entry.amount);
 			return {
-				chunks: buildReplayChunksFromPromise(finalResult, hasTools),
-				finalResult
+				ok: false,
+				reason: "tpm"
 			};
 		}
-		return this.registerStreamTrigger(resolvedParams);
+		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
+			});
+		}
 	}
 	/**
-	* Opens the shared stream for a cache miss and tracks its settled value
-	* in `this.inFlight` until it resolves or rejects. Writes to the cache
-	* on success only, matching `runAndCache`.
-	*
-	* Registers the in-flight promise synchronously, before anything async
-	* runs, so a concurrent `cachedCall` for the same key always sees it in
-	* time to join instead of triggering its own stream. Settlement is
-	* wired onto the whole `withReservedUsageForStream` call rather than a
-	* line inside its callback, so any failure point (reserving usage,
-	* opening the stream, or the stream itself) reliably settles the
-	* in-flight entry instead of leaving it stuck.
+	* 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.
 	*/
-	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;
+	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
 			});
-			return {
-				chunks: opened.chunks,
-				finalResult: trackedResult
-			};
-		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
-		streamPromise.then((opened) => {
-			opened.finalResult.then(resolveInFlight, rejectInFlight);
-		}, (error) => {
-			rejectInFlight(error);
 		});
-		return streamPromise;
 	}
 	/** Logs a failed refundUsage attempt via the configured logger. */
 	logRefundError(logMessage, error) {
 		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
 	}
+	/**
+	* 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
+	* `resolveKey`, if any, before deletion).
+	*/
+	async deleteCache(key) {
+		await this.cacheOrchestrator.deleteCache(key);
+	}
 	async cachedCall(params) {
 		const { call: callParams,...cacheParams } = params;
 		const { reserveUsage, refundUsage,...restCallParams } = callParams;
 		if (reserveUsage || refundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedCall; set them at the top level instead.");
 		if (restCallParams.stream) {
 			const streamParams = restCallParams;
-			return this.runCachedStream({
+			return this.cacheOrchestrator.runCachedStream({
 				...cacheParams,
 				openStream: () => this.call(streamParams)
 			}, Boolean(restCallParams.tools));
@@ -1409,16 +2238,39 @@ var VernLLM = class {
 		});
 	}
 	/**
+	* @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/sse.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
@@ -1520,7 +2372,7 @@ function parseSseFrame(frame) {
 }
 
 //#endregion
-//#region src/internal/imageFormat.ts
+//#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
@@ -1544,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
 /**
@@ -1594,6 +2454,23 @@ function toAnthropicToolChoice(toolChoice) {
 	};
 }
 /**
+* 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 →
@@ -1601,21 +2478,38 @@ function toAnthropicToolChoice(toolChoice) {
 * point).
 *
 * Returns `toolName` alongside the body: when set, the model was forced to
-* call a single synthetic tool standing in for `jsonSchema` output, and
+* 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.
+* 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) {
+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 toolName = params.response_format?.type === "json_schema" ? params.response_format.json_schema.name.trim() : void 0;
-	if (params.response_format?.type === "json_schema" && !toolName) throw new LLMError("json_schema.name must not be empty.", "validation");
+	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 (params.response_format?.type === "json_schema" && toolName) {
-		const { schema, description, strict } = params.response_format.json_schema;
+	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,
@@ -1627,14 +2521,7 @@ function buildAnthropicRequestBody(params) {
 			name: toolName
 		};
 	} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
-	else if (params.tools?.length) {
-		tools = params.tools.map((t) => ({
-			name: t.function.name,
-			description: t.function.description,
-			input_schema: assertObjectSchema(t.function.parameters, t.function.name)
-		}));
-		toolChoice = toAnthropicToolChoice(params.tool_choice);
-	}
+	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,
@@ -1645,7 +2532,8 @@ function buildAnthropicRequestBody(params) {
 		...tools ? {
 			tools,
 			tool_choice: toolChoice
-		} : {}
+		} : {},
+		...outputFormat ? { output_config: { format: outputFormat } } : {}
 	};
 	return {
 		body,
@@ -1656,22 +2544,37 @@ function buildAnthropicRequestBody(params) {
 * 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.
+* 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) {
+function fromAnthropic(anthropicClient, options) {
+	const nativeStructuredOutputModels = options?.nativeStructuredOutputModels;
 	const rawMessagesCreate = anthropicClient.messages.create.bind(anthropicClient.messages);
 	return { chat: { completions: {
-		async create(params, options) {
-			const { body, toolName } = buildAnthropicRequestBody(params);
-			const response = await anthropicClient.messages.create(body, options);
+		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) {
@@ -1703,12 +2606,12 @@ function fromAnthropic(anthropicClient) {
 				}
 			};
 		},
-		async *createStream(params, options) {
-			const { body, toolName } = buildAnthropicRequestBody(params);
+		async *createStream(params, options$1) {
+			const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels);
 			const stream = await rawMessagesCreate({
 				...body,
 				stream: true
-			}, options);
+			}, options$1);
 			const blockKinds = new Map();
 			let inputTokens = 0;
 			let sawJsonTool = false;
@@ -1966,10 +2869,10 @@ function buildGeminiRequest(params) {
 * Anthropic.
 *
 * `tools` maps to Gemini's native `functionDeclarations`/`functionCall`;
-* `tool_choice` maps to `toolConfig.functionCallingConfig`. `jsonSchema`
-* and `tools` are mutually exclusive by the time a call reaches here
-* (enforced in vernLLM.ts), so `responseSchema` and `tools` never
-* both apply.
+* `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
@@ -2093,6 +2996,23 @@ 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 →
@@ -2100,21 +3020,42 @@ function toBedrockContent(blocks) {
 * check all happen exactly once).
 *
 * Returns `toolName` alongside the request: when set, the model was forced
-* to call a single synthetic tool standing in for `jsonSchema` output, and
-* both `create` and `createStream` need to know this so they can unwrap
-* that tool call back into plain text content instead of treating it like
-* a real tool call.
+* 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) {
+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 toolName = jsonSchema?.name.trim();
-	if (jsonSchema && !toolName) throw new LLMError("json_schema.name must not be empty.", "validation");
+	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;
-	if (jsonSchema) {
+	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,
@@ -2125,17 +3066,10 @@ function buildBedrockRequest(params, toolUseSupportedModels) {
 			toolChoice: { tool: { name: toolName } }
 		};
 	} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
-	else if (params.tools?.length) toolConfig = {
-		tools: params.tools.map((t) => ({ toolSpec: {
-			name: t.function.name,
-			description: t.function.description,
-			inputSchema: { json: t.function.parameters }
-		} })),
-		toolChoice: toBedrockToolChoice(params.tool_choice)
-	};
-	if (jsonSchema && toolUseSupportedModels) {
+	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 jsonSchema structured output requires Converse tool use.`, "validation");
+		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 = {
@@ -2146,7 +3080,8 @@ function buildBedrockRequest(params, toolUseSupportedModels) {
 			...params.temperature !== void 0 ? { temperature: params.temperature } : {},
 			maxTokens: params.max_tokens
 		},
-		...toolConfig ? { toolConfig } : {}
+		...toolConfig ? { toolConfig } : {},
+		...outputConfig ? { outputConfig } : {}
 	};
 	return {
 		request,
@@ -2161,22 +3096,36 @@ function buildBedrockRequest(params, toolUseSupportedModels) {
 * 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` maps to Converse's native `toolConfig`/`toolUse`/`toolResult`;
-* `tool_choice` maps to `toolConfig.toolChoice`. Mutually exclusive with
-* `jsonSchema` by the time a call reaches here (enforced in vernLLM.ts).
+* `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
@@ -2192,9 +3141,10 @@ function buildBedrockRequest(params, toolUseSupportedModels) {
 */
 function fromBedrock(bedrockClient, options) {
 	const toolUseSupportedModels = options?.toolUseSupportedModels;
+	const nativeStructuredOutputModels = options?.nativeStructuredOutputModels;
 	return { chat: { completions: {
 		async create(params, requestOptions) {
-			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels);
+			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels);
 			const response = await bedrockClient.converse(request, requestOptions);
 			let text;
 			let wireToolCalls;
@@ -2232,7 +3182,7 @@ function fromBedrock(bedrockClient, options) {
 		},
 		async *createStream(params, requestOptions) {
 			if (!bedrockClient.converseStream) throw new LLMError("stream: true requires a Bedrock client with converseStream", "validation");
-			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels);
+			const { 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) {
@@ -2694,5 +3644,5 @@ const fromAtlasCloud = fromOpenAICompatible;
 const from01AI = fromOpenAICompatible;
 
 //#endregion
-export { CircuitBreaker, ConsoleLogger, InMemoryCacheAdapter, LLMError, NormalizedCacheAdapter, SSE_PING, TieredCacheAdapter, VernLLM, from01AI, fromAnthropic, fromAnyscale, fromAtlasCloud, fromBaseten, fromBedrock, fromCerebras, fromCloudflareWorkersAI, fromDeepInfra, fromDeepSeek, fromFeatherless, fromFetch, fromFireworks, fromFriendli, fromGemini, fromGitHubModels, fromGroq, fromHyperbolic, fromInferenceNet, fromInfermatic, fromKlusterAI, fromLMStudio, fromLambdaLabs, fromLepton, fromMiniMax, fromMistral, fromMoonshot, fromNebius, fromNovita, fromNvidiaNIM, fromOllama, fromOpenAICompatible, fromOpenRouter, fromParasail, fromPerplexity, fromSambaNova, fromSiliconFlow, fromSnowflakeCortex, fromStepFun, fromTogether, fromVLLM, fromVercelAIGateway, fromXAI, fromZhipu, isLLMError, isToolCallResult, parseSseStream };
+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