vern-llm 2.2.0 → 2.4.0

package/dist/index.cjs

@@ -25,23 +25,273 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 const crypto = __toESM(require("crypto"));
 
 //#region src/types/errors.ts
+/**
+* Tool contract codes: a model or provider response defect, not a
+* transient provider fault. Deterministic on the wire request, so
+* retrying can't change the outcome and it shouldn't count toward the
+* circuit breaker either. Shared by `LLMError.retryable` below and by
+* `CallExecutor`'s own retry/breaker accounting, so the two can't drift
+* apart.
+*/
+const NON_RETRYABLE_TOOL_CONTRACT_CODES = new Set([
+	"unknown_tool",
+	"duplicate_tool_call_id",
+	"tool_choice_none_violated",
+	"unexpected_tool_calls"
+]);
+/**
+* Local rate-limit codes: the call never reached the provider, so it says
+* nothing about the provider's health, and retrying either just requeues
+* behind the same limit (the two queue codes) or can never succeed at all
+* (`rate_limit_capacity_exceeded`). Shared for the same reason as
+* {@link NON_RETRYABLE_TOOL_CONTRACT_CODES}.
+*/
+const LOCAL_RATE_LIMIT_CODES = new Set([
+	"rate_limit_queue_full",
+	"rate_limit_queue_timeout",
+	"rate_limit_capacity_exceeded"
+]);
+/**
+* Types that are never worth retrying on their own: deterministic
+* caller-input, model-response, or cancellation failures rather than a
+* transient provider fault.
+*/
+const NON_RETRYABLE_TYPES = new Set([
+	"parse",
+	"validation",
+	"invalid_params",
+	"aborted"
+]);
+/**
+* Shared retryability rule behind both `LLMError.retryable` and
+* `LLMErrorSnapshot.retryable`. Pulled out so the two can't drift apart:
+* a snapshot is a point-in-time copy of an error's fields, and this is
+* one of them, so it has to be computed the same way in both places.
+*/
+function computeRetryable(type, code) {
+	if (NON_RETRYABLE_TYPES.has(type)) return false;
+	if (code && NON_RETRYABLE_TOOL_CONTRACT_CODES.has(code)) return false;
+	if (code && LOCAL_RATE_LIMIT_CODES.has(code)) return false;
+	return true;
+}
+/**
+* Returns `issues` unchanged when it can survive `JSON.stringify`.
+* Most `issues` values are VernLLM's own structured shapes (see
+* `LLMErrorIssuesByCode`) and always safe. The one exception is a
+* schema validation failure, where `issues` is a caller supplied
+* `SchemaLike` validator's own `error: unknown`, not controlled by
+* VernLLM and not guaranteed to be circular free. Rather than silently
+* dropping it in that case, this returns a marker string so a reader
+* of serialized output can tell "no issues data" apart from "issues
+* existed but could not be shown".
+*/
+function safeIssues(issues) {
+	if (issues === void 0) return void 0;
+	try {
+		JSON.stringify(issues);
+		return issues;
+	} catch {
+		return "[Unserializable: issues contained a circular reference]";
+	}
+}
+/**
+* Returns a JSON safe, independent copy of `body`, or a marker string if
+* `body` can't survive `JSON.stringify` (e.g. a circular reference). A
+* request body built from adapter-transformed messages is normally
+* always plain data, but tool call arguments or a caller supplied
+* `cause`-adjacent value could in principle carry a circular reference,
+* so this guards the same way `safeIssues` does rather than assuming it
+* can't happen. Unlike `safeIssues`, this clones rather than returning
+* the same reference: the object backing a request body can still be
+* mutated by adapter code between when a request is dispatched and when
+* an attempt is later recorded as failed (e.g. `fromGemini` sets
+* `request.config` in place), so returning the same reference here could
+* make a stored snapshot silently reflect a later, different state than
+* what was actually sent.
+*/
+function safeBody(body) {
+	if (body === void 0) return void 0;
+	try {
+		return JSON.parse(JSON.stringify(body));
+	} catch {
+		return "[Unserializable: request body contained a circular reference]";
+	}
+}
+const AUTH_HEADER_NAMES = new Set([
+	"authorization",
+	"x-api-key",
+	"x-goog-api-key",
+	"api-key"
+]);
+/** Removes auth headers before a request snapshot is built. Case insensitive on header names. */
+function stripAuthHeaders(headers) {
+	if (headers === void 0) return void 0;
+	const out = {};
+	for (const [key, value] of Object.entries(headers)) if (!AUTH_HEADER_NAMES.has(key.toLowerCase())) out[key] = value;
+	return out;
+}
+/**
+* Depth cap for `safeAttempts`, guarding against a pathological,
+* self referential `attempts` array. `attempts` is a public
+* `LLMErrorOptions` field, so a caller can construct one by hand; this
+* keeps that path bounded the same way a circular `issues` value is
+* bounded, rather than assuming well formed input.
+*/
+const MAX_ATTEMPTS_DEPTH = 20;
+/**
+* Returns a copy of `attempts` with every nested snapshot's `issues`
+* re-checked through `safeIssues`, recursively through each snapshot's
+* own `attempts`. Needed for two reasons: `safeIssues` returns a safe
+* `issues` value by reference, so a shared object can be mutated into a
+* circular one after the snapshot was created, and `attempts` is a
+* public constructor option, so a caller can hand build a `RetryAttempt`
+* (or a whole `LLMErrorSnapshot`) with a circular `issues` and pass it
+* in directly, never touching `toSnapshot()` at all. The same applies to
+* `request`: its `body` is re-checked through `safeBody`, and its
+* `headers` are re-stripped through `stripAuthHeaders`, so a hand built
+* `RetryAttempt.request` can't smuggle an auth header past `toSnapshot()`
+* either. Extra fields on an attempt (e.g. `FallbackAttempt`'s
+* `provider`/`model`) are preserved.
+*/
+function safeAttempts(attempts, depth = 0) {
+	if (attempts === void 0) return void 0;
+	if (depth >= MAX_ATTEMPTS_DEPTH) return [];
+	return attempts.map((attempt) => ({
+		...attempt,
+		error: {
+			...attempt.error,
+			issues: safeIssues(attempt.error.issues),
+			attempts: safeAttempts(attempt.error.attempts, depth + 1)
+		},
+		request: attempt.request && {
+			...attempt.request,
+			body: safeBody(attempt.request.body),
+			headers: stripAuthHeaders(attempt.request.headers)
+		}
+	}));
+}
+/**
+* Builds a point-in-time, plain data copy of one attempt's outgoing
+* request. Mirrors `LLMError.toSnapshot()`: never thrown or dispatched
+* again, safe to serialize and store. A plain function rather than a
+* method, since unlike `LLMError` a request has no throwable identity or
+* derived state worth wrapping in a class.
+*
+* `startedAt` is optional so existing call sites (and tests) that don't
+* care about exact timing keep working, but a caller that has a real
+* capture time should always pass it: this function may run well after
+* the request was actually dispatched (e.g. `callExecutor` only builds
+* the snapshot once an attempt has failed), so defaulting to `Date.now()`
+* here would record failure-handling time, not request-start time.
+*/
+function toRequestSnapshot(provider, model, body, headers, startedAt = Date.now()) {
+	return {
+		provider,
+		model,
+		body: safeBody(body),
+		headers: stripAuthHeaders(headers),
+		startedAt
+	};
+}
 var LLMError = class extends Error {
-	constructor(message, type, status, issues, cause, retryAfterMs, code) {
+	status;
+	issues;
+	cause;
+	retryAfterMs;
+	/** Stable discriminator within `type`. Absent on errors predating it. */
+	code;
+	/** Every attempt made before this error was thrown, in order. Absent when nothing was retried. */
+	attempts;
+	constructor(message, type, options = {}) {
 		super(message);
 		this.type = type;
-		this.status = status;
-		this.issues = issues;
-		this.cause = cause;
-		this.retryAfterMs = retryAfterMs;
-		this.code = code;
 		this.name = "LLMError";
+		this.status = options.status;
+		this.issues = options.issues;
+		this.cause = options.cause;
+		this.retryAfterMs = options.retryAfterMs;
+		this.code = options.code;
+		this.attempts = options.attempts;
+	}
+	/**
+	* Computed purely from `type`/`code`, independent of any specific call's
+	* `nonRetryableStatus` list. False for `parse`/`validation`/
+	* `invalid_params`/`aborted` types (the caller's own input, the model's
+	* own response, or intentional cancellation, none of which are the
+	* provider being unhealthy), the tool contract codes, and the local
+	* rate limit codes. Subclasses (see `FallbackExhaustedError`) may
+	* override this when `type` alone carries no retry signal.
+	*/
+	get retryable() {
+		return computeRetryable(this.type, this.code);
+	}
+	/**
+	* Copies this error's fields into an {@link LLMErrorSnapshot}, for
+	* recording as a `RetryAttempt`/`FallbackAttempt`. `retryable` is
+	* captured here since a snapshot has no getter of its own. `cause` is
+	* not copied, see `LLMErrorSnapshot`'s own doc. `issues` and every
+	* nested `attempts` entry's own `issues` go through `safeAttempts`,
+	* since a schema validation failure's `issues` is a caller supplied
+	* value, not controlled by VernLLM, and `attempts` is itself a public
+	* constructor option a caller can hand build.
+	*/
+	toSnapshot() {
+		return {
+			message: this.message,
+			type: this.type,
+			status: this.status,
+			issues: safeIssues(this.issues),
+			retryAfterMs: this.retryAfterMs,
+			code: this.code,
+			retryable: this.retryable,
+			attempts: safeAttempts(this.attempts)
+		};
+	}
+	/**
+	* Controls what `JSON.stringify(err)` produces. Omits `cause` for the
+	* same reason `toSnapshot()` does: `cause` is `unknown` and never
+	* validated by VernLLM, and some SDK errors carry circular structures
+	* `JSON.stringify` cannot serialize at all. Read `err.cause` directly
+	* instead. `issues`, including every nested `attempts` entry's own
+	* `issues`, goes through `safeAttempts` for the same reason: a schema
+	* validation failure's `issues` is caller supplied and not guaranteed
+	* circular free. Also includes `message` and `retryable`, which a
+	* plain property walk would otherwise miss: `message` is
+	* non-enumerable on `Error`, and `retryable` is a getter, not an own
+	* property.
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			type: this.type,
+			status: this.status,
+			issues: safeIssues(this.issues),
+			retryAfterMs: this.retryAfterMs,
+			code: this.code,
+			retryable: this.retryable,
+			attempts: safeAttempts(this.attempts)
+		};
 	}
-	/** Every tool contract failure in one response, when there is more than one. */
-	toolIssues;
 };
 function isLLMError(err) {
 	return err instanceof LLMError;
 }
+/**
+* Narrows `err.issues` to the exact shape {@link LLMErrorIssuesByCode} maps
+* `code` to, for any code listed there. `code` stays the only discriminator
+* VernLLM uses; this just gives that existing check a typed return instead
+* of requiring a manual cast of `issues`:
+*
+* ```ts
+* if (isLLMError(err) && hasIssues(err, 'duplicate_tool_names')) {
+*   console.log(err.issues.names); // string[], no cast needed
+* }
+* ```
+*/
+function hasIssues(err, code) {
+	return err.code === code && err.issues !== void 0;
+}
 
 //#endregion
 //#region src/types/cache.ts
@@ -171,7 +421,12 @@ function isToolCallResult(result) {
 //#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"]);
+const TOOL_CONTRACT_CODES = new Set([
+	"unknown_tool",
+	"duplicate_tool_call_id",
+	"tool_choice_none_violated",
+	"unexpected_tool_calls"
+]);
 /**
 * 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)`.
@@ -194,10 +449,30 @@ const defaultFallbackOn = (error) => {
 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, last?.retryAfterMs, "fallback_exhausted");
+		super(`${attempts.length} provider${attempts.length === 1 ? "" : "s"} attempted and failed: ${attempts.map((a) => `${a.provider}(${a.error.type})`).join(" then ")}`, "fallback_exhausted", {
+			status: last?.status,
+			cause: last,
+			retryAfterMs: last?.retryAfterMs,
+			code: "fallback_exhausted",
+			attempts
+		});
 		this.attempts = attempts;
 	}
+	/**
+	* `type: 'fallback_exhausted'` by itself says nothing about whether
+	* retrying could help; the reason the last target failed does. Defers to
+	* that attempt's own `retryable` instead of anything about this class's
+	* own type.
+	*/
+	get retryable() {
+		const last = this.attempts[this.attempts.length - 1]?.error;
+		return last ? last.retryable : super.retryable;
+	}
 };
+/** Narrows `err` to {@link FallbackExhaustedError}, for direct access to its `attempts` (`provider`/`model` per failed target) without a manual `instanceof` check. */
+function isFallbackExhaustedError(err) {
+	return err instanceof FallbackExhaustedError;
+}
 
 //#endregion
 //#region src/internal/execution/usage.utils.ts
@@ -219,7 +494,7 @@ async function reserve(params, 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);
+		throw new LLMError(error instanceof Error ? error.message : "Usage reservation failed", "quota_exceeded", { cause: error });
 	}
 }
 /**
@@ -419,13 +694,30 @@ var CacheOrchestrator = class {
 	*/
 	async deleteCache(key) {
 		if (!this.cache.delete) return;
-		await this.cache.delete(await this.resolveCacheKey(key));
+		try {
+			await this.cache.delete(await this.resolveCacheKey(key));
+		} catch (error) {
+			this.logger.warn(`[VernLLM] cache delete failed: ${error instanceof Error ? error.message : "unknown"}`);
+		}
 	}
 	/** Logs a failed refundUsage attempt via the configured logger. */
 	logRefundError(logMessage, error) {
 		this.logger.error(logMessage, { message: error instanceof Error ? error.message : "unknown" });
 	}
 	/**
+	* Reads from the cache, treating a failed adapter read as a miss rather
+	* than letting it fail the call. The request still falls through to a
+	* real provider call, but that fallback is now logged instead of silent.
+	*/
+	async getCached(key) {
+		try {
+			return await this.cache.get(key);
+		} catch (error) {
+			this.logger.warn(`[VernLLM] cache read failed: ${error instanceof Error ? error.message : "unknown"}`);
+			return { hit: false };
+		}
+	}
+	/**
 	* Internal cache primitive around caller-supplied logic. Concurrent misses
 	* for the same `cacheKey` share a single in-flight call, avoiding cache
 	* stampedes.
@@ -445,7 +737,7 @@ var CacheOrchestrator = class {
 			...params,
 			cacheKey: resolvedKey
 		};
-		const cached = await this.cache.get(resolvedKey);
+		const cached = await this.getCached(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));
@@ -466,7 +758,7 @@ var CacheOrchestrator = class {
 		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" });
+			this.logger.warn(`[VernLLM] cache write failed: ${error instanceof Error ? error.message : "unknown"}`);
 		}
 		return result;
 	}
@@ -495,7 +787,7 @@ var CacheOrchestrator = class {
 			...params,
 			cacheKey: resolvedKey
 		};
-		const cached = await this.cache.get(resolvedKey);
+		const cached = await this.getCached(resolvedKey);
 		if (cached.hit) {
 			const value = cached.value;
 			return {
@@ -544,7 +836,7 @@ var CacheOrchestrator = class {
 				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" });
+					this.logger.warn(`[VernLLM] cache write failed: ${error instanceof Error ? error.message : "unknown"}`);
 				}
 				return value;
 			}, (error) => {
@@ -586,6 +878,7 @@ var CircuitBreaker = class {
 	threshold;
 	cooldownMs;
 	onStateChange;
+	/** Whether this breaker tracks failures per model instead of one shared circuit. Read by `CallExecutor`/`VernLLM` to report per-target in `getCircuitStates`. */
 	isolateByModel;
 	sharedBucket = newBucket();
 	bucketsByModel = new Map();
