vern-llm 1.6.0 → 1.7.0

package/dist/index.cjs

@@ -209,6 +209,15 @@ function extractRetryAfterMs(err, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
 	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,
@@ -238,6 +247,54 @@ async function waitForRetry(delay, signal) {
 		signal?.addEventListener("abort", onAbort, { once: true });
 	});
 }
+/**
+* Runs `getResult` after reserving usage, if a `reserveUsage` hook was
+* provided. `refundUsage` fires only if a reservation was actually made.
+* `onRefundError` is called (instead of throwing) whenever a refund attempt
+* itself fails, so a broken refund hook never masks the original error.
+*/
+async function withReservedUsage(params, coalesced, getResult, signal, onRefundError) {
+	if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+	let reserved = false;
+	try {
+		if (params.reserveUsage) {
+			await params.reserveUsage({
+				coalesced,
+				signal
+			});
+			reserved = true;
+		}
+	} catch (error) {
+		if (signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
+		throw new LLMError(error instanceof Error ? error.message : "Usage reservation failed", "quota_exceeded", void 0, void 0, error);
+	}
+	const refund = async (logMessage) => {
+		try {
+			await params.refundUsage?.({
+				coalesced,
+				signal
+			});
+		} catch (refundError) {
+			onRefundError(logMessage, refundError);
+		}
+	};
+	if (signal?.aborted) {
+		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
+		throw new LLMError("LLM request aborted", "aborted");
+	}
+	let result;
+	try {
+		result = await getResult();
+	} catch (error) {
+		if (reserved) await refund("[VernLLM] refundUsage failed");
+		throw error;
+	}
+	if (signal?.aborted) {
+		if (reserved) await refund("[VernLLM] refundUsage failed after abort");
+		throw new LLMError("LLM request aborted", "aborted");
+	}
+	return result;
+}
 
 //#endregion
 //#region src/logger.ts
@@ -312,16 +369,73 @@ var InMemoryCacheAdapter = class {
 		}
 	}
 };