@@ -631,12 +924,12 @@ var CircuitBreaker = class {
 		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");
+			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", { code: "circuit_cooling_down" });
 			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");
+		if (bucket.trialInFlight) throw new LLMError("Circuit half-open. A trial request is already in flight. Try again shortly.", "circuit_open", { code: "circuit_trial_in_flight" });
 		bucket.trialInFlight = true;
 	}
 	recordSuccess(model) {
@@ -671,6 +964,33 @@ var CircuitBreaker = class {
 	getState(model) {
 		return this.lookupBucket(model)?.state ?? "closed";
 	}
+	/**
+	* Manually opens the circuit, as if `threshold` consecutive failures had
+	* just happened, e.g. to pull a provider out of rotation ahead of known
+	* maintenance. Resets the cooldown window from now, same as a real
+	* threshold-crossing failure would, and clears any in-flight half-open
+	* trial since it no longer applies once the circuit is (re)opened.
+	*/
+	open(model) {
+		const bucket = this.ensureBucketFor(model);
+		bucket.openedAt = Date.now();
+		bucket.trialInFlight = false;
+		this.transition(bucket, "open", model);
+	}
+	/**
+	* Manually closes the circuit and resets its failure count, e.g. once a
+	* provider is confirmed healthy again without waiting out the cooldown.
+	* Mirrors `recordSuccess`'s bookkeeping (including dropping the
+	* per-model bucket under `isolateByModel`, once idle) but without
+	* requiring an actual successful call first.
+	*/
+	close(model) {
+		const bucket = this.ensureBucketFor(model);
+		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);
+	}
 };
 
 //#endregion
@@ -789,7 +1109,7 @@ async function withTimeout(fn, timeoutMs, externalSignal) {
 	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");
+		if (controller.signal.aborted && !externalSignal?.aborted && err instanceof DOMException && err.name === "AbortError") throw new LLMError("Request timed out", "timeout", { code: "request_timeout" });
 		throw err;
 	} finally {
 		clearTimeout(timer);
@@ -822,7 +1142,7 @@ function withChunkIdleTimeout(next, timeoutMs, onIdle, logger) {
 		const timer = setTimeout(() => {
 			settled = true;
 			onIdle?.();
-			reject(new LLMError(`No stream chunk received for ${activeTimeoutMs}ms (idle timeout)`, "timeout"));
+			reject(new LLMError(`No stream chunk received for ${activeTimeoutMs}ms (idle timeout)`, "timeout", { code: "idle_timeout" }));
 		}, clampTimeoutMs(activeTimeoutMs));
 		next().then((result) => {
 			clearTimeout(timer);
@@ -987,20 +1307,99 @@ function describeError(err) {
 	} 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.code === void 0) {
-			if (error.status === 429) error.code = "provider_rate_limited";
-			else if (error.status === 401 || error.status === 403) error.code = "invalid_credentials";
+/**
+* Maps an HTTP status to its corresponding `LLMErrorCode`, derived purely
+* from the status itself so it applies the same way regardless of which
+* adapter or client raised the error. Used both when building a fresh
+* `LLMError` and when filling in a `code` on an already-normalized one
+* that doesn't have one yet, so the two paths can't drift apart.
+*/
+function codeForStatus(status) {
+	switch (status) {
+		case 429: return "provider_rate_limited";
+		case 401: return "authentication";
+		case 403: return "authorization";
+		case 404: return "not_found";
+		case 413: return "payload_too_large";
+		default: return status >= 500 ? "server_error" : void 0;
+	}
+}
+/**
+* Whether a provider's error response actually contains anything a person
+* could act on. Some providers return a non-2xx status with **no body at
+* all** for certain field-validation failures (Mistral's OpenAI-compatible
+* endpoint does this, for example, when a request includes a field the
+* target model doesn't support). SDKs built on top of `openai` render that
+* specific case as a message like `"400 status code (no body)"`.
+*
+* Derived from the object's own `error`/`message` fields directly, rather
+* than from whatever `describeError` rendered, because `describeError`
+* falls back to serializing the *whole* thrown value when neither field is
+* present or meaningful. That fallback is local echo (e.g. just the
+* `status` a caller passed in), not provider diagnostic content, and
+* treating it as "detail" defeats the whole point of this check.
+*/
+const NO_BODY_MESSAGE_PATTERN = /\(no body\)/i;
+function isEmptyObject(value) {
+	return Object.keys(value).length === 0;
+}
+function hasNoDiagnosticDetail(error) {
+	if (error && typeof error === "object") {
+		const { error: errorField, message } = error;
+		if (errorField !== void 0 && errorField !== null) {
+			const isEmptyString = typeof errorField === "string" && errorField.trim().length === 0;
+			const isEmptyStruct = typeof errorField === "object" && isEmptyObject(errorField);
+			if (!isEmptyString && !isEmptyStruct) return false;
+		}
+		if (typeof message === "string") {
+			const trimmed = message.trim();
+			return trimmed.length === 0 || NO_BODY_MESSAGE_PATTERN.test(trimmed);
 		}
+		return true;
+	}
+	return true;
+}
+/**
+* Converts any thrown value into a well-typed LLMError. `attempts`, when
+* given, is the accumulated record of every attempt made before `error`
+* was thrown; it's passed straight into the constructed error's options
+* rather than assigned onto the error afterward, so `attempts` is always
+* settled once, through the constructor, like every other field on
+* `LLMError`.
+*/
+function normalizeError(error, signal, attempts) {
+	if (signal?.aborted) return new LLMError("LLM request aborted", "aborted", { attempts });
+	if (error instanceof LLMError) {
+		if (error.code === void 0 && error.status !== void 0) error.code = codeForStatus(error.status);
+		if (error.attempts === void 0 && attempts !== void 0) error.attempts = attempts;
 		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" : status === 401 || status === 403 ? "invalid_credentials" : void 0);
-	return new LLMError("LLM request failed", "unknown", void 0, void 0, error, retryAfterMs, isNetworkError(error) ? "connection_failed" : void 0);
+	if (status !== void 0) {
+		const description = describeError(error);
+		const code = codeForStatus(status);
+		const isRequestValidationStatus = code === void 0;
+		const message = hasNoDiagnosticDetail(error) ? isRequestValidationStatus ? `LLM request failed with status ${status} and no error detail from the provider. This usually means a field or value in the request isn't supported by the specific model (for example, a reasoning/thinking parameter the model doesn't accept), rather than a transport or auth problem.` : `LLM request failed with status ${status} and no error detail from the provider.` : `LLM request failed: ${description}`;
+		return new LLMError(message, "api", {
+			status,
+			cause: error,
+			retryAfterMs,
+			code,
+			attempts
+		});
+	}
+	if (isNetworkError(error)) return new LLMError("LLM request failed", "network", {
+		cause: error,
+		retryAfterMs,
+		code: "connection_failed",
+		attempts
+	});
+	return new LLMError("LLM request failed", "unknown", {
+		cause: error,
+		retryAfterMs,
+		attempts
+	});
 }
 
 //#endregion
@@ -1049,7 +1448,7 @@ function parseWireToolCalls(wireToolCalls) {
 		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");
+			throw new LLMError(`Invalid JSON arguments for tool call "${wc.function.name}"`, "parse", { code: "tool_arguments_parse_failed" });
 		}
 		return {
 			id: wc.id,
@@ -1062,11 +1461,22 @@ function parseWireToolCalls(wireToolCalls) {
 //#endregion
 //#region src/internal/execution/requestBuilder.ts
 /**
+* Serializes `ConversationTurn` assistant content for the wire. Strings
+* pass through unchanged. Parsed JSON values are `JSON.stringify`'d.
+*/
+function serializeAssistantContent(content) {
+	return typeof content === "string" ? content : JSON.stringify(content);
+}
+/**
 * 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
+* Owns every check that depends only on the caller's own input shape, not
+* on execution: history alternation, duplicate/empty tool lists,
+* `toolChoice` naming a real tool. All deterministic on the call site's
+* own input and never touch the network, so every throw here is
+* `type: 'invalid_params'`, not `'validation'` (which is reserved for the
+* model/provider's own response failing a contract check). 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`.
@@ -1075,16 +1485,24 @@ var RequestBuilder = class {
 	model;
 	defaultMaxTokens;
 	defaultTemperature;
+	defaultReasoningEffort;
+	defaultBudgetTokens;
+	supportsJsonObjectMode;
 	constructor(options) {
 		this.model = options.model;
 		this.defaultMaxTokens = options.defaultMaxTokens;
 		this.defaultTemperature = options.defaultTemperature;
+		this.defaultReasoningEffort = options.defaultReasoningEffort;
+		this.defaultBudgetTokens = options.defaultBudgetTokens;
+		this.supportsJsonObjectMode = options.supportsJsonObjectMode;
 	}
 	/** 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 { systemPrompt, userContent, history = [], maxTokens = this.defaultMaxTokens, model = this.model, 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");
+		const reasoningEffort = params.reasoningEffort === void 0 ? this.defaultReasoningEffort : params.reasoningEffort;
+		const budgetTokens = params.budgetTokens === void 0 ? this.defaultBudgetTokens : params.budgetTokens;
+		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.", "invalid_params");
 		if (tools) {
 			const seen = new Set();
 			const duplicates = new Set();
@@ -1092,13 +1510,26 @@ var RequestBuilder = class {
 				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 (duplicates.size) throw new LLMError(`\`tools\` has duplicate name(s): [${[...duplicates].join(", ")}]. Tool names must be unique.`, "invalid_params", {
+				code: "duplicate_tool_names",
+				issues: { names: [...duplicates] }
+			});
 		}
-		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");
+		if (toolChoice && !tools) throw new LLMError("`toolChoice` was set without `tools`. There is nothing for it to choose between. Set `tools`, or remove `toolChoice`.", "invalid_params");
+		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(", ")}]).`, "invalid_params", {
+			code: "unknown_tool_choice",
+			issues: {
+				requested: toolChoice.name,
+				available: tools.map((t) => t.name)
+			}
+		});
+		const jsonModeExplicit = params.jsonMode;
+		const jsonMode = jsonModeExplicit ?? (tools ? false : true);
+		if (!this.supportsJsonObjectMode && !jsonSchema && jsonModeExplicit === true) throw new LLMError("jsonMode: true was set explicitly, but this client does not support `response_format: \"json_object\"` (see LLMClient.supportsJsonObjectMode). Neither Anthropic nor Bedrock has a field that mechanically guarantees JSON output for this mode. Use `jsonSchema` instead, which maps to a real constraint on both.", "invalid_params");
+		if (!this.supportsJsonObjectMode && !jsonSchema && jsonModeExplicit === void 0 && params.schema) throw new LLMError("`schema` was provided, which requires JSON output to validate against, but this client does not support `response_format: \"json_object\"` (see LLMClient.supportsJsonObjectMode) and no `jsonSchema` was set. Neither Anthropic nor Bedrock has a field that mechanically guarantees JSON output without one. Use `jsonSchema` instead, which maps to a real constraint on both and still runs `schema` against its parsed result.", "invalid_params");
+		const jsonModeEffective = !this.supportsJsonObjectMode && !jsonSchema && jsonModeExplicit === void 0 ? false : jsonMode;
+		const useJson = jsonModeEffective || 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.", "invalid_params");
 		const responseFormat = this.buildResponseFormat(jsonSchema, useJson);
 		this.validateHistory(history);
 		const request = {
@@ -1107,6 +1538,7 @@ var RequestBuilder = class {
 			max_tokens: maxTokens,
 			...responseFormat ? { response_format: responseFormat } : {},
 			...reasoningEffort ? { reasoning_effort: reasoningEffort } : {},
+			...budgetTokens !== void 0 && budgetTokens !== null ? { budget_tokens: budgetTokens } : {},
 			...tools ? { tools: toWireTools(tools) } : {},
 			...tools ? { tool_choice: this.buildWireToolChoice(toolChoice) } : {},
 			messages: [
@@ -1135,29 +1567,47 @@ var RequestBuilder = class {
 		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");
+				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`, "invalid_params");
+				if (!turn.toolResults?.length) throw new LLMError(`history[${index}] is a "tool" turn but has no toolResults`, "invalid_params");
 				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");
+				if (unknownIds.length) throw new LLMError(`history[${index}].toolResults references unknown toolCallId(s) [${unknownIds.join(", ")}]`, "invalid_params", {
+					code: "unknown_tool_result_ids",
+					issues: {
+						historyIndex: index,
+						ids: unknownIds
+					}
+				});
 				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");
+				if (duplicateIds.size) throw new LLMError(`history[${index}].toolResults has duplicate toolCallId(s) [${[...duplicateIds].join(", ")}]`, "invalid_params", {
+					code: "duplicate_tool_result_ids",
+					issues: {
+						historyIndex: index,
+						ids: [...duplicateIds]
+					}
+				});
 				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");
+				if (missingIds.length) throw new LLMError(`history[${index}] is missing toolResults for toolCallId(s) [${missingIds.join(", ")}]`, "invalid_params", {
+					code: "missing_tool_results",
+					issues: {
+						historyIndex: index,
+						ids: missingIds
+					}
+				});
 			} 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");
+				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}]`, "invalid_params");
+				if (previousTurn?.role === "assistant" && previousTurn.toolCalls?.length) throw new LLMError(`history[${index}] follows an assistant tool request without tool results`, "invalid_params");
 			}
 			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");
+		if (previousTurn?.role === "assistant" && previousTurn.toolCalls?.length) throw new LLMError("The last entry in history is an assistant tool request without tool results", "invalid_params");
+		if (previousTurn?.role === "user") throw new LLMError("The last entry in history is a \"user\" turn, which would collide with the current userContent turn.", "invalid_params");
 	}
 	/** Maps VernLLM's app-facing `ToolChoice` onto the OpenAI-shaped wire `tool_choice`. */
 	buildWireToolChoice(toolChoice) {
@@ -1184,9 +1634,13 @@ var RequestBuilder = class {
 		}));
 		if (turn.role === "assistant" && turn.toolCalls?.length) return [{
 			role: "assistant",
-			...turn.content ? { content: turn.content } : {},
+			...turn.content !== void 0 ? { content: serializeAssistantContent(turn.content) } : {},
 			tool_calls: toWireToolCalls(turn.toolCalls)
 		}];
+		if (turn.role === "assistant") return [{
+			role: "assistant",
+			content: serializeAssistantContent(turn.content === void 0 ? "" : turn.content)
+		}];
 		return [{
 			role: turn.role,
 			content: turn.content ?? ""
@@ -1320,10 +1774,12 @@ function buildStreamResult(iterator, first, options) {
 						complete: wireChunk.complete
 					});
 				} else if (wireChunk.type === "usage") {
+					const reasoningTokens = wireChunk.usage.completion_tokens_details?.reasoning_tokens;
 					usage = {
 						promptTokens: wireChunk.usage.prompt_tokens ?? 0,
 						completionTokens: wireChunk.usage.completion_tokens ?? 0,
 						totalTokens: wireChunk.usage.total_tokens ?? 0,
+						...reasoningTokens !== void 0 ? { reasoningTokens } : {},
 						requestId,
 						model,
 						provider: providerName,
@@ -1377,6 +1833,16 @@ function buildStreamResult(iterator, first, options) {
 //#endregion
 //#region src/internal/execution/callExecutor.ts
 /**
+* Identity function with its own parameter, used only to sidestep a TS
+* quirk: a `let` reassigned solely inside a nested closure (like
+* `retryWithBackoff`'s `onRequest`) gets narrowed to `undefined` at the
+* point it was last synchronously assigned, which would otherwise make
+* `lastRequestForAttempt` read as `never` at the point it's used below.
+*/
+function passThroughRequestSnapshot(snapshot) {
+	return snapshot;
+}
+/**
 * 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
@@ -1419,12 +1885,27 @@ var CallExecutor = class {
 		this.requestBuilder = new RequestBuilder({
 			model,
 			defaultMaxTokens: options.defaultMaxTokens,
-			defaultTemperature: options.defaultTemperature
+			defaultTemperature: options.defaultTemperature,
+			defaultReasoningEffort: options.defaultReasoningEffort,
+			defaultBudgetTokens: options.defaultBudgetTokens,
+			supportsJsonObjectMode: client.supportsJsonObjectMode ?? true
 		});
 	}
 	getCircuitState(model) {
 		return this.breaker?.getState(model);
 	}
+	/** Whether this target's breaker tracks failures per model. `false` if no breaker is configured. */
+	get isolateByModel() {
+		return this.breaker?.isolateByModel ?? false;
+	}
+	/** Manually opens this target's circuit breaker, if one is configured. No-op otherwise. */
+	openCircuit(model) {
+		this.breaker?.open(model);
+	}
+	/** Manually closes this target's circuit breaker, if one is configured. No-op otherwise. */
+	closeCircuit(model) {
+		this.breaker?.close(model);
+	}
 	/**
 	* Throws if the breaker is open for this target/model, exactly like the
 	* check `run`/`runStream` used to make internally. Exposed so `VernLLM`
@@ -1446,10 +1927,11 @@ var CallExecutor = class {
 	*/
 	async run(params, requestId, onAttempt) {
 		const model = params.model ?? this.model;
+		const attempts = [];
 		try {
-			return await this.retryWithBackoff((attempt) => this.executeCall(params, requestId, attempt), requestId, model, params.signal, onAttempt);
+			return await this.retryWithBackoff((attempt, onRequest) => this.executeCall(params, requestId, attempt, onRequest), requestId, model, params.signal, onAttempt, attempts);
 		} catch (error) {
-			const normalized = normalizeError(error, params.signal);
+			const normalized = normalizeError(error, params.signal, attempts.length > 0 ? attempts : void 0);
 			if (this.countsTowardBreaker(normalized)) this.breaker?.recordFailure(model);
 			this.logger.debug(`[VernLLM:${requestId}] error:\n${this.redactText(describeError(error))}`);
 			throw normalized;
@@ -1458,10 +1940,11 @@ var CallExecutor = class {
 	/** Streaming counterpart to `run`. Mirrors the old streaming branch of `VernLLM.call`. */
 	async runStream(params, requestId, onAttempt) {
 		const model = params.model ?? this.model;
+		const attempts = [];
 		try {
-			return await this.retryWithBackoff((attempt) => this.executeStreamCall(params, requestId, attempt), requestId, model, params.signal, onAttempt);
+			return await this.retryWithBackoff((attempt, onRequest) => this.executeStreamCall(params, requestId, attempt, onRequest), requestId, model, params.signal, onAttempt, attempts);
 		} catch (error) {
-			const normalized = normalizeError(error, params.signal);
+			const normalized = normalizeError(error, params.signal, attempts.length > 0 ? attempts : void 0);
 			if (this.countsTowardBreaker(normalized)) this.breaker?.recordFailure(model);
 			this.logger.debug(`[VernLLM:${requestId}] stream-open error:\n${this.redactText(describeError(error))}`);
 			throw normalized;
@@ -1474,8 +1957,9 @@ var CallExecutor = class {
 	* set. Throws on an empty response (no text and no tool_calls) so the
 	* retry loop treats it like any other transient failure.
 	*/
-	async executeCall(params, requestId, attempt) {
+	async executeCall(params, requestId, attempt, onRequest) {
 		const { useJson, model, request } = this.requestBuilder.build(params);
+		onRequest?.(toRequestSnapshot(this.providerName, model, request, void 0, Date.now()));
 		let release;
 		if (this.limiter) {
 			const acquired = await this.limiter.acquire(this.limiter.estimate(request), params.signal);
@@ -1529,11 +2013,11 @@ var CallExecutor = class {
 	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");
+			if (!content && !wireToolCalls?.length) throw new LLMError("Empty LLM response", "api", { code: "empty_response" });
 			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");
-				if (params.toolChoice === "none") throw new LLMError("Provider returned tool_calls despite toolChoice: 'none'.", "api", void 0, void 0, void 0, void 0, "tool_choice_none_violated");
+				if (!params.tools) throw new LLMError("Provider returned tool_calls but no `tools` were sent with this call.", "validation", { code: "unexpected_tool_calls" });
+				if (params.toolChoice === "none") throw new LLMError("Provider returned tool_calls despite toolChoice: 'none'.", "validation", { code: "tool_choice_none_violated" });
 				const toolCalls = parseWireToolCalls(wireToolCalls);
 				this.validateToolCallArguments(toolCalls, params.tools);
 				this.breaker?.recordSuccess(model);
@@ -1583,10 +2067,14 @@ var CallExecutor = class {
 	* not on the first chunk arriving, so a connection that opens but then
 	* dies mid-stream isn't masked as a success (see `buildStreamResult`).
 	*/
-	async executeStreamCall(params, requestId, attempt) {
+	async executeStreamCall(params, requestId, attempt, onRequest) {
 		const { useJson, model, request } = this.requestBuilder.build(params);
+		onRequest?.(toRequestSnapshot(this.providerName, model, request, void 0, Date.now()));
 		const completions = this.client.chat.completions;
-		if (!completions.createStream) throw new LLMError("stream: true requires a client/adapter with createStream", "validation");
+		if (!completions.createStream) throw new LLMError("stream: true requires a client/adapter with createStream", "invalid_params", {
+			code: "unsupported_capability",
+			issues: { capability: "createStream" }
+		});
 		const createStream = completions.createStream.bind(completions);
 		let release;
 		if (this.limiter) {
@@ -1647,13 +2135,13 @@ var CallExecutor = class {
 	* `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`).
+	* every call and thrown together as one `type: 'validation'` error with
+	* `issues: ToolIssue[]`, since retrying a request that already has these
+	* errors cannot help (excluded from retry by `type`) 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.
 	*/
 	validateToolCallArguments(toolCalls, tools) {
 		const known = new Map(tools.map((t) => [t.name, t]));
@@ -1675,28 +2163,51 @@ var CallExecutor = class {
 		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;
+			const message = toolIssues.length > 1 ? `${primary} (${toolIssues.length} tool call issues total, see error.issues.)` : primary;
+			throw new LLMError(message, "validation", {
+				code: unknownTool ? "unknown_tool" : "duplicate_tool_call_id",
+				issues: toolIssues
+			});
 		}
 		for (const call of toolCalls) {
 			const definition = known.get(call.name);
 			if (!definition?.argumentsSchema) continue;
 			const result = definition.argumentsSchema.safeParse(call.arguments);
-			if (!result.success) throw new LLMError(`Arguments for tool call "${call.name}" failed validation`, "validation", void 0, result.error);
+			if (!result.success) throw new LLMError(`Arguments for tool call "${call.name}" failed validation`, "validation", { issues: result.error });
 		}
 	}
-	/** Runs `fn`, retrying with backoff according to `shouldRetry`. */
-	async retryWithBackoff(fn, requestId, model, signal, onAttempt) {
+	/**
+	* Runs `fn`, retrying with backoff according to `shouldRetry`. When
+	* `attempts` is given, every failed attempt that is actually followed by
+	* a retry is recorded, in order. This mirrors `LLMError.attempts`'s
+	* contract: every attempt made before this error was thrown. The
+	* terminal failure is never pushed since it isn't a prior attempt, it
+	* is the error being thrown. `attempts` stays empty when nothing was
+	* retried, so no separate bookkeeping is needed at the call sites.
+	* Each failure is recorded as a snapshot (`LLMError.toSnapshot()`),
+	* not the live `LLMError`, per `RetryAttempt`'s contract.
+	*/
+	async retryWithBackoff(fn, requestId, model, signal, onAttempt, attempts) {
 		let lastError;
-		for (let attempt = 0; attempt <= this.maxRetries; attempt++) try {
-			if (attempt > 0) await this.recoverDelay(requestId, model, attempt, lastError, signal);
-			onAttempt?.();
-			return await fn(attempt);
-		} catch (error) {
-			lastError = error;
-			if (!this.shouldRetry(error, signal)) break;
+		let lastRequestForAttempt;
+		for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+			lastRequestForAttempt = void 0;
+			try {
+				if (attempt > 0) await this.recoverDelay(requestId, model, attempt, lastError, signal);
+				onAttempt?.();
+				return await fn(attempt, (req) => {
+					lastRequestForAttempt = req;
+				});
+			} catch (error) {
+				lastError = error;
+				const willRetry = attempt < this.maxRetries && this.shouldRetry(error, signal);
+				if (!willRetry) break;
+				attempts?.push({
+					index: attempt,
+					error: normalizeError(error, signal).toSnapshot(),
+					request: passThroughRequestSnapshot(lastRequestForAttempt)
+				});
+			}
 		}
 		throw lastError;
 	}
@@ -1708,10 +2219,12 @@ var CallExecutor = class {
 	*/
 	extractUsage(response, requestId, model) {
 		if (!response.usage) return void 0;
+		const reasoningTokens = response.usage.completion_tokens_details?.reasoning_tokens;
 		return {
 			promptTokens: response.usage.prompt_tokens ?? 0,
 			completionTokens: response.usage.completion_tokens ?? 0,
 			totalTokens: response.usage.total_tokens ?? 0,
+			...reasoningTokens !== void 0 ? { reasoningTokens } : {},
 			requestId,
 			model,
 			provider: this.providerName,
@@ -1766,7 +2279,7 @@ var CallExecutor = class {
 		if (parsed === null || parsed === void 0) throw new LLMError("Invalid JSON response", "parse");
 		if (!schema) return parsed;
 		const result = schema.safeParse(parsed);
-		if (!result.success) throw new LLMError("Schema validation failed", "validation", void 0, result.error);
+		if (!result.success) throw new LLMError("Schema validation failed", "validation", { issues: result.error });
 		return result.data;
 	}
 	/**
@@ -1779,7 +2292,7 @@ var CallExecutor = class {
 		const retryAfterMs = extractRetryAfterMs(error);
 		const delay = retryAfterMs ?? getBackoffDelay(this.baseDelayMs, attempt);
 		const retryAfterHonored = retryAfterMs !== void 0;
-		this.logger.warn(`[VernLLM:${requestId}] recovery attempt ${attempt}/${this.maxRetries}, waiting ${delay}ms` + (retryAfterHonored ? " (honoring Retry-After)" : ""));
+		this.logger.warn(`[VernLLM:${requestId}] recovery attempt ${attempt}/${this.maxRetries}, waiting ${Math.ceil(delay)}ms` + (retryAfterHonored ? " (honoring Retry-After)" : ""));
 		this.reportEvent({
 			kind: "retry",
 			requestId,
@@ -1793,15 +2306,10 @@ var CallExecutor = class {
 		});
 		await waitForRetry(delay, signal);
 	}
-	isNonRetryableToolContractError(error) {
-		return error instanceof LLMError && (error.code === "unknown_tool" || error.code === "duplicate_tool_call_id" || error.code === "tool_choice_none_violated");
-	}
 	/** 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;
+		if (error instanceof LLMError && !error.retryable) return false;
 		const status = extractStatus(error);
 		return !(status !== void 0 && this.nonRetryableStatus.includes(status));
 	}
@@ -1811,16 +2319,48 @@ var CallExecutor = class {
 	* reusing a call id, or a provider ignoring `toolChoice: 'none'` isn't
 	* the provider being unhealthy, it's a model/provider 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.
+	* shouldn't push a healthy provider's circuit toward opening. Same for
+	* a caller-input bug or a local rate-limit rejection: neither ever
+	* reached the provider at all. This is exactly what `LLMError.retryable`
+	* already excludes, so this defers to it directly.
 	*/
 	countsTowardBreaker(error) {
-		if (error.type === "validation" || error.type === "parse" || error.type === "aborted" || error.code === "local_rate_limit" || this.isNonRetryableToolContractError(error)) return false;
-		return true;
+		return error.retryable;
 	}
 };
 
+//#endregion
+//#region src/internal/logger.utils.ts
+/**
+* Wraps a `Logger` so a throwing implementation can never break the call
+* it's trying to describe. `logger` is user-supplied (`VernLLMOptions.logger`),
+* so a custom logger that ships to a file, Datadog, etc. can throw for
+* reasons unrelated to VernLLM. Wrap once at construction so every
+* downstream `this.logger.warn(...)` call stays as-is and is safe by
+* construction, instead of guarding each call site individually.
+*/
+function createSafeLogger(logger) {
+	return {
+		debug: safe(logger, "debug"),
+		warn: safe(logger, "warn"),
+		error: safe(logger, "error")
+	};
+}
+function safe(logger, method) {
+	const fn = logger[method].bind(logger);
+	return (...args) => {
+		try {
+			swallowRejection(fn(...args));
+		} catch {}
+	};
+}
+function isPromiseLike(value) {
+	return typeof value?.then === "function";
+}
+function swallowRejection(result) {
+	if (isPromiseLike(result)) Promise.resolve(result).catch(() => {});
+}
+
 //#endregion
 //#region src/logger.ts
 /**
@@ -1961,8 +2501,8 @@ var RateLimiter = class {
 	*/
 	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 (!Number.isFinite(estimatedTokens) || estimatedTokens < 0) throw new LLMError(`estimatedTokens must be a finite, non-negative number, got ${String(estimatedTokens)}`, "invalid_params");
+		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.`, "rate_limited", { code: "rate_limit_capacity_exceeded" });
 		if (this.queue.length === 0) {
 			const attempt = this.tryAcquireBuckets(estimatedTokens);
 			if (attempt.ok) return {
@@ -1975,7 +2515,7 @@ var RateLimiter = class {
 		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");
+		return new LLMError("Rate limit queue is full", "rate_limited", { code: "rate_limit_queue_full" });
 	}
 	enqueue(estimatedTokens, initialReason, signal) {
 		return new Promise((resolvePromise, rejectPromise) => {
@@ -2008,7 +2548,7 @@ var RateLimiter = class {
 				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"));
+				waiter.reject(new LLMError("Rate limit queue timed out before capacity was available", "rate_limited", { code: "rate_limit_queue_timeout" }));
 			}, this.maxQueueMs);
 			signal?.addEventListener("abort", onAbort, { once: true });
 			this.queue.push(waiter);
@@ -2108,7 +2648,7 @@ var RateLimiter = class {
 //#endregion
 //#region src/vernLLM.ts
 /**
-* A resilient layer around an LLM chat completions client. This is VernLLM!
+* A LLM call framework for resilience, observability and control. This is VernLLM!
 *
 * Adds retry with backoff and jitter, per-attempt timeouts, an optional
 * circuit breaker, JSON parsing with optional schema validation, usage
@@ -2142,12 +2682,14 @@ var VernLLM = class {
 	* `nonRetryableStatus` `[400, 401, 403, 404, 422]`, `debug` false.
 	*/
 	constructor(options) {
-		this.logger = options.logger ?? new ConsoleLogger(options.debug ?? false);
+		this.logger = createSafeLogger(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 primaryDefaultReasoningEffort = options.defaultReasoningEffort;
+		const primaryDefaultBudgetTokens = options.defaultBudgetTokens;
 		const primaryTarget = {
 			client: options.client,
 			model: options.model,
@@ -2158,6 +2700,8 @@ var VernLLM = class {
 			baseDelayMs: options.baseDelayMs,
 			defaultMaxTokens: options.defaultMaxTokens,
 			defaultTemperature: primaryDefaultTemperature,
+			defaultReasoningEffort: primaryDefaultReasoningEffort,
+			defaultBudgetTokens: primaryDefaultBudgetTokens,
 			nonRetryableStatus: options.nonRetryableStatus,
 			circuitBreaker: options.circuitBreaker,
 			rateLimit: options.rateLimit
@@ -2175,6 +2719,8 @@ var VernLLM = class {
 				baseDelayMs: target.baseDelayMs ?? options.baseDelayMs ?? 500,
 				defaultMaxTokens: target.defaultMaxTokens ?? options.defaultMaxTokens ?? 1e3,
 				defaultTemperature: target.defaultTemperature === void 0 ? primaryDefaultTemperature : target.defaultTemperature,
+				defaultReasoningEffort: target.defaultReasoningEffort === void 0 ? primaryDefaultReasoningEffort : target.defaultReasoningEffort,
+				defaultBudgetTokens: target.defaultBudgetTokens === void 0 ? primaryDefaultBudgetTokens : target.defaultBudgetTokens,
 				nonRetryableStatus: target.nonRetryableStatus ?? options.nonRetryableStatus ?? [
 					400,
 					401,
@@ -2235,7 +2781,7 @@ var VernLLM = class {
 					index: i - 1,
 					provider: executor.providerName,
 					model: params.model ?? executor.model,
-					error: normalized
+					error: normalized.toSnapshot()
 				});
 				const isLast = i === this.executors.length - 1;
 				const policyDecision = this.fallbackOn(normalized, { isLastTarget: isLast });
@@ -2254,7 +2800,7 @@ var VernLLM = class {
 				});
 			}
 		}
-		throw new LLMError("No provider targets configured", "unknown");
+		throw new LLMError("No provider targets configured", "invalid_params");
 	}
 	async call(params) {
 		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
@@ -2300,7 +2846,7 @@ var VernLLM = class {
 	async cachedCall(params) {
 		const { call: callParams,...cacheParams } = params;
 		const restCallParams = callParams;
-		if (restCallParams.reserveUsage || restCallParams.refundUsage) throw new LLMError("`reserveUsage`/`refundUsage` were set inside `call`, where cachedCall ignores them. Move them to the top level of the cachedCall() params, alongside cacheKey/ttl, instead.", "validation");
+		if (restCallParams.reserveUsage || restCallParams.refundUsage) throw new LLMError("`reserveUsage`/`refundUsage` were set inside `call`, where cachedCall ignores them. Move them to the top level of the cachedCall() params, alongside cacheKey/ttl, instead.", "invalid_params");
 		if (restCallParams.stream) {
 			const streamParams = restCallParams;
 			return this.cacheOrchestrator.runCachedStream({
@@ -2314,36 +2860,107 @@ 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.
+	* @param target.index Which target to read. Defaults to the primary.
+	* @param target.model Which model bucket to read, if the target isolates by model.
+	* @returns The breaker state, or `undefined` if that target has no breaker.
+	* @throws {RangeError} If `target.index` names no target. Lets a real
+	* target with no breaker (`undefined`) stay distinguishable from a
+	* target that doesn't exist.
 	*/
-	getCircuitState(model) {
-		return this.executors[0].getCircuitState(model);
+	getCircuitState(target) {
+		const executor = this.resolveExecutor(target?.index ?? 0, "getCircuitState");
+		this.warnIfModelUnsupported(executor.isolateByModel, target?.model, "getCircuitState");
+		return executor.getCircuitState(target?.model ?? executor.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.
+	* @param model Which model bucket to read, for targets that isolate by model.
+	* @returns Every target's state, in chain order.
 	*/
 	getCircuitStates(model) {
 		return this.executors.map((executor, index) => ({
 			provider: executor.providerName,
 			index,
 			isFallback: index > 0,
-			state: executor.getCircuitState(model)
+			isolateByModel: executor.isolateByModel,
+			state: executor.getCircuitState(model ?? executor.model)
 		}));
 	}
+	/**
+	* Manually opens a target's breaker, e.g. to pull a provider out of
+	* rotation ahead of known maintenance instead of waiting for it to fail.
+	*
+	* @param target.index Which target to open. Defaults to the primary.
+	* @param target.model Which model bucket to open, if the target isolates by model.
+	* @throws {RangeError} If `target.index` names no target.
+	*/
+	openCircuit(target) {
+		const executor = this.resolveExecutor(target?.index ?? 0, "openCircuit");
+		this.warnIfModelUnsupported(executor.isolateByModel, target?.model, "openCircuit");
+		executor.openCircuit(target?.model ?? executor.model);
+	}
+	/**
+	* Manually closes a target's breaker, e.g. once a provider is confirmed
+	* healthy again without waiting out the cooldown.
+	*
+	* @param target.index Which target to close. Defaults to the primary.
+	* @param target.model Which model bucket to close, if the target isolates by model.
+	* @throws {RangeError} If `target.index` names no target.
+	*/
+	closeCircuit(target) {
+		const executor = this.resolveExecutor(target?.index ?? 0, "closeCircuit");
+		this.warnIfModelUnsupported(executor.isolateByModel, target?.model, "closeCircuit");
+		executor.closeCircuit(target?.model ?? executor.model);
+	}
+	/** Resolves a target index so every circuit-breaker method agrees on what counts as valid. */
+	resolveExecutor(index, caller) {
+		const executor = this.executors[index];
+		if (!executor) throw new RangeError(`${caller}: no target at index ${index} (chain has ${this.executors.length} target${this.executors.length === 1 ? "" : "s"})`);
+		return executor;
+	}
+	/** Warns when `model` can't do anything on this target, so it's never silently ignored. */
+	warnIfModelUnsupported(isolateByModel, model, caller) {
+		if (model !== void 0 && !isolateByModel) this.logger.warn(`[VernLLM] ${caller}: \`model: '${model}'\` has no effect here. This target's circuitBreaker doesn't have isolateByModel on, so it only tracks one shared circuit regardless of \`model\`. Omit \`model\`, or set \`circuitBreaker.isolateByModel: true\` on this target if per-model tracking is what you want.`);
+	}
 };
+/**
+* Identity function preserving `params`'s own precise type, unlike a `:
+* CallParams<T>` annotation, which would widen `tools` away and break the
+* `ConditionalToolCallParams<T>` overload for `tools: someCondition ?
+* [tool] : undefined`. Use it when you need `call()` params in a named,
+* reusable variable; skip it when you can pass the object inline.
+*
+* ```ts
+* const params = defineCallParams({
+*   userContent: 'What is the weather?',
+*   tools: someCondition ? [weatherTool] : undefined,
+* });
+* const result = await llm.call(params);
+* // result: unknown | CallWithToolsResult<unknown>, same as inline
+* ```
+*
+* `T` isn't a parameter here; pin it via `llm.call<T>(params)` as usual.
+* `defineCachedCallParams` is the `cachedCall()` counterpart.
+*/
+function defineCallParams(params) {
+	return params;
+}
+/**
+* The `cachedCall()` counterpart to `defineCallParams`: preserves the
+* whole `{ cacheKey, ttl, call }` object, `call.tools` included, in one
+* named variable.
+*
+* ```ts
+* const params = defineCachedCallParams({
+*   cacheKey: 'weather-ny',
+*   ttl: 60,
+*   call: { userContent: 'What is the weather?', tools: someCondition ? [weatherTool] : undefined },
+* });
+* const result = await llm.cachedCall(params);
+* ```
+*/
+function defineCachedCallParams(params) {
+	return params;
+}
 
 //#endregion
 //#region src/adapters/internal/sse.ts
@@ -2382,7 +2999,7 @@ async function* parseSseStream(source) {
 		try {
 			text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
 		} catch (cause) {
-			throw new LLMError("Invalid UTF-8 in SSE stream", "parse", void 0, void 0, cause);
+			throw new LLMError("Invalid UTF-8 in SSE stream", "parse", { cause });
 		}
 		buffer = (buffer + text).replace(/\r\n/g, "\n").replace(/\r(?!$)/g, "\n");
 		let boundary$1 = buffer.indexOf("\n\n");
@@ -2398,7 +3015,7 @@ async function* parseSseStream(source) {
 	try {
 		buffer += decoder.decode();
 	} catch (cause) {
-		throw new LLMError("Invalid UTF-8 in SSE stream", "parse", void 0, void 0, cause);
+		throw new LLMError("Invalid UTF-8 in SSE stream", "parse", { cause });
 	}
 	buffer = buffer.replace(/\r$/, "\n");
 	let boundary = buffer.indexOf("\n\n");
@@ -2443,7 +3060,10 @@ function parseSseFrame(frame) {
 	try {
 		return JSON.parse(data);
 	} catch (cause) {
-		throw new LLMError(`Invalid JSON in SSE frame: ${data.slice(0, 200)}`, "parse", void 0, void 0, cause);
+		throw new LLMError(`Invalid JSON in SSE frame: ${data.slice(0, 200)}`, "parse", {
+			cause,
+			code: "stream_frame_invalid"
+		});
 	}
 }
 
@@ -2463,13 +3083,14 @@ const SUPPORTED_IMAGE_MIME_TYPES = [
 ];
 /**
 * Validates an `ImageBlock.mimeType` against the shared supported set.
-* Throws a non-retryable `LLMError('validation')`, since an unsupported
-* mimeType is a permanent failure, retrying the same input can't fix it,
-* the same way a schema-validation or JSON-parse failure isn't retried.
+* Throws a non-retryable `LLMError('invalid_params')`, since an unsupported
+* mimeType is a bug in the caller's own input, deterministic before any
+* request is built, the same class of failure as every other check in
+* `RequestBuilder`.
 */
 function assertSupportedImageMimeType(mimeType) {
 	if (SUPPORTED_IMAGE_MIME_TYPES.includes(mimeType)) return mimeType;
-	throw new LLMError(`Unsupported image mimeType "${mimeType}": expected one of ${SUPPORTED_IMAGE_MIME_TYPES.join(", ")}`, "validation");
+	throw new LLMError(`Unsupported image mimeType "${mimeType}": expected one of ${SUPPORTED_IMAGE_MIME_TYPES.join(", ")}`, "invalid_params");
 }
 
 //#endregion
@@ -2480,6 +3101,275 @@ function supportsNativeStructuredOutput(model, override) {
 	return Array.isArray(override) ? override.includes(model) : override(model);
 }
 
+//#endregion
+//#region src/adapters/internal/reasoningBudget.utils.ts
+const DEFAULT_EFFORT_TOKENS = {
+	minimal: 1024,
+	low: 4096,
+	medium: 16e3,
+	high: 32e3
+};
+/**
+* Merges a caller-supplied partial override over `DEFAULT_EFFORT_TOKENS`.
+* Called once per adapter instance (not per request), so a per-instance
+* override only needs to specify the tiers it actually wants to change.
+*
+* Throws `LLMError('invalid_params')` if the override doesn't keep the
+* tiers in strictly ascending order (`minimal < low < medium < high`).
+* `budgetTokensToEffort` buckets by walking the tiers low to high and
+* returning on the first one a value is `<=`, so an unordered table (e.g.
+* `low` above `medium`) wouldn't just produce a "wrong" bucket, it would
+* make some tiers unreachable outright, silently, with no signal to the
+* caller that their override doesn't do what they think it does.
+*/
+function resolveEffortTokenTable(override) {
+	if (!override) return DEFAULT_EFFORT_TOKENS;
+	const table = {
+		...DEFAULT_EFFORT_TOKENS,
+		...override
+	};
+	if (!(table.minimal < table.low && table.low < table.medium && table.medium < table.high)) throw new LLMError(`reasoningEffortTokens must keep tiers in strictly ascending order (minimal < low < medium < high), got ${JSON.stringify(table)}. An out-of-order override doesn't just misrank tiers, it can make some of them unreachable.`, "invalid_params");
+	return table;
+}
+/** Converts a `reasoningEffort` tier into the nearest `budgetTokens` value. */
+function effortToBudgetTokens(effort, table = DEFAULT_EFFORT_TOKENS) {
+	return table[effort];
+}
+/**
+* Converts a raw `budgetTokens` value into the nearest `reasoningEffort`
+* tier, for providers that only understand tiers. Buckets by the same
+* `table` `effortToBudgetTokens` produces its values from, so the two
+* functions agree with each other at the boundary values, as long as the
+* same (possibly overridden) table is passed to both. A value strictly
+* between two tiers (e.g. 4097, one above the default `low`) rounds up to
+* the next tier it's still `<=`, i.e. `medium` here, not down to `low`.
+*/
+function budgetTokensToEffort(budgetTokens, table = DEFAULT_EFFORT_TOKENS) {
+	if (budgetTokens <= table.minimal) return "minimal";
+	if (budgetTokens <= table.low) return "low";
+	if (budgetTokens <= table.medium) return "medium";
+	return "high";
+}
+/**
+* Parses an Opus model id's generation and minor version, e.g.
+* `"claude-opus-4-7-20260101"` -> `[4, 7]`, `"anthropic.claude-opus-5-x"` ->
+* `[5, 0]`. Not anchored, so it matches equally inside a bare Anthropic id
+* or a Bedrock id carrying a provider prefix. Returns `null` for a
+* non-Opus model id.
+*/
+/**
+* Parses an Opus model id's generation and minor version, e.g.
+* `"claude-opus-4-7-20260101"` -> `[4, 7]`, `"anthropic.claude-opus-5-x"` ->
+* `[5, 0]`. Not anchored, so it matches equally inside a bare Anthropic id
+* or a Bedrock id carrying a provider prefix. Returns `null` for a
+* non-Opus model id.
+*
+* Anthropic model ids sometimes carry a trailing snapshot date instead of
+* (or in addition to) an explicit minor version, e.g. the real, still-
+* supported base `"claude-opus-4-20250514"` (no `.7`-style minor at all,
+* just a date suffix directly after the major version). Read naively,
+* `20250514` looks like a minor version far above any real threshold and
+* would misclassify this pre-4.6 model as adaptive-only. Snapshot dates
+* are always 8 digits (`YYYYMMDD`); a real minor version never is, so an
+* 8+ digit second segment is treated as a date, not a minor version.
+*/
+function parseOpusVersion(model) {
+	const match = /opus-(\d+)(?:-(\d+))?/.exec(model);
+	if (!match) return null;
+	const minorStr = match[2];
+	const minor = minorStr === void 0 || minorStr.length >= 8 ? 0 : Number(minorStr);
+	return [Number(match[1]), minor];
+}
+/**
+* Default rule for whether `model` only supports adaptive thinking
+* (`thinking: { type: 'adaptive' }`) and returns a 400 for manual,
+* budget-based thinking (`thinking: { type: 'enabled', budget_tokens }`):
+* Claude Opus 4.7 and later (matched as a version threshold, so 4.8, 4.9,
+* 5, and every future Opus point release are covered automatically,
+* without a new list entry per release), and every Claude 5 tier model
+* outside the Opus family (Sonnet 5, Fable 5, Mythos 5, Mythos Preview).
+* `mythos` alone is enough to catch both Mythos names without listing
+* each separately.
+*
+* Necessarily best-effort: a new model family with its own name (not
+* `opus-*`, not `sonnet-5`/`fable-5`/`mythos-*`) still needs a code
+* update here, or a caller-supplied `adaptiveOnlyModels` override (see
+* `isAdaptiveOnlyModel`) covering it in the meantime.
+*/
+function isDefaultAdaptiveOnly(model) {
+	const opusVersion = parseOpusVersion(model);
+	if (opusVersion) {
+		const [major, minor] = opusVersion;
+		return major > 4 || major === 4 && minor >= 7;
+	}
+	return [
+		"sonnet-5",
+		"fable-5",
+		"mythos"
+	].some((s) => model.includes(s));
+}
+/**
+* Whether `model` is adaptive-only, per the built-in rule above, or per a
+* caller-supplied `adaptiveOnlyModels` override. The override is
+* additive, not a replacement: it can mark an *additional* model as
+* adaptive-only (useful for a model family this package doesn't know
+* about yet), but it can't un-mark one the built-in rule already caught,
+* since a caller correcting a false negative is the only direction that
+* needs covering, a false positive here would mean this package is
+* simply wrong and needs its own fix, not a per-caller workaround.
+*/
+function isAdaptiveOnlyModel(model, override) {
+	if (isDefaultAdaptiveOnly(model)) return true;
+	if (!override) return false;
+	return Array.isArray(override) ? override.includes(model) : override(model);
+}
+/** Whether `model` is known to support manual, budget-based thinking. */
+function supportsManualThinkingBudget(model, override) {
+	return !isAdaptiveOnlyModel(model, override);
+}
+/**
+* Anthropic (and Claude models on Bedrock) require `budget_tokens` to be
+* at least 1024 and strictly less than `max_tokens`, since the thinking
+* budget and the reply share the same `max_tokens` ceiling. VernLLM's own
+* default `maxTokens` is 1000 (see `RequestBuilder`'s `defaultMaxTokens`),
+* below the 1024 floor, so the *default* `minimal` tier (1024 tokens) is
+* silently invalid against the *default* `max_tokens` unless a caller
+* happens to raise one or the other. Checked here, once, right before a
+* `thinking` block would be built, rather than left for Anthropic's own
+* 400 to explain after a real network round trip.
+*/
+function assertValidClaudeBudgetTokens(budgetTokens, maxTokens) {
+	if (budgetTokens < 1024) throw new LLMError(`budgetTokens (${budgetTokens}) is below Anthropic's minimum of 1024. Raise budgetTokens, or use a reasoningEffort tier of 'low' or above with the default conversion table.`, "invalid_params");
+	if (budgetTokens >= maxTokens) throw new LLMError(`budgetTokens (${budgetTokens}) must be less than maxTokens (${maxTokens}); the thinking budget and the reply share the same max_tokens ceiling on Anthropic. Raise maxTokens, or lower budgetTokens/reasoningEffort.`, "invalid_params");
+}
+/**
+* Anthropic rejects any form of `thinking` (manual `budget_tokens` or
+* adaptive) combined with a `tool_choice` that forces tool use, a forced
+* single tool or "must call some tool", with a 400: `"Thinking may not be
+* enabled when tool_choice forces tool use."` Auto/none (or no tools at
+* all) are unaffected, thinking only conflicts with a choice that removes
+* the model's ability to just reply with text. This is a Claude-model
+* constraint, not specific to the Anthropic API's own wire shape, so it
+* applies identically to Claude models called through Bedrock's Converse
+* API, which forwards `thinking` under `additionalModelRequestFields` but
+* is still talking to the same underlying model.
+*
+* This combination can arise two ways: a caller explicitly sets both
+* `budgetTokens`/`reasoningEffort` and a forced `toolChoice`, or, more
+* subtly (Anthropic adapter only), a caller sets `jsonSchema` on a model
+* without native structured output support, which silently forces a
+* single synthetic tool call to emulate it, with no `tool_choice` of the
+* caller's own in sight. Both end up resolving to a forced tool choice by
+* the time each adapter calls this, so checking the adapter's own
+* already-resolved choice (rather than the caller's raw
+* `params.tool_choice`) catches both, right before a `thinking` block
+* would be built, rather than left for Anthropic's own 400 to explain
+* after a real network round trip.
+*
+* Takes a plain description of the forced choice rather than either
+* adapter's own wire shape (Anthropic SDK's `{ type: 'tool' | 'any', ... }`
+* vs Converse's `{ tool: {...} } | { any: {} }`), so both adapters can
+* share one check without either shape leaking into this file. Pass
+* `undefined` when the resolved choice is `auto`/`none`/unset, forcing
+* nothing.
+*/
+function assertNoForcedToolChoiceWithThinking(forcedChoiceDescription) {
+	if (!forcedChoiceDescription) return;
+	throw new LLMError(`budgetTokens/reasoningEffort was set alongside ${forcedChoiceDescription}. Anthropic rejects thinking combined with a tool_choice that forces tool use, the model has to be able to reply with plain text for thinking to run. Use toolChoice: 'auto' (or omit toolChoice) for this call, or drop budgetTokens/reasoningEffort for it.`, "invalid_params");
+}
+/**
+* Maps VernLLM's four-tier `reasoningEffort` onto Anthropic's five-tier
+* adaptive effort. `xhigh` and `max` have no VernLLM-side equivalent and
+* are unreachable through this mapping; a caller who wants either has to
+* target Anthropic/Bedrock-specific behavior already, so there's no gap
+* the shared `CallParams` surface needs to cover for a first pass.
+*/
+function toClaudeAdaptiveEffort(effort) {
+	return effort === "minimal" ? "low" : effort;
+}
+/** Converts VernLLM's `reasoningEffort` directly into Gemini's `ThinkingLevel` enum value. */
+function toGeminiThinkingLevel(effort, model) {
+	return clampGeminiThinkingLevel(model, effort.toUpperCase());
+}
+/**
+* Parses a Gemini model id's minor version, e.g. `"gemini-3.1-pro"` -> `1`,
+* `"gemini-3-pro"` -> `0` (no explicit minor). Only meaningful alongside
+* `parseGeminiMajorVersion`.
+*/
+function parseGeminiMinorVersion(model) {
+	const match = /gemini-\d+\.(\d+)/.exec(model);
+	return match ? Number(match[1]) : 0;
+}
+/**
+* Some Gemini 3 "Pro" tier models accept a narrower set of `thinkingLevel`
+* values than VernLLM's four tiers map onto, confirmed against real API
+* 400s and Google's own migration guidance, not assumed:
+* - Gemini 3 Pro (major 3, minor 0, e.g. `"gemini-3-pro-preview"`): only
+*   `LOW` and `HIGH`; `MEDIUM` returns a 400 ("Thinking level MEDIUM is
+*   not supported for this model").
+* - Gemini 3.1 Pro (major 3, minor >= 1): `LOW`/`MEDIUM`/`HIGH`, no
+*   `MINIMAL`, Google's own docs point users toward a Flash-tier model
+*   instead for the lowest setting.
+* - Every Flash-tier Gemini 3+ model accepts the full four levels, no
+*   clamping needed, matched by this function simply not applying to
+*   anything without `"pro"` in the model id.
+*
+* Clamped automatically rather than left to error, since `reasoningEffort`
+* is a per-call value, a caller hitting this isn't misconfiguring an
+* instance once, they're getting an intermittent-looking failure on
+* whichever specific call happened to pick an unsupported tier. Necessarily
+* best-effort: a future Pro-tier release could add back a level this rule
+* still clamps, or clamp one this rule doesn't yet know to touch.
+*/
+function clampGeminiThinkingLevel(model, level) {
+	if (!model.includes("pro")) return level;
+	const major = parseGeminiMajorVersion(model);
+	if (major === null || major < 3) return level;
+	const minor = parseGeminiMinorVersion(model);
+	if (minor === 0) return level === "HIGH" ? "HIGH" : "LOW";
+	return level === "MINIMAL" ? "LOW" : level;
+}
+/**
+* Parses a Gemini model id's major generation number, e.g.
+* `"gemini-3.1-flash-lite"` -> `3`, `"gemini-2.5-flash"` -> `2`. Not
+* anchored, so a Vertex-prefixed or otherwise decorated id still matches.
+* Returns `null` for a non-Gemini model id.
+*/
+function parseGeminiMajorVersion(model) {
+	const match = /gemini-(\d+)/.exec(model);
+	return match ? Number(match[1]) : null;
+}
+/**
+* Default rule for whether `model` uses `thinkingLevel` instead of
+* `thinkingBudget`: every Gemini 3 series model and later, matched as a
+* version threshold so 3.1, 3.5, 3.6, and every future Gemini 3.x or
+* later release are covered automatically, without a new entry per
+* release, same reasoning as `isDefaultAdaptiveOnly`'s Opus threshold.
+* Gemini 2.5 and earlier still use `thinkingBudget`.
+*
+* `thinkingBudget` is still *accepted* on Gemini 3 for backward
+* compatibility, per Google's own docs, but "may result in unexpected
+* performance" there, so this rule switches VernLLM's own default
+* behavior over rather than leaving it on the old field indefinitely.
+*/
+function isDefaultThinkingLevelModel(model) {
+	const major = parseGeminiMajorVersion(model);
+	return major !== null && major >= 3;
+}
+/**
+* Whether `model` uses `thinkingLevel`, per the built-in version
+* threshold above, or per a caller-supplied `thinkingLevelModels`
+* override. Additive, not a replacement, same reasoning as
+* `isAdaptiveOnlyModel`: an override can mark an *additional* model as
+* using `thinkingLevel` (a model family this package doesn't recognize
+* yet), it can't un-mark one the built-in threshold already caught.
+*/
+function usesGeminiThinkingLevel(model, override) {
+	if (isDefaultThinkingLevelModel(model)) return true;
+	if (!override) return false;
+	return Array.isArray(override) ? override.includes(model) : override(model);
+}
+
 //#endregion
 //#region src/adapters/anthropic.ts
 /**
@@ -2564,7 +3454,7 @@ function buildAnthropicTools(tools, toolChoiceParam) {
 * `params.tools` are left for the normal, non-forced tool-call handling
 * both `create` and `createStream` already do when `toolName` is unset.
 */
-function buildAnthropicRequestBody(params, nativeStructuredOutputModels) {
+function buildAnthropicRequestBody(params, nativeStructuredOutputModels, effortTokenTable, adaptiveOnlyModels) {
 	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;
@@ -2572,8 +3462,8 @@ function buildAnthropicRequestBody(params, nativeStructuredOutputModels) {
 	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");
+	if (params.response_format?.type === "json_object") throw new LLMError("response_format: \"json_object\" is not supported on Anthropic. Unlike OpenAI, Anthropic has no API-level field that mechanically guarantees valid JSON output for this mode, so it used to be emulated by injecting a \"respond with JSON only\" instruction into the system prompt, a guarantee this adapter can no longer make. Use `jsonSchema` instead, which maps to a real API-level constraint (Anthropic's native output_config.format on covered models, or a forced single tool call otherwise).", "validation");
 	let toolName;
-	let jsonInstruction;
 	let outputFormat;
 	let tools;
 	let toolChoice;
@@ -2596,20 +3486,42 @@ function buildAnthropicRequestBody(params, nativeStructuredOutputModels) {
 			type: "tool",
 			name: toolName
 		};
-	} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
+	}
 	if (!jsonSchema && params.tools?.length) ({tools, toolChoice} = buildAnthropicTools(params.tools, params.tool_choice));
-	const system = [systemMessage?.content, jsonInstruction].filter(Boolean).join("\n\n");
+	let thinking;
+	let effort;
+	if (params.budget_tokens !== void 0 || params.reasoning_effort !== void 0) {
+		assertNoForcedToolChoiceWithThinking(toolChoice?.type === "tool" ? `toolChoice forcing the "${toolChoice.name}" tool` : toolChoice?.type === "any" ? "toolChoice: 'required' (Anthropic's \"any\" tool_choice)" : void 0);
+		if (supportsManualThinkingBudget(params.model, adaptiveOnlyModels)) {
+			const budgetTokens = params.budget_tokens ?? effortToBudgetTokens(params.reasoning_effort, effortTokenTable);
+			assertValidClaudeBudgetTokens(budgetTokens, params.max_tokens);
+			thinking = {
+				type: "enabled",
+				budget_tokens: budgetTokens
+			};
+		} else {
+			const effortTier = params.reasoning_effort ?? budgetTokensToEffort(params.budget_tokens, effortTokenTable);
+			thinking = { type: "adaptive" };
+			effort = toClaudeAdaptiveEffort(effortTier);
+		}
+	}
+	const system = systemMessage?.content;
+	const temperature = thinking ? void 0 : params.temperature;
 	const body = {
 		model: params.model,
 		max_tokens: params.max_tokens,
-		...params.temperature !== void 0 ? { temperature: params.temperature } : {},
+		...temperature !== void 0 ? { temperature } : {},
 		system: system || void 0,
 		messages: mergeConsecutiveToolResults$1(conversationMessages.map((m) => toAnthropicMessage(m))),
 		...tools ? {
 			tools,
 			tool_choice: toolChoice
 		} : {},
-		...outputFormat ? { output_config: { format: outputFormat } } : {}
+		...outputFormat || effort ? { output_config: {
+			...outputFormat ? { format: outputFormat } : {},
+			...effort ? { effort } : {}
+		} } : {},
+		...thinking ? { thinking } : {}
 	};
 	return {
 		body,
@@ -2638,103 +3550,113 @@ function buildAnthropicRequestBody(params, nativeStructuredOutputModels) {
 * 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. 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.
+* `response_format: json_object` throws `LLMError('validation')`. Anthropic
+* has no API-level field that mechanically guarantees JSON output the way
+* OpenAI's `json_object` mode does; the only way to emulate it was a
+* system-prompt instruction with no actual enforcement behind it, a
+* guarantee this adapter no longer pretends to make. Use `jsonSchema`
+* instead, which maps to a real constraint either way (native
+* `output_config.format` or a forced tool call).
 */
 function fromAnthropic(anthropicClient, options) {
 	const nativeStructuredOutputModels = options?.nativeStructuredOutputModels;
+	const effortTokenTable = resolveEffortTokenTable(options?.reasoningEffortTokens);
+	const adaptiveOnlyModels = options?.adaptiveOnlyModels;
 	const rawMessagesCreate = anthropicClient.messages.create.bind(anthropicClient.messages);
-	return { chat: { completions: {
-		async create(params, options$1) {
-			const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels);
-			const response = await anthropicClient.messages.create(body, options$1);
-			let text;
-			let wireToolCalls;
-			if (toolName) {
-				const toolUse = response.content.find((block) => block.type === "tool_use" && block.name === toolName);
-				if (!toolUse) throw new LLMError(`Anthropic did not return the required structured output tool "${toolName}".`, "validation");
-				if (!toolUse.input || typeof toolUse.input !== "object" || Array.isArray(toolUse.input)) throw new LLMError(`Anthropic returned invalid structured output for tool "${toolName}". Expected an object.`, "validation");
-				text = JSON.stringify(toolUse.input);
-			} else {
-				text = response.content.filter((block) => block.type === "text").map((block) => block.text ?? "").join("");
-				const toolUses = response.content.filter((block) => block.type === "tool_use");
-				if (toolUses.length) wireToolCalls = toolUses.map((block) => ({
-					id: block.id,
-					type: "function",
-					function: {
-						name: block.name,
-						arguments: JSON.stringify(block.input ?? {})
-					}
-				}));
-			}
-			return {
-				choices: [{ message: {
-					content: text,
-					...wireToolCalls ? { tool_calls: wireToolCalls } : {}
-				} }],
-				usage: {
-					prompt_tokens: response.usage?.input_tokens,
-					completion_tokens: response.usage?.output_tokens,
-					total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0)
+	return {
+		supportsJsonObjectMode: false,
+		chat: { completions: {
+			async create(params, options$1) {
+				const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels, effortTokenTable, adaptiveOnlyModels);
+				const response = await anthropicClient.messages.create(body, options$1);
+				let text;
+				let wireToolCalls;
+				if (toolName) {
+					const toolUse = response.content.find((block) => block.type === "tool_use" && block.name === toolName);
+					if (!toolUse) throw new LLMError(`Anthropic did not return the required structured output tool "${toolName}".`, "validation");
+					if (!toolUse.input || typeof toolUse.input !== "object" || Array.isArray(toolUse.input)) throw new LLMError(`Anthropic returned invalid structured output for tool "${toolName}". Expected an object.`, "validation");
+					text = JSON.stringify(toolUse.input);
+				} else {
+					text = response.content.filter((block) => block.type === "text").map((block) => block.text ?? "").join("");
+					const toolUses = response.content.filter((block) => block.type === "tool_use");
+					if (toolUses.length) wireToolCalls = toolUses.map((block) => ({
+						id: block.id,
+						type: "function",
+						function: {
+							name: block.name,
+							arguments: JSON.stringify(block.input ?? {})
+						}
+					}));
 				}
-			};
-		},
-		async *createStream(params, options$1) {
-			const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels);
-			const stream = await rawMessagesCreate({
-				...body,
-				stream: true
-			}, options$1);
-			const blockKinds = new Map();
-			let inputTokens = 0;
-			let sawJsonTool = false;
-			for await (const event of stream) if (event.type === "message_start") inputTokens = event.message.usage?.input_tokens ?? 0;
-			else if (event.type === "content_block_start") if (event.content_block.type === "tool_use") {
-				const kind = event.content_block.name === toolName ? "json-tool" : "tool_use";
-				blockKinds.set(event.index, kind);
-				if (kind === "json-tool") sawJsonTool = true;
-				else if (!toolName) yield {
-					type: "tool_call_delta",
-					index: event.index,
-					id: event.content_block.id,
-					name: event.content_block.name
+				return {
+					choices: [{ message: {
+						content: text,
+						...wireToolCalls ? { tool_calls: wireToolCalls } : {}
+					} }],
+					usage: {
+						prompt_tokens: response.usage?.input_tokens,
+						completion_tokens: response.usage?.output_tokens,
+						total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0),
+						...response.usage?.output_tokens_details?.thinking_tokens !== void 0 ? { completion_tokens_details: { reasoning_tokens: response.usage.output_tokens_details.thinking_tokens } } : {}
+					}
 				};
-			} else blockKinds.set(event.index, "text");
-			else if (event.type === "content_block_delta") {
-				if (event.delta.type === "text_delta") {
-					if (!toolName) yield {
-						type: "text-delta",
-						delta: event.delta.text
-					};
-				} else if (event.delta.type === "input_json_delta") {
-					const kind = blockKinds.get(event.index);
-					if (kind === "json-tool") yield {
-						type: "text-delta",
-						delta: event.delta.partial_json
-					};
+			},
+			async *createStream(params, options$1) {
+				const { body, toolName } = buildAnthropicRequestBody(params, nativeStructuredOutputModels, effortTokenTable, adaptiveOnlyModels);
+				const stream = await rawMessagesCreate({
+					...body,
+					stream: true
+				}, options$1);
+				const blockKinds = new Map();
+				let inputTokens = 0;
+				let sawJsonTool = false;
+				for await (const event of stream) if (event.type === "message_start") inputTokens = event.message.usage?.input_tokens ?? 0;
+				else if (event.type === "content_block_start") if (event.content_block.type === "tool_use") {
+					const kind = event.content_block.name === toolName ? "json-tool" : "tool_use";
+					blockKinds.set(event.index, kind);
+					if (kind === "json-tool") sawJsonTool = true;
 					else if (!toolName) yield {
 						type: "tool_call_delta",
 						index: event.index,
-						argumentsDelta: event.delta.partial_json
+						id: event.content_block.id,
+						name: event.content_block.name
 					};
-				}
-			} else if (event.type === "message_delta") {
-				const outputTokens = event.usage?.output_tokens ?? 0;
-				yield {
-					type: "usage",
-					usage: {
-						prompt_tokens: inputTokens,
-						completion_tokens: outputTokens,
-						total_tokens: inputTokens + outputTokens
+				} else blockKinds.set(event.index, "text");
+				else if (event.type === "content_block_delta") {
+					if (event.delta.type === "text_delta") {
+						if (!toolName) yield {
+							type: "text-delta",
+							delta: event.delta.text
+						};
+					} else if (event.delta.type === "input_json_delta") {
+						const kind = blockKinds.get(event.index);
+						if (kind === "json-tool") yield {
+							type: "text-delta",
+							delta: event.delta.partial_json
+						};
+						else if (!toolName) yield {
+							type: "tool_call_delta",
+							index: event.index,
+							argumentsDelta: event.delta.partial_json
+						};
 					}
-				};
-			} else if (event.type === "ping") yield { type: "ping" };
-			if (toolName && !sawJsonTool) throw new LLMError(`Anthropic did not return the required structured output tool "${toolName}".`, "validation");
-		}
-	} } };
+				} else if (event.type === "message_delta") {
+					const outputTokens = event.usage?.output_tokens ?? 0;
+					const thinkingTokens = event.usage?.output_tokens_details?.thinking_tokens;
+					yield {
+						type: "usage",
+						usage: {
+							prompt_tokens: inputTokens,
+							completion_tokens: outputTokens,
+							total_tokens: inputTokens + outputTokens,
+							...thinkingTokens !== void 0 ? { completion_tokens_details: { reasoning_tokens: thinkingTokens } } : {}
+						}
+					};
+				} else if (event.type === "ping") yield { type: "ping" };
+				if (toolName && !sawJsonTool) throw new LLMError(`Anthropic did not return the required structured output tool "${toolName}".`, "validation");
+			}
+		} }
+	};
 }
 /**
 * Anthropic requires strict role alternation, so the per-wire-message
@@ -2782,7 +3704,7 @@ function toAnthropicMessage(m) {
 			try {
 				input = tc.function.arguments.trim() ? JSON.parse(tc.function.arguments) : {};
 			} catch (cause) {
-				throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) has arguments that are not valid JSON.`, "validation", void 0, void 0, cause);
+				throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) has arguments that are not valid JSON.`, "validation", { cause });
 			}
 			if (input === null || Array.isArray(input) || typeof input !== "object") throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) arguments must be a JSON object.`, "validation");
 			blocks.push({
@@ -2863,17 +3785,31 @@ function parseToolArguments(text, toolName) {
 	try {
 		parsed = text.trim() ? JSON.parse(text) : {};
 	} catch (cause) {
-		throw new LLMError(`Tool call "${toolName}" arguments are not valid JSON.`, "validation", void 0, void 0, cause);
+		throw new LLMError(`Tool call "${toolName}" arguments are not valid JSON.`, "parse", {
+			cause,
+			code: "tool_arguments_parse_failed"
+		});
 	}
 	if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") throw new LLMError(`Tool call "${toolName}" arguments must be a JSON object.`, "validation");
 	return parsed;
 }
+/**
+* Parses a wire tool message's `content` into the object Gemini's
+* `functionResponse.response` expects. Gemini (and the real SDK's
+* `FunctionResponse.response` type) requires an object, so a result that
+* parses to something other than a plain JSON object (a string, number,
+* array, or unparseable text) is wrapped under an `output` key, mirroring
+* Gemini's own documented convention for non-object function results.
+*/
 function parseToolResult(text) {
+	let parsed;
 	try {
-		return text.trim() ? JSON.parse(text) : "";
+		parsed = text.trim() ? JSON.parse(text) : "";
 	} catch {
-		return text;
+		parsed = text;
 	}
+	if (parsed && !Array.isArray(parsed) && typeof parsed === "object") return parsed;
+	return { output: parsed };
 }
 /**
 * Gemini expects the results of everything the model asked for in one turn
@@ -2902,7 +3838,7 @@ function mergeConsecutiveFunctionResponses(contents) {
 * `abortSignal` is folded into `config` by the caller (`create`/
 * `createStream`), once the request options are available.
 */
-function buildGeminiRequest(params) {
+function buildGeminiRequest(params, effortTokenTable, thinkingLevelModels) {
 	const systemMessage = params.messages.find((m) => m.role === "system");
 	const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "tool");
 	const wantsJson = Boolean(params.response_format);
@@ -2927,51 +3863,37 @@ function buildGeminiRequest(params) {
 		})) }];
 		config.toolConfig = toGeminiToolConfig(params.tool_choice);
 	}
+	if (usesGeminiThinkingLevel(params.model, thinkingLevelModels)) {
+		const effortTier = params.reasoning_effort ?? (params.budget_tokens !== void 0 ? budgetTokensToEffort(params.budget_tokens, effortTokenTable) : void 0);
+		if (effortTier !== void 0) config.thinkingConfig = { thinkingLevel: toGeminiThinkingLevel(effortTier, params.model) };
+	} else {
+		const thinkingBudget = params.budget_tokens ?? (params.reasoning_effort ? effortToBudgetTokens(params.reasoning_effort, effortTokenTable) : void 0);
+		if (thinkingBudget !== void 0) config.thinkingConfig = { thinkingBudget };
+	}
 	return {
 		model: params.model,
 		contents: mergeConsecutiveFunctionResponses(conversationMessages.map((m) => toGeminiContent(m))),
 		config
 	};
 }
-/**
-* Wraps a Gemini client so it satisfies the `LLMClient` interface VernLLM
-* uses for OpenAI-compatible APIs. Gemini's shape differs on nearly every
-* 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.
-*
-* `tools` maps to Gemini's native `functionDeclarations`/`functionCall`;
-* `tool_choice` maps to `toolConfig.functionCallingConfig`. Gemini accepts
-* `responseSchema` and `tools` in the same request natively, so both are
-* set independently here and no special-casing is needed for the
-* combination, unlike `fromAnthropic`/`fromBedrock`.
-*
-* `createStream` calls `generateContentStream` (optional on `GeminiClient`
-*, required only if the caller sets `stream: true`) and translates each
-* partial response into `WireStreamChunk`s. Unlike OpenAI/Anthropic,
-* Gemini's own function-calling API doesn't stream tool-call arguments
-* incrementally: a `functionCall` part always arrives whole in one chunk,
-* so each one is emitted as a single, complete `tool_call_delta` (a
-* one-shot "delta" containing the full arguments) rather than accumulated
-* fragments, that's a real difference in the underlying API, not
-* something this adapter can smooth over. `usageMetadata` is (per Gemini's
-* own behavior) only reliably present on the last chunk, so the `usage`
-* `WireStreamChunk` is emitted once, after the stream completes, from
-* whichever chunk's `usageMetadata` was seen last.
-*/
-function fromGemini(geminiClient) {
+function fromGemini(client, options) {
+	const effortTokenTable = resolveEffortTokenTable(options?.reasoningEffortTokens);
+	const thinkingLevelModels = options?.thinkingLevelModels;
+	const resolved = client.models ?? client;
+	if (typeof resolved.generateContent !== "function") throw new LLMError("fromGemini requires a client with generateContent: pass ai.models, or the whole ai client (fromGemini(ai)).", "invalid_params", {
+		code: "unsupported_capability",
+		issues: { capability: "generateContent" }
+	});
+	const generateContent = resolved.generateContent.bind(resolved);
+	const generateContentStream = typeof resolved.generateContentStream === "function" ? resolved.generateContentStream.bind(resolved) : void 0;
 	return { chat: { completions: {
-		async create(params, options) {
-			const request = buildGeminiRequest(params);
+		async create(params, options$1) {
+			const request = buildGeminiRequest(params, effortTokenTable, thinkingLevelModels);
 			request.config = {
 				...request.config,
-				abortSignal: options.signal
+				abortSignal: options$1.signal
 			};
-			const response = await geminiClient.generateContent(request);
+			const response = await generateContent(request);
 			const parts = response.candidates?.[0]?.content?.parts ?? [];
 			const text = parts.map((p) => p.text ?? "").join("");
 			const functionCalls = parts.filter((p) => p.functionCall);
@@ -2992,18 +3914,22 @@ function fromGemini(geminiClient) {
 				usage: {
 					prompt_tokens: response.usageMetadata?.promptTokenCount,
 					completion_tokens: response.usageMetadata?.candidatesTokenCount,
-					total_tokens: response.usageMetadata?.totalTokenCount
+					total_tokens: response.usageMetadata?.totalTokenCount,
+					...response.usageMetadata?.thoughtsTokenCount !== void 0 ? { completion_tokens_details: { reasoning_tokens: response.usageMetadata.thoughtsTokenCount } } : {}
 				}
 			};
 		},
-		async *createStream(params, options) {
-			if (!geminiClient.generateContentStream) throw new LLMError("stream: true requires a Gemini client with generateContentStream", "validation");
-			const request = buildGeminiRequest(params);
+		async *createStream(params, options$1) {
+			if (!generateContentStream) throw new LLMError("stream: true requires a Gemini client with generateContentStream", "invalid_params", {
+				code: "unsupported_capability",
+				issues: { capability: "generateContentStream" }
+			});
+			const request = buildGeminiRequest(params, effortTokenTable, thinkingLevelModels);
 			request.config = {
 				...request.config,
-				abortSignal: options.signal
+				abortSignal: options$1.signal
 			};
-			const stream = await geminiClient.generateContentStream(request);
+			const stream = await generateContentStream(request);
 			let toolCallIndex = 0;
 			let lastUsage;
 			for await (const chunk of stream) {
@@ -3032,7 +3958,8 @@ function fromGemini(geminiClient) {
 				usage: {
 					prompt_tokens: lastUsage.promptTokenCount,
 					completion_tokens: lastUsage.candidatesTokenCount,
-					total_tokens: lastUsage.totalTokenCount
+					total_tokens: lastUsage.totalTokenCount,
+					...lastUsage.thoughtsTokenCount !== void 0 ? { completion_tokens_details: { reasoning_tokens: lastUsage.thoughtsTokenCount } } : {}
 				}
 			};
 		}
@@ -3041,6 +3968,19 @@ function fromGemini(geminiClient) {
 
 //#endregion
 //#region src/adapters/bedrock.ts
+/**
+* Default heuristic for whether a Bedrock model id is a Claude model,
+* matching AWS's own `anthropic.claude-*`/`us.anthropic.claude-*` naming.
+* Only used to decide whether a reasoning token budget is worth forwarding
+* through `additionalModelRequestFields`, not a general capability check,
+* so a plain substring match is enough, no override hook needed the way
+* `nativeStructuredOutputModels`/`toolUseSupportedModels` have one: a
+* false positive here just sends an inert extra field, not a request that
+* fails outright.
+*/
+function isClaudeModel(model) {
+	return model.includes("claude");
+}
 /** Maps a `ContentBlock` image MIME type, already validated, to Converse's `format` enum. */
 function toBedrockImageFormat(mimeType) {
 	switch (assertSupportedImageMimeType(mimeType)) {
@@ -3107,7 +4047,7 @@ function buildBedrockToolConfig(tools, toolChoiceParam) {
 * normal, non-forced tool-call handling both `create` and `createStream`
 * already do when `toolName` is unset.
 */
-function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels) {
+function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels, effortTokenTable, adaptiveOnlyModels) {
 	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;
@@ -3115,8 +4055,8 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 	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");
+	if (params.response_format?.type === "json_object") throw new LLMError("response_format: \"json_object\" is not supported on Bedrock. Converse has no field that mechanically guarantees valid JSON output for this mode, so it used to be emulated by injecting a \"respond with JSON only\" instruction into the system prompt, a guarantee this adapter can no longer make. Use `jsonSchema` instead, which maps to a real constraint (Converse's native outputConfig.textFormat on covered models, or a forced tool call otherwise).", "validation");
 	let toolName;
-	let jsonInstruction;
 	let toolConfig;
 	let outputConfig;
 	if (jsonSchema && isNative) {
@@ -3141,23 +4081,48 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 			} }],
 			toolChoice: { tool: { name: toolName } }
 		};
-	} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
+	}
 	if (params.tools?.length && !toolName) toolConfig = buildBedrockToolConfig(params.tools, params.tool_choice);
 	if (jsonSchema && toolConfig && toolUseSupportedModels) {
 		const isSupported = Array.isArray(toolUseSupportedModels) ? toolUseSupportedModels.includes(params.model) : toolUseSupportedModels(params.model);
-		if (!isSupported) throw new LLMError(`Bedrock model "${params.model}" is not listed in toolUseSupportedModels, but this call requires Converse tool use (either jsonSchema emulated as a forced tool call, or real \`tools\` sent alongside native structured output).`, "validation");
+		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).`, "invalid_params", {
+			code: "unsupported_capability",
+			issues: { capability: "toolUseSupportedModels" }
+		});
+	}
+	let additionalModelRequestFields;
+	let effort;
+	if (isClaudeModel(params.model) && (params.budget_tokens !== void 0 || params.reasoning_effort !== void 0)) {
+		const forcedToolChoice = toolConfig?.toolChoice;
+		assertNoForcedToolChoiceWithThinking(forcedToolChoice && "tool" in forcedToolChoice ? `toolChoice forcing the "${forcedToolChoice.tool?.name}" tool` : forcedToolChoice && "any" in forcedToolChoice ? "toolChoice: 'required' (Converse's \"any\" tool_choice)" : void 0);
+		if (supportsManualThinkingBudget(params.model, adaptiveOnlyModels)) {
+			const budgetTokens = params.budget_tokens ?? effortToBudgetTokens(params.reasoning_effort, effortTokenTable);
+			assertValidClaudeBudgetTokens(budgetTokens, params.max_tokens);
+			additionalModelRequestFields = { thinking: {
+				type: "enabled",
+				budget_tokens: budgetTokens
+			} };
+		} else {
+			const effortTier = params.reasoning_effort ?? budgetTokensToEffort(params.budget_tokens, effortTokenTable);
+			additionalModelRequestFields = { thinking: { type: "adaptive" } };
+			effort = toClaudeAdaptiveEffort(effortTier);
+		}
 	}
-	const systemParts = [systemMessage?.content, jsonInstruction].filter((s) => Boolean(s));
+	const temperature = additionalModelRequestFields ? void 0 : params.temperature;
 	const request = {
 		modelId: params.model,
 		messages: mergeConsecutiveToolResults(conversationMessages.map((m) => toBedrockMessage(m))),
-		system: systemParts.length ? systemParts.map((text) => ({ text })) : void 0,
+		system: systemMessage?.content ? [{ text: systemMessage.content }] : void 0,
 		inferenceConfig: {
-			...params.temperature !== void 0 ? { temperature: params.temperature } : {},
+			...temperature !== void 0 ? { temperature } : {},
 			maxTokens: params.max_tokens
 		},
 		...toolConfig ? { toolConfig } : {},
-		...outputConfig ? { outputConfig } : {}
+		...outputConfig || effort ? { outputConfig: {
+			...outputConfig ?? {},
+			...effort ? { effort } : {}
+		} } : {},
+		...additionalModelRequestFields ? { additionalModelRequestFields } : {}
 	};
 	return {
 		request,
@@ -3165,6 +4130,120 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 	};
 }
 /**
+* Distinguishes a real AWS SDK v3 client (`.send(command)`) from a
+* hand-written `BedrockConverseClient` (`.converse(params)`) purely
+* structurally, so `fromBedrock` can accept either without the caller
+* saying which one they're passing. The two shapes don't overlap: nothing
+* implementing `.converse()` would also need `.send()`.
+*/
+function isAwsSendClient(client) {
+	return typeof client.send === "function";
+}
+/**
+* Narrows one raw AWS stream event down to VernLLM's intentionally minimal
+* `BedrockConverseStreamEvent` union. Returns `undefined` if the event
+* isn't one of the kinds this adapter models.
+*
+* AWS's real `ConverseStreamOutput` type is a strictly larger union than
+* `BedrockConverseStreamEvent`. On top of every member modeled here, it
+* also includes a generated `$unknown` member, AWS's forward-compatibility
+* escape hatch for event kinds added to the service after this SDK version
+* was generated. A blind type assertion from one union to the other would
+* compile, but would let `$unknown` (or any other future member) reach
+* `fromBedrock`'s event-handling loop unnarrowed, as if it were one of the
+* kinds actually handled there.
+*
+* Returning `undefined` for anything unrecognized, filtered out by
+* `normalizeBedrockEventStream` below, keeps two guarantees. AWS SDK
+* generated types never leak into `fromBedrock`'s application code, only
+* this module's own `BedrockConverseStreamEvent` shape does. An event kind
+* this adapter doesn't yet know about is silently skipped, the same
+* forward-compatible behavior AWS's own `$unknown` convention implies,
+* rather than crashing the stream or being misrouted into a handler that
+* doesn't actually match its shape.
+*/
+function normalizeBedrockStreamEvent(raw) {
+	if ("messageStart" in raw) return { messageStart: raw.messageStart };
+	if ("contentBlockStart" in raw) return { contentBlockStart: raw.contentBlockStart };
+	if ("contentBlockDelta" in raw) return { contentBlockDelta: raw.contentBlockDelta };
+	if ("contentBlockStop" in raw) return { contentBlockStop: raw.contentBlockStop };
+	if ("messageStop" in raw) return { messageStop: raw.messageStop };
+	if ("metadata" in raw) return { metadata: raw.metadata };
+	if ("internalServerException" in raw) return { internalServerException: raw.internalServerException };
+	if ("modelStreamErrorException" in raw) return { modelStreamErrorException: raw.modelStreamErrorException };
+	if ("validationException" in raw) return { validationException: raw.validationException };
+	if ("throttlingException" in raw) return { throttlingException: raw.throttlingException };
+	if ("serviceUnavailableException" in raw) return { serviceUnavailableException: raw.serviceUnavailableException };
+	return void 0;
+}
+/**
+* Wraps a raw AWS event stream, narrowing each event through
+* `normalizeBedrockStreamEvent` and filtering out anything that doesn't
+* map onto `BedrockConverseStreamEvent`. `fromBedrock`'s event loop only
+* ever sees the shapes it actually models.
+*/
+async function* normalizeBedrockEventStream(rawStream) {
+	for await (const raw of rawStream) {
+		const event = normalizeBedrockStreamEvent(raw);
+		if (event) yield event;
+	}
+}
+/**
+* Adapts a real AWS SDK v3 client (anything with `.send()`, matching
+* `BedrockRuntimeClient`) into a `BedrockConverseClient`, so `fromBedrock`
+* can accept either without a hand-written `.converse()`/`.converseStream()`
+* wrapper. Internally does what that wrapper would: `client.send(new
+* ConverseCommand(params))`, `client.send(new
+* ConverseStreamCommand(params))`.
+*
+* `@aws-sdk/client-bedrock-runtime` is intentionally not a dependency (not
+* even a peer dependency) of this package. `vern-llm` otherwise has zero
+* runtime dependencies, and every other adapter works the same way:
+* structural typing over whatever client the caller already has. Instead,
+* `ConverseCommand`/`ConverseStreamCommand` are pulled in with a dynamic
+* `import()` the first time either method actually runs, and memoized
+* after that. Nothing is added to `package.json`, static or peer.
+* Bundlers only pull the AWS SDK in for code paths that actually pass a
+* raw AWS client to `fromBedrock`; a hand-written `BedrockConverseClient`
+* stays unaffected. If `@aws-sdk/client-bedrock-runtime` isn't installed,
+* the failure is a clear `LLMError` naming exactly what's missing, at the
+* moment it's needed, rather than a silent peer-dependency warning at
+* install time or a raw "Cannot find module" a caller has to trace back
+* themselves.
+*
+* Also closes two structural gaps between AWS's generated types and
+* `BedrockConverseClient`. AWS's `ConverseStreamCommandOutput.stream` is
+* optional, a response may not include it. This throws a clear `LLMError`
+* instead of letting `undefined` reach `fromBedrock`'s `for await` loop.
+* AWS's `ConverseStreamOutput` union is larger than
+* `BedrockConverseStreamEvent`, it includes a generated `$unknown` member.
+* Every event is narrowed through `normalizeBedrockStreamEvent` before it
+* reaches application code, instead of being asserted wholesale from one
+* type to the other.
+*/
+function wrapAwsSendClient(client) {
+	let commandsPromise;
+	function loadCommands() {
+		commandsPromise ??= import("@aws-sdk/client-bedrock-runtime").then((mod) => mod, (cause) => {
+			commandsPromise = void 0;
+			throw new LLMError("fromBedrock requires \"@aws-sdk/client-bedrock-runtime\" to be installed to use a raw AWS SDK client (it is not a dependency of vern-llm itself). Install it, or pass your own object with .converse()/.converseStream() methods instead.", "validation", { cause });
+		});
+		return commandsPromise;
+	}
+	return {
+		converse: async (params, requestOptions) => {
+			const { ConverseCommand } = await loadCommands();
+			return client.send(new ConverseCommand(params), { abortSignal: requestOptions.signal });
+		},
+		converseStream: async (params, requestOptions) => {
+			const { ConverseStreamCommand } = await loadCommands();
+			const result = await client.send(new ConverseStreamCommand(params), { abortSignal: requestOptions.signal });
+			if (!result.stream) throw new LLMError("Bedrock ConverseStreamCommand response did not include a stream. This can happen if the request or the model doesn't actually support Converse streaming.", "api", { code: "server_error" });
+			return { stream: normalizeBedrockEventStream(result.stream) };
+		}
+	};
+}
+/**
 * Wraps a Bedrock Converse-API client so it satisfies the `LLMClient`
 * interface VernLLM uses for OpenAI/Groq. The Converse API is unified
 * across Bedrock's model families (Anthropic, Titan, Llama, Mistral, etc.),
@@ -3172,6 +4251,16 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 * regardless of which underlying model `modelId` points at, as long as
 * that model supports Converse (most current-generation ones do)
 *
+* `bedrockClient` accepts either a hand-written `BedrockConverseClient`
+* (a `.converse()`/`.converseStream()` wrapper you provide) or a real AWS
+* SDK v3 client (anything with `.send()`, matching `BedrockRuntimeClient`)
+* directly, detected structurally. Passing a raw AWS client skips the
+* hand-written wrapper entirely, internally doing what it would
+* (`send(new ConverseCommand(...))`, `send(new
+* ConverseStreamCommand(...))`). See `wrapAwsSendClient` for how that path
+* is implemented, including why `@aws-sdk/client-bedrock-runtime` stays
+* out of this package's dependencies either way.
+*
 * `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
@@ -3193,12 +4282,15 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 * `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. 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.
+* `response_format: json_object` throws `LLMError('validation')`: Converse
+* has no field that mechanically guarantees JSON output, and the only way
+* to emulate it was an unenforced system-prompt instruction, a guarantee
+* this adapter no longer pretends to make. Use `jsonSchema` instead.
+* `reasoning_effort` (no Converse equivalent) is converted to a token
+* budget and forwarded via `additionalModelRequestFields` for Claude
+* models only; `budget_tokens` is forwarded the same way directly. Both
+* are silently dropped for non-Claude models, which have no equivalent
+* field to reach for. See `adapters/internal/reasoningBudget.utils.ts`.
 *
 * `tools` alone maps to Converse's native `toolConfig`/`toolUse`/
 * `toolResult`; `tool_choice` maps to `toolConfig.toolChoice`.
@@ -3216,104 +4308,122 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 * `create` branch above unwraps it.
 */
 function fromBedrock(bedrockClient, options) {
+	const client = isAwsSendClient(bedrockClient) ? wrapAwsSendClient(bedrockClient) : bedrockClient;
 	const toolUseSupportedModels = options?.toolUseSupportedModels;
 	const nativeStructuredOutputModels = options?.nativeStructuredOutputModels;
-	return { chat: { completions: {
-		async create(params, requestOptions) {
-			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels);
-			const response = await bedrockClient.converse(request, requestOptions);
-			let text;
-			let wireToolCalls;
-			if (toolName) {
-				const toolUseBlock = response.output?.message?.content?.find((block) => block.toolUse?.name === toolName);
-				text = toolUseBlock?.toolUse ? JSON.stringify(toolUseBlock.toolUse.input) : "";
-			} else {
-				const blocks = response.output?.message?.content ?? [];
-				text = blocks.map((c) => c.text ?? "").join("");
-				const toolUses = blocks.filter((block) => Boolean(block.toolUse));
-				if (toolUses.length) wireToolCalls = toolUses.map((block, i) => {
-					const toolUse = block.toolUse;
-					if (!toolUse.name) throw new LLMError(`Bedrock returned a toolUse block without a name at index ${i}.`, "validation");
-					return {
-						id: toolUse.toolUseId ?? `${toolUse.name}_${i}`,
-						type: "function",
-						function: {
-							name: toolUse.name,
-							arguments: JSON.stringify(toolUse.input ?? {})
-						}
-					};
-				});
-			}
-			return {
-				choices: [{ message: {
-					content: text,
-					...wireToolCalls ? { tool_calls: wireToolCalls } : {}
-				} }],
-				usage: {
-					prompt_tokens: response.usage?.inputTokens,
-					completion_tokens: response.usage?.outputTokens,
-					total_tokens: response.usage?.totalTokens
+	const effortTokenTable = resolveEffortTokenTable(options?.reasoningEffortTokens);
+	const adaptiveOnlyModels = options?.adaptiveOnlyModels;
+	return {
+		supportsJsonObjectMode: false,
+		chat: { completions: {
+			async create(params, requestOptions) {
+				const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels, effortTokenTable, adaptiveOnlyModels);
+				const response = await client.converse(request, requestOptions);
+				let text;
+				let wireToolCalls;
+				if (toolName) {
+					const toolUseBlock = response.output?.message?.content?.find((block) => block.toolUse?.name === toolName);
+					text = toolUseBlock?.toolUse ? JSON.stringify(toolUseBlock.toolUse.input) : "";
+				} else {
+					const blocks = response.output?.message?.content ?? [];
+					text = blocks.map((c) => c.text ?? "").join("");
+					const toolUses = blocks.filter((block) => Boolean(block.toolUse));
+					if (toolUses.length) wireToolCalls = toolUses.map((block, i) => {
+						const toolUse = block.toolUse;
+						if (!toolUse.name) throw new LLMError(`Bedrock returned a toolUse block without a name at index ${i}.`, "validation");
+						return {
+							id: toolUse.toolUseId ?? `${toolUse.name}_${i}`,
+							type: "function",
+							function: {
+								name: toolUse.name,
+								arguments: JSON.stringify(toolUse.input ?? {})
+							}
+						};
+					});
 				}
-			};
-		},
-		async *createStream(params, requestOptions) {
-			if (!bedrockClient.converseStream) throw new LLMError("stream: true requires a Bedrock client with converseStream", "validation");
-			const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels);
-			const { stream } = await bedrockClient.converseStream(request, requestOptions);
-			const blockKinds = new Map();
-			for await (const event of stream) if ("contentBlockStart" in event) {
-				const { contentBlockIndex, start } = event.contentBlockStart;
-				if (start?.toolUse) {
-					const kind = start.toolUse.name === toolName ? "json-tool" : "tool_use";
-					blockKinds.set(contentBlockIndex, kind);
-					if (kind === "tool_use" && !toolName) yield {
-						type: "tool_call_delta",
-						index: contentBlockIndex,
-						id: start.toolUse.toolUseId,
-						name: start.toolUse.name
-					};
-				} else blockKinds.set(contentBlockIndex, "text");
-			} else if ("contentBlockDelta" in event) {
-				const { contentBlockIndex, delta } = event.contentBlockDelta;
-				if (delta && "text" in delta && delta.text !== void 0 && !toolName) yield {
-					type: "text-delta",
-					delta: delta.text
+				return {
+					choices: [{ message: {
+						content: text,
+						...wireToolCalls ? { tool_calls: wireToolCalls } : {}
+					} }],
+					usage: {
+						prompt_tokens: response.usage?.inputTokens,
+						completion_tokens: response.usage?.outputTokens,
+						total_tokens: response.usage?.totalTokens
+					}
 				};
-				else if (delta && "toolUse" in delta && delta.toolUse?.input !== void 0) {
-					const kind = blockKinds.get(contentBlockIndex);
-					if (kind === "json-tool") yield {
+			},
+			async *createStream(params, requestOptions) {
+				if (!client.converseStream) throw new LLMError("stream: true requires a Bedrock client with converseStream", "invalid_params", {
+					code: "unsupported_capability",
+					issues: { capability: "converseStream" }
+				});
+				const { request, toolName } = buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOutputModels, effortTokenTable, adaptiveOnlyModels);
+				const { stream } = await client.converseStream(request, requestOptions);
+				const blockKinds = new Map();
+				for await (const event of stream) if ("contentBlockStart" in event) {
+					const { contentBlockIndex, start } = event.contentBlockStart;
+					if (start?.toolUse) {
+						const kind = start.toolUse.name === toolName ? "json-tool" : "tool_use";
+						blockKinds.set(contentBlockIndex, kind);
+						if (kind === "tool_use" && !toolName) yield {
+							type: "tool_call_delta",
+							index: contentBlockIndex,
+							id: start.toolUse.toolUseId,
+							name: start.toolUse.name
+						};
+					} else blockKinds.set(contentBlockIndex, "text");
+				} else if ("contentBlockDelta" in event) {
+					const { contentBlockIndex, delta } = event.contentBlockDelta;
+					if (delta && "text" in delta && delta.text !== void 0 && !toolName) yield {
 						type: "text-delta",
-						delta: delta.toolUse.input
-					};
-					else if (!toolName) yield {
-						type: "tool_call_delta",
-						index: contentBlockIndex,
-						argumentsDelta: delta.toolUse.input
+						delta: delta.text
 					};
+					else if (delta && "toolUse" in delta && delta.toolUse?.input !== void 0) {
+						const kind = blockKinds.get(contentBlockIndex);
+						if (kind === "json-tool") yield {
+							type: "text-delta",
+							delta: delta.toolUse.input
+						};
+						else if (!toolName) yield {
+							type: "tool_call_delta",
+							index: contentBlockIndex,
+							argumentsDelta: delta.toolUse.input
+						};
+					}
+				} else if ("metadata" in event && event.metadata.usage) yield {
+					type: "usage",
+					usage: {
+						prompt_tokens: event.metadata.usage.inputTokens,
+						completion_tokens: event.metadata.usage.outputTokens,
+						total_tokens: event.metadata.usage.totalTokens
+					}
+				};
+				else if ("throttlingException" in event) throw new LLMError(event.throttlingException.message ?? "Bedrock throttled the request mid-stream", "api", {
+					status: 429,
+					code: "provider_rate_limited"
+				});
+				else if ("validationException" in event) throw new LLMError(event.validationException.message ?? "Bedrock rejected the request mid-stream", "validation");
+				else if ("internalServerException" in event || "serviceUnavailableException" in event || "modelStreamErrorException" in event) {
+					const detail = "internalServerException" in event && event.internalServerException.message || "serviceUnavailableException" in event && event.serviceUnavailableException.message || "modelStreamErrorException" in event && event.modelStreamErrorException.message || "Bedrock reported a mid-stream error";
+					const status = "modelStreamErrorException" in event && event.modelStreamErrorException.originalStatusCode || "serviceUnavailableException" in event && 503 || 500;
+					throw new LLMError(detail, "api", {
+						status,
+						code: status >= 500 ? "server_error" : void 0
+					});
 				}
-			} else if ("metadata" in event && event.metadata.usage) yield {
-				type: "usage",
-				usage: {
-					prompt_tokens: event.metadata.usage.inputTokens,
-					completion_tokens: event.metadata.usage.outputTokens,
-					total_tokens: event.metadata.usage.totalTokens
-				}
-			};
-			else if ("throttlingException" in event) throw new LLMError(event.throttlingException.message ?? "Bedrock throttled the request mid-stream", "api", 429);
-			else if ("validationException" in event) throw new LLMError(event.validationException.message ?? "Bedrock rejected the request mid-stream", "validation");
-			else if ("internalServerException" in event || "serviceUnavailableException" in event || "modelStreamErrorException" in event) {
-				const detail = "internalServerException" in event && event.internalServerException.message || "serviceUnavailableException" in event && event.serviceUnavailableException.message || "modelStreamErrorException" in event && event.modelStreamErrorException.message || "Bedrock reported a mid-stream error";
-				const status = "modelStreamErrorException" in event && event.modelStreamErrorException.originalStatusCode || "serviceUnavailableException" in event && 503 || 500;
-				throw new LLMError(detail, "api", status);
 			}
-		}
-	} } };
+		} }
+	};
 }
 /** Maps VernLLM's OpenAI-shaped wire `tool_choice` onto Converse's `toolChoice`. */
 function toBedrockToolChoice(toolChoice) {
 	if (!toolChoice || toolChoice === "auto") return { auto: {} };
 	if (toolChoice === "required") return { any: {} };
-	if (toolChoice === "none") throw new LLMError("'none' is not supported by fromBedrock: Bedrock Converse has no `tool_choice` equivalent to forbidding tool use while tools are still offered. Omit `tools` entirely for this call instead.", "validation");
+	if (toolChoice === "none") throw new LLMError("'none' is not supported by fromBedrock: Bedrock Converse has no `tool_choice` equivalent to forbidding tool use while tools are still offered. Omit `tools` entirely for this call instead.", "invalid_params", {
+		code: "unsupported_capability",
+		issues: { capability: "toolChoice: 'none'" }
+	});
 	return { tool: { name: toolChoice.function.name } };
 }
 /**
@@ -3338,7 +4448,7 @@ function toBedrockMessage(m) {
 			else try {
 				input = JSON.parse(tc.function.arguments);
 			} catch (cause) {
-				throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) has arguments that are not valid JSON.`, "validation", void 0, void 0, cause);
+				throw new LLMError(`Assistant tool call "${tc.function.name}" (${tc.id}) has arguments that are not valid JSON.`, "validation", { cause });
 			}
 			blocks.push({ toolUse: {
 				toolUseId: tc.id,
@@ -3509,8 +4619,14 @@ function fromFetch(config) {
 			};
 		},
 		async *createStream(params, options) {
-			if (!config.mapStreamEvent) throw new LLMError("stream: true requires mapStreamEvent to be configured on fromFetch", "validation");
-			if (config.request && !config.requestStream) throw new LLMError("`stream: true` requires `requestStream` to be configured on fromFetch when a custom `request` transport is set. `requestStream` does not fall back to `request` (it needs an async-iterable byte stream, which `RequestLike`'s buffered `ResponseLike` has no way to provide), without it, `stream: true` would silently use plain native `fetch` instead of your configured transport. Add a `requestStream` that opens the same connection your `request` does, or omit `request` if native `fetch` is fine for both.", "validation");
+			if (!config.mapStreamEvent) throw new LLMError("stream: true requires mapStreamEvent to be configured on fromFetch", "invalid_params", {
+				code: "unsupported_capability",
+				issues: { capability: "mapStreamEvent" }
+			});
+			if (config.request && !config.requestStream) throw new LLMError("`stream: true` requires `requestStream` to be configured on fromFetch when a custom `request` transport is set. `requestStream` does not fall back to `request` (it needs an async-iterable byte stream, which `RequestLike`'s buffered `ResponseLike` has no way to provide), without it, `stream: true` would silently use plain native `fetch` instead of your configured transport. Add a `requestStream` that opens the same connection your `request` does, or omit `request` if native `fetch` is fine for both.", "invalid_params", {
+				code: "unsupported_capability",
+				issues: { capability: "requestStream" }
+			});
 			const { url, method, headers, body } = await buildRequestInit(config, params, config.mapRequest(params));
 			const requestStream = config.requestStream ?? defaultRequestStream;
 			const parseFrames = config.parseStreamFrames ?? parseSseStream;
@@ -3537,6 +4653,22 @@ function fromFetch(config) {
 //#endregion
 //#region src/adapters/openaiCompatible.ts
 /**
+* OpenAI's wire format only understands `reasoning_effort`, not a raw
+* token budget. When the caller set `reasoningEffort`, it's already on
+* `params` and passed through unchanged, this function does nothing.
+* When only `budgetTokens` was set, it's converted to the nearest tier
+* and `budget_tokens` is dropped, since OpenAI's API would otherwise
+* silently ignore an unrecognized field.
+*/
+function applyReasoningBudget(params, effortTokenTable) {
+	if (params.budget_tokens === void 0) return params;
+	const { budget_tokens,...rest } = params;
+	return rest.reasoning_effort !== void 0 ? rest : {
+		...rest,
+		reasoning_effort: budgetTokensToEffort(budget_tokens, effortTokenTable)
+	};
+}
+/**
 * Translates a VernLLM `ContentBlock[]` into OpenAI's wire-level content
 * array. Text blocks become `{ type: 'text', text }`; image blocks become
 * `{ type: 'image_url', image_url: { url } }` with the base64 payload
@@ -3602,23 +4734,24 @@ function* toWireStreamChunks(chunk) {
 function fromOpenAICompatible(client, options = {}) {
 	const raw = client;
 	const { supportsStreamUsage = true } = options;
+	const effortTokenTable = resolveEffortTokenTable(options.reasoningEffortTokens);
 	const rawCreate = raw.chat.completions.create.bind(raw.chat.completions);
 	return { chat: { completions: {
 		async create(params, options$1) {
 			const messages = toOpenAIMessages(params);
-			return raw.chat.completions.create({
+			return raw.chat.completions.create(applyReasoningBudget({
 				...params,
 				messages
-			}, options$1);
+			}, effortTokenTable), options$1);
 		},
 		async *createStream(params, options$1) {
 			const messages = toOpenAIMessages(params);
-			const stream = await rawCreate({
+			const stream = await rawCreate(applyReasoningBudget({
 				...params,
 				messages,
 				stream: true,
 				...supportsStreamUsage ? { stream_options: { include_usage: true } } : {}
-			}, options$1);
+			}, effortTokenTable), options$1);
 			for await (const chunk of stream) yield* toWireStreamChunks(chunk);
 		}
 	} } };
@@ -3742,6 +4875,8 @@ exports.TieredCacheAdapter = TieredCacheAdapter
 exports.VernLLM = VernLLM
 exports.defaultEstimateTokens = defaultEstimateTokens
 exports.defaultFallbackOn = defaultFallbackOn
+exports.defineCachedCallParams = defineCachedCallParams
+exports.defineCallParams = defineCallParams
 exports.from01AI = from01AI
 exports.fromAnthropic = fromAnthropic
 exports.fromAnyscale = fromAnyscale
@@ -3785,6 +4920,8 @@ exports.fromVLLM = fromVLLM
 exports.fromVercelAIGateway = fromVercelAIGateway
 exports.fromXAI = fromXAI
 exports.fromZhipu = fromZhipu
+exports.hasIssues = hasIssues
+exports.isFallbackExhaustedError = isFallbackExhaustedError
 exports.isLLMError = isLLMError
 exports.isToolCallResult = isToolCallResult
 exports.parseSseStream = parseSseStream