+/**
+* 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/vernLLM.ts
 /**
-* A resilient wrapper around an LLM chat completions client, this is VernLLM!
+* A resilient layer around an LLM chat completions client, this is VernLLM!
 *
-* Adds retry with exponential 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
+* Adds retry with backoff/jitter, per-attempt timeouts, an optional circuit breaker,
+* JSON parsing with optional schema validation, usage tracking, and an
+* optional response cache, all configurable, all opt-in beyond sensible
+* defaults.
 */
 var VernLLM = class {
 	client;
@@ -338,18 +452,18 @@ var VernLLM = class {
 	logger;
 	breaker;
 	/**
-	* @param options: Client, model, and all tunables (retries, timeout,
-	* backoff, cache, circuit breaker, logger, etc). See VernLLMOptions in `types.ts`
-	* for individual defaults
+	* @param options - Client, model, and tunables. Notable defaults:
+	* `maxRetries` 1, `timeoutMs` 25000, `baseDelayMs` 500 (exponential backoff
+	* base), `defaultMaxTokens` 1000, `cache` an in-memory adapter,
+	* `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
 	*/
 	constructor(options) {
 		this.client = options.client;
 		this.model = options.model;
-		const retryConfig = this.resolveRetryConfig(options);
-		this.maxRetries = retryConfig.maxRetries;
-		this.timeoutMs = retryConfig.timeoutMs;
-		this.baseDelayMs = retryConfig.baseDelayMs;
-		this.defaultMaxTokens = retryConfig.defaultMaxTokens;
+		this.maxRetries = options.maxRetries ?? 1;
+		this.timeoutMs = options.timeoutMs ?? 25e3;
+		this.baseDelayMs = options.baseDelayMs ?? 500;
+		this.defaultMaxTokens = options.defaultMaxTokens ?? 1e3;
 		this.cache = options.cache ?? new InMemoryCacheAdapter();
 		this.nonRetryableStatus = options.nonRetryableStatus ?? [
 			400,
@@ -360,72 +474,40 @@ var VernLLM = class {
 		];
 		this.parseJson = options.parseJson ?? defaultParseJson;
 		this.onUsage = options.onUsage;
-		this.logger = this.resolveLogger(options);
-		this.breaker = this.resolveCircuitBreaker(options);
-	}
-	/**
-	* Resolves retry/timeout/token defaults from the given options,
-	* falling back to the librarys built-in defaults for anything unset
-	*/
-	resolveRetryConfig(options) {
-		return {
-			maxRetries: options.maxRetries ?? 1,
-			timeoutMs: options.timeoutMs ?? 25e3,
-			baseDelayMs: options.baseDelayMs ?? 500,
-			defaultMaxTokens: options.defaultMaxTokens ?? 1e3
-		};
+		this.logger = options.logger ?? new ConsoleLogger(options.debug ?? false);
+		this.breaker = options.circuitBreaker ? new CircuitBreaker(options.circuitBreaker === true ? void 0 : options.circuitBreaker) : void 0;
 	}
-	/**
-	* Returns the caller supplied logger, or a console-based logger whose
-	* debug output is gated by the `debug` option (defaulting to off,
-	* so response content isn't unintentionally written to logs)
-	*/
-	resolveLogger(options) {
-		return options.logger ?? new ConsoleLogger(options.debug ?? false);
+	/** Resolves a cache key through the adapter when it supports normalization. */
+	async resolveCacheKey(key) {
+		return this.cache.resolveKey ? await this.cache.resolveKey(key) : key;
 	}
 	/**
-	* Builds a circuit breaker if `circuitBreaker` is truthy on the
-	* options. Passing `true` uses default thresholds, passing an options
-	* object tunes them. Returns undefined when the breaker is disabled
-	*/
-	resolveCircuitBreaker(options) {
-		if (!options.circuitBreaker) return void 0;
-		return new CircuitBreaker(options.circuitBreaker === true ? void 0 : options.circuitBreaker);
-	}
-	/**
-	* Makes a single logical LLM call, transparently retrying on failure
-	* according to the configured retry policy
-	*
-	* Fails fast if the circuit breaker is open or the signal is already
-	* aborted, before any request is dispatched. On exhausting all
-	* retries, records a circuit breaker failure and rejects with a
-	* normalized LLMError
+	* Makes a single logical LLM call, retrying on failure per the configured
+	* policy. Fails fast if the breaker is open or the signal is already
+	* aborted. On exhausting retries, records a breaker failure and rejects
+	* with a normalized LLMError.
 	*
-	* @param params : System/user content plus per call overrides
-	* (model, temperature, jsonMode, schema, signal, etc)
-	* @returns The parsed and optionally schema-validated response, or
-	* the raw string content when jsonMode is disabled
+	* @param params - System/user content plus per-call overrides (model,
+	* temperature, jsonMode, schema, signal, etc). See `CallParams`.
+	* @returns The parsed (and optionally schema-validated) response, or the
+	* raw string content when `jsonMode` is false and no `jsonSchema` is set.
 	*/
 	async call(params) {
 		this.breaker?.assertClosed();
 		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
 		const requestId = params.requestId ?? (0, crypto.randomUUID)();
-		return this.withReservedUsage(params, false, async () => {
+		return withReservedUsage(params, false, async () => {
 			try {
 				return await this.retryWithBackoff(() => this.executeCall(params, requestId), requestId, params.signal);
 			} catch (error) {
-				const normalized = this.normalizeError(error, params.signal);
+				const normalized = normalizeError(error, params.signal);
 				if (normalized.type !== "validation" && normalized.type !== "parse" && normalized.type !== "aborted") this.breaker?.recordFailure();
 				this.logger.debug(`[vern:${requestId}] error:\n${describeError(error)}`);
 				throw normalized;
 			}
-		}, params.signal);
+		}, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
 	}
-	/**
-	* Runs `fn`, retrying with backoff according to `shouldRetry` policy
-	* Purely mechanical: knows nothing about LLM specifics beyond the retry
-	* predicate, so its testable independent of request/response shaping
-	*/
+	/** Runs `fn`, retrying with backoff according to `shouldRetry`. */
 	async retryWithBackoff(fn, requestId, signal) {
 		let lastError;
 		for (let attempt = 0; attempt <= this.maxRetries; attempt++) try {
@@ -438,24 +520,9 @@ var VernLLM = class {
 		throw lastError;
 	}
 	/**
-	* Converts any thrown value into a well-typed LLMError for the public
-	* API surface. Preserves an existing LLMError as is, reports aborted
-	* signals as such, classifies errors carrying an http status as
-	* type api, and otherwise falls back to a generic unknown error.
-	*/
-	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);
-	}
-	/**
 	* Performs a single attempt: builds the request, dispatches it with a
-	* timeout, and shapes the response. Throws on an empty response so
-	* the retry loop treats it like any other transient failure. Records
-	* usage and a circuit breaker success before returning
+	* timeout, and shapes the response. Throws on an empty response so the
+	* retry loop treats it like any other transient failure.
 	*/
 	async executeCall(params, requestId) {
 		const { useJson, model, request } = this.buildRequestPayload(params);
@@ -473,12 +540,8 @@ var VernLLM = class {
 		return result;
 	}
 	/**
-	* Anthropic and Gemini both require strict user/assistant alternation
-	* (and reject or silently mishandle two consecutive same-role turns), so
-	* this validates `history` up front rather than letting a malformed
-	* request surface as a confusing provider-side error. Thrown as a
-	* validation LLMError, which `shouldRetry` never retries, since retrying
-	* the same malformed input can't succeed
+	* Validates `history` alternates user/assistant turns, since providers
+	* like Anthropic/Gemini reject or mishandle consecutive same-role turns.
 	*/
 	validateHistory(history) {
 		let previousRole;
@@ -489,12 +552,7 @@ var VernLLM = class {
 		}
 		if (previousRole === "user") throw new LLMError("The last entry in history is a \"user\" turn, which would collide with the current userContent turn. history must end with an \"assistant\" turn (or be empty).", "validation");
 	}
-	/**
-	* Applies per call defaults and shapes the params into the request
-	* object expected by the underlying client, including the resolved
-	* response format. Also returns whether JSON parsing should be
-	* applied to the response and which model was ultimately used
-	*/
+	/** Applies per-call defaults and shapes params into the client's request object. */
 	buildRequestPayload(params) {
 		const { systemPrompt, userContent, history = [], temperature = .2, jsonMode = true, maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema } = params;
 		const useJson = jsonMode || Boolean(jsonSchema);
@@ -529,11 +587,10 @@ var VernLLM = class {
 		};
 	}
 	/**
-	* Chooses the response format to send to the provider. A provider
-	* native json schema takes priority when supplied, constraining
-	* 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
+	* 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 {
@@ -547,15 +604,7 @@ var VernLLM = class {
 		};
 		return useJson ? { type: "json_object" } : void 0;
 	}
-	/**
-	* Reports token usage to the caller supplied onUsage callback, when
-	* both a callback was configured and the provider actually returned
-	* usage data on this response. A no op otherwise.
-	*
-	* A throwing onUsage callback is logged and swallowed rather than
-	* propagated, so a broken billing/metrics hook can't fail or retrigger
-	* retries on an otherwise-successful call.
-	*/
+	/** Reports token usage to `onUsage`, swallowing and logging any error it throws. */
 	recordUsage(response, requestId, model) {
 		if (!response.usage || !this.onUsage) return;
 		try {
@@ -570,12 +619,7 @@ var VernLLM = class {
 			this.logger.error("[VernLLM] onUsage failed", { message: error instanceof Error ? error.message : "unknown" });
 		}
 	}
-	/**
-	* Parses the raw response content as JSON and, when a schema is
-	* supplied, validates the parsed value against it. Throws a parse
-	* type LLMError on malformed JSON and a validation type LLMError,
-	* carrying the schemas issues, on a failed validation
-	*/
+	/** Parses response content as JSON and validates it against `schema` when supplied. */
 	parseAndValidate(content, schema) {
 		let parsed;
 		try {
@@ -590,12 +634,10 @@ var VernLLM = class {
 		return result.data;
 	}
 	/**
-	* Waits out the backoff delay for a given retry attempt, logging the
-	* attempt for observability before the wait begins. Honors a
-	* Retry-After header on the failed attempt's error when present
-	* (capped at the same maxDelayMs as backoff), otherwise falls back to
-	* exponential backoff exactly as before. Rejects early if the signal
-	* aborts during the wait
+	* 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`).
 	*/
 	async recoverDelay(requestId, attempt, error, signal) {
 		const retryAfterMs = extractRetryAfterMs(error);
@@ -603,58 +645,56 @@ var VernLLM = class {
 		this.logger.warn(`[vern:${requestId}] recovery attempt ${attempt}/${this.maxRetries}, waiting ${delay}ms` + (retryAfterMs !== void 0 ? " (honoring Retry-After)" : ""));
 		await waitForRetry(delay, signal);
 	}
-	/**
-	* Decides whether a failed attempt is worth retrying. Never retries
-	* once the signal has aborted, never retries a parse or validation
-	* failure since those stem from the response content rather than a
-	* transient fault, and never retries a status code the caller has
-	* marked as non retryable. Retries everything else
-	*/
+	/** 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;
 		const status = extractStatus(error);
-		if (status !== void 0 && this.nonRetryableStatus.includes(status)) return false;
-		return true;
+		return !(status !== void 0 && this.nonRetryableStatus.includes(status));
 	}
 	/**
 	* Removes a cached response by key when the configured cache adapter
-	* supports deletion.
-	*
-	* Cache invalidation remains the responsibility of the caller because
+	* 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) {
 		if (!this.cache.delete) return;
-		await this.cache.delete(key);
+		await this.cache.delete(await this.resolveCacheKey(key));
 	}
 	/**
-	* Cache wrapper around caller-supplied logic. `params.fn` should invoke
-	* `this.call(...)` (see `cachedLLMCall`); retry/timeout handling is left
-	* to the caller.
+	* Cache wrapper around caller-supplied logic. Concurrent misses for the
+	* same `cacheKey` share a single in-flight call, avoiding cache stampedes.
 	*
-	* Concurrent misses for the same `cacheKey` share a single in-flight call,
-	* avoiding cache stampedes. Each caller still receives its own
-	* `reserveUsage`/`refundUsage` callbacks with coalescing metadata.
+	* @param params - `cacheKey`, `ttl`, `fn` (the work to run on a cache
+	* miss, typically `() => this.call(...)`), and optional
+	* `reserveUsage`/`refundUsage`/`signal`. See `CachedCallParams`.
+	* @returns The cached value on a hit, or the result of `fn()` on a miss.
 	*/
 	async cachedCall(params) {
-		const cached = await this.cache.get(params.cacheKey);
+		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(params.cacheKey);
-		const coalesced = existing !== void 0;
-		if (coalesced) return this.withReservedUsage(params, coalesced, () => existing, params.signal);
-		return this.registerTrigger(params, coalesced);
+		const existing = this.inFlight.get(resolvedKey);
+		if (existing) return withReservedUsage(resolvedParams, true, () => existing, params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
+		return this.registerTrigger(resolvedParams, false);
 	}
-	/** Starts the shared fn() call for a cache miss, reserving usage first, and registers it in the in-flight map until it settles */
+	/** 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 = this.withReservedUsage(params, coalesced, () => this.runAndCache(params), params.signal);
+		const resultPromise = withReservedUsage(params, coalesced, () => this.runAndCache(params), params.signal, (logMessage, error) => this.logRefundError(logMessage, error));
 		this.inFlight.set(params.cacheKey, resultPromise);
 		resultPromise.catch(() => {}).finally(() => {
 			this.inFlight.delete(params.cacheKey);
 		});
 		return resultPromise;
 	}
-	/** Runs `fn` and writes its result to the cache. Only ever called once per cacheKey per in-flight window, from registerTrigger */
+	/** Runs `fn` and writes its result to the cache. */
 	async runAndCache(params) {
 		const result = await params.fn();
 		try {
@@ -664,76 +704,31 @@ var VernLLM = class {
 		}
 		return result;
 	}
-	/**
-	* Runs `getResult` after reserving usage, if a `reserveUsage` hook was
-	* provided. `refundUsage` fires only if a reservation was actually made,
-	* i.e. `reserveUsage` was provided and it resolved successfully. If
-	* `reserveUsage` is omitted entirely, or if it throws, there is nothing to
-	* refund, so `refundUsage` is not invoked in either case.
-	*
-	* Shared by `cachedCall()`/`registerTrigger()` and `call()`, so it only
-	* depends on the usage hooks rather than LLM request concerns.
-	*/
-	async withReservedUsage(params, coalesced, getResult, signal) {
-		let reserved = false;
-		try {
-			if (params.reserveUsage) {
-				await params.reserveUsage({
-					coalesced,
-					signal
-				});
-				reserved = true;
-			}
-		} catch (error) {
-			throw new LLMError(error instanceof Error ? error.message : "Usage reservation failed", "quota_exceeded", void 0, void 0, error);
-		}
-		if (signal?.aborted) {
-			if (reserved) try {
-				await params.refundUsage?.({
-					coalesced,
-					signal
-				});
-			} catch (refundError) {
-				this.logger.error("[VernLLM] refundUsage failed after abort", { message: refundError instanceof Error ? refundError.message : "unknown" });
-			}
-			throw new LLMError("LLM request aborted", "aborted");
-		}
-		try {
-			return await getResult();
-		} catch (error) {
-			if (reserved) try {
-				await params.refundUsage?.({
-					coalesced,
-					signal
-				});
-			} catch (refundError) {
-				this.logger.error("[VernLLM] refundUsage failed", { message: refundError instanceof Error ? refundError.message : "unknown" });
-			}
-			throw error;
-		}
+	/** Logs a failed refundUsage attempt via the configured logger. */
+	logRefundError(logMessage, error) {
+		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
 	}
 	/**
 	* Convenience wrapper composing `call` + `cachedCall`, so cached LLM calls
-	* automatically get retry/timeout/circuit-breaker behavior without callers
-	* having to remember to wire `fn: () => this.call(...)` themselves.
+	* automatically get retry/timeout/circuit-breaker behavior. `reserveUsage`/
+	* `refundUsage` are read from the top-level params only.
 	*
-	* `reserveUsage`/`refundUsage` are read from the top-level params only — if
-	* `call` also sets them, they're ignored, since `call()` now performs its
-	* own reservation. Honoring both would reserve/refund twice per logical
-	* cachedLLMCall (once via cachedCall's wrapping, once via the inner call()).
+	* @param params - `cachedCall` params (`cacheKey`, `ttl`, etc, minus `fn`)
+	* plus `call`, the `CallParams` to pass through to `this.call(...)`.
+	* @returns The cached value on a hit, or the freshly-called result on a miss.
 	*/
 	async cachedLLMCall(params) {
 		const { call: callParams,...cacheParams } = params;
-		const { reserveUsage: _innerReserveUsage, refundUsage: _innerRefundUsage,...restCallParams } = callParams;
-		if (_innerReserveUsage || _innerRefundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedLLMCall; set them at the top level instead.");
+		const { reserveUsage: innerReserveUsage, refundUsage: innerRefundUsage,...restCallParams } = callParams;
+		if (innerReserveUsage || innerRefundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedLLMCall; set them at the top level instead.");
 		return this.cachedCall({
 			...cacheParams,
 			fn: () => this.call(restCallParams)
 		});
 	}
 	/**
-	* Returns the current circuit breaker state, or undefined when no
-	* circuit breaker was configured on this instance
+	* @returns The current circuit breaker state (`'closed' | 'open' |
+	* 'half-open'`), or undefined if no circuit breaker was configured.
 	*/
 	getCircuitState() {
 		return this.breaker?.getState();
@@ -790,15 +785,14 @@ function toAnthropicContent(blocks) {
 * Wraps an Anthropic SDK client so it satisfies the same `LLMClient`
 * interface VernLLM uses for OpenAI/Groq.
 *
-* `response_format: json_schema` is mapped to Anthropics forced tool-use:
+* `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,
-* and `tool_choice` forces the model to call it, so the output is
-* provider-constrained to match the schema rather than merely instructed
-* to via prompt text (the same guarantee OpenAIs native `json_schema` mode
-* gives, built on Anthropics tool-calling primitive instead).
+* `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_object` (no schema to build a tool from) falls
-* back to a system-prompt instruction, since theres nothing to constrain
+* back to a system-prompt instruction, since there's nothing to constrain
 * generation against.
 */
 function fromAnthropic(anthropicClient) {
@@ -809,11 +803,12 @@ function fromAnthropic(anthropicClient) {
 		let jsonInstruction;
 		let tools;
 		if (params.response_format?.type === "json_schema" && toolName) {
-			const { schema, description } = params.response_format.json_schema;
+			const { schema, description, strict } = params.response_format.json_schema;
 			tools = [{
 				name: toolName,
 				description,
-				input_schema: schema
+				input_schema: schema,
+				strict
 			}];
 		} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
 		const system = [systemMessage?.content, jsonInstruction].filter(Boolean).join("\n\n");
@@ -855,7 +850,7 @@ function fromAnthropic(anthropicClient) {
 /**
 * Translates a VernLLM `ContentBlock[]` into Gemini's native `parts` array:
 * text blocks become `{ text }`, image blocks become inline data parts
-* (`{ inlineData: { mimeType, data } }`), Geminis shape for embedding raw
+* (`{ inlineData: { mimeType, data } }`), Gemini's shape for embedding raw
 * base64 image bytes directly in the request.
 */
 function toGeminiParts(blocks) {
@@ -866,14 +861,14 @@ function toGeminiParts(blocks) {
 }
 /**
 * Wraps a Gemini client so it satisfies the `LLMClient` interface VernLLM
-* uses for OpenAI/Groq. Geminis shape differs on nearly every axis: a
-* `contents` array instead of `messages`, a separate `systemInstruction`
-* field instead of a `system` role message, `generationConfig` instead of
-* top-level `temperature`/`max_tokens`, and native JSON Schema support via
-* `responseMimeType: 'application/json'` + `responseSchema` (so `jsonSchema`
-* is provider-enforced here, unlike the Anthropic adapters prompt-embedding
-* fallback). `reasoning_effort` has no equivalent. Geminis thinking models
-* use a token budget, not an effort tier, so its dropped, same as Anthropic.
+* uses for OpenAI-compatible APIs. Gemini's shape differs on nearly every
+* axis: a `contents` array instead of `messages`, a separate
+* `systemInstruction` field instead of a `system` role message,
+* `generationConfig` instead of top-level `temperature`/`max_tokens`, and
+* native JSON Schema support via `responseMimeType: 'application/json'` +
+* `responseSchema`. `reasoning_effort` has no equivalent. Gemini's thinking
+* models use a token budget, not an effort tier, so it's dropped, same as
+* Anthropic.
 */
 function fromGemini(geminiClient) {
 	return { chat: { completions: { async create(params, options) {
@@ -885,7 +880,13 @@ function fromGemini(geminiClient) {
 			maxOutputTokens: params.max_tokens
 		};
 		if (wantsJson) generationConfig.responseMimeType = "application/json";
-		if (params.response_format?.type === "json_schema") generationConfig.responseSchema = params.response_format.json_schema.schema;
+		if (params.response_format?.type === "json_schema") {
+			const { schema, description } = params.response_format.json_schema;
+			generationConfig.responseSchema = {
+				...schema,
+				...description ? { description } : {}
+			};
+		}
 		const response = await geminiClient.generateContent({
 			model: params.model,
 			contents: conversationMessages.map((m) => ({
@@ -942,39 +943,50 @@ function toBedrockContent(blocks) {
 /**
 * Wraps a Bedrock Converse-API client so it satisfies the `LLMClient`
 * interface VernLLM uses for OpenAI/Groq. The Converse API is unified
-* across Bedrocks model families (Anthropic, Titan, Llama, Mistral, etc.),
+* across Bedrock's model families (Anthropic, Titan, Llama, Mistral, etc.),
 * so unlike raw per-model Bedrock invocation, this one adapter works
 * 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 Converses `toolConfig`: a
-* single tool is defined from the schema and `toolChoice` forces the model
-* to call it, constraining output at generation time rather than merely
-* instructing for it via prompt text. Native tool support varies by model
-* family (most current-generation ones support it via Converse; check your
-* specific `modelId` if a call fails with an unsupported-parameter error).
+* `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
+* `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.
 */
-function fromBedrock(bedrockClient) {
-	return { chat: { completions: { async create(params, options) {
+function fromBedrock(bedrockClient, options) {
+	const toolUseSupportedModels = options?.toolUseSupportedModels;
+	return { chat: { completions: { async create(params, requestOptions) {
 		const systemMessage = params.messages.find((m) => m.role === "system");
 		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
-		const toolName = params.response_format?.type === "json_schema" ? params.response_format.json_schema.name : void 0;
+		const jsonSchema = params.response_format?.type === "json_schema" ? params.response_format.json_schema : void 0;
+		const toolName = jsonSchema?.name.trim();
+		if (jsonSchema && !toolName) throw new LLMError("json_schema.name must not be empty.", "validation");
 		let jsonInstruction;
 		let toolConfig;
-		if (params.response_format?.type === "json_schema" && toolName) {
-			const { schema, description } = params.response_format.json_schema;
+		if (jsonSchema) {
+			const { schema, description, strict } = jsonSchema;
 			toolConfig = {
 				tools: [{ toolSpec: {
 					name: toolName,
 					description,
-					inputSchema: { json: schema }
+					inputSchema: { json: schema },
+					strict
 				} }],
 				toolChoice: { tool: { name: toolName } }
 			};
 		} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
+		if (jsonSchema && toolUseSupportedModels) {
+			const isSupported = Array.isArray(toolUseSupportedModels) ? toolUseSupportedModels.includes(params.model) : toolUseSupportedModels(params.model);
+			if (!isSupported) throw new LLMError(`Bedrock model "${params.model}" is not listed in toolUseSupportedModels, but jsonSchema structured output requires Converse tool use.`, "validation");
+		}
 		const systemParts = [systemMessage?.content, jsonInstruction].filter((s) => Boolean(s));
 		const response = await bedrockClient.converse({
 			modelId: params.model,
@@ -988,7 +1000,7 @@ function fromBedrock(bedrockClient) {
 				maxTokens: params.max_tokens
 			},
 			...toolConfig ? { toolConfig } : {}
-		}, options);
+		}, requestOptions);
 		let text;
 		if (toolName) {
 			const toolUseBlock = response.output?.message?.content?.find((block) => block.toolUse?.name === toolName);
@@ -1201,6 +1213,8 @@ exports.CircuitBreaker = CircuitBreaker
 exports.ConsoleLogger = ConsoleLogger
 exports.InMemoryCacheAdapter = InMemoryCacheAdapter
 exports.LLMError = LLMError
+exports.NormalizedCacheAdapter = NormalizedCacheAdapter
+exports.TieredCacheAdapter = TieredCacheAdapter
 exports.VernLLM = VernLLM
 exports.from01AI = from01AI
 exports.fromAnthropic = fromAnthropic