vern-llm 2.2.0 → 2.3.0

package/dist/index.cjs

@@ -25,23 +25,205 @@ 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]";
+	}
+}
+/**
+* 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. 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)
+		}
+	}));
+}
 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 +353,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 +381,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 +426,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 +626,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 +669,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 +690,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 +719,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 +768,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 +810,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 +856,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 +896,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 +1041,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 +1074,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 +1239,58 @@ 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");
+/**
+* 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;
+	}
+}
+/**
+* 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) {
-			if (error.status === 429) error.code = "provider_rate_limited";
-			else if (error.status === 401 || error.status === 403) error.code = "invalid_credentials";
-		}
+		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) return new LLMError("LLM request failed", "api", {
+		status,
+		cause: error,
+		retryAfterMs,
+		code: codeForStatus(status),
+		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 +1339,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,
@@ -1064,9 +1354,13 @@ function parseWireToolCalls(wireToolCalls) {
 /**
 * 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`.
@@ -1084,7 +1378,7 @@ var RequestBuilder = class {
 	build(params) {
 		const { systemPrompt, userContent, history = [], maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema, tools, toolChoice } = params;
 		const temperature = params.temperature === void 0 ? this.defaultTemperature : params.temperature;
-		if (tools && tools.length === 0) throw new LLMError("`tools` was an empty array. This is almost always a bug (e.g. a filtered tool list that ended up empty). An empty `tools` array still switches on tool-call mode (response shape, jsonMode default, wire format) with nothing for the model to call. Omit `tools` entirely for a normal call, or make sure the array is non-empty.", "validation");
+		if (tools && 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 +1386,22 @@ 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");
+		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 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 (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 = {
@@ -1135,29 +1438,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) {
@@ -1425,6 +1746,18 @@ var CallExecutor = class {
 	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 +1779,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) => this.executeCall(params, requestId, attempt), 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 +1792,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) => this.executeStreamCall(params, requestId, attempt), 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;
@@ -1529,11 +1864,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);
@@ -1586,7 +1921,10 @@ var CallExecutor = class {
 	async executeStreamCall(params, requestId, attempt) {
 		const { useJson, model, request } = this.requestBuilder.build(params);
 		const completions = this.client.chat.completions;
-		if (!completions.createStream) throw new LLMError("stream: true requires a client/adapter with createStream", "validation");
+		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 +1985,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,20 +2013,31 @@ 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);
@@ -1696,7 +2045,12 @@ var CallExecutor = class {
 			return await fn(attempt);
 		} catch (error) {
 			lastError = error;
-			if (!this.shouldRetry(error, signal)) break;
+			const willRetry = attempt < this.maxRetries && this.shouldRetry(error, signal);
+			if (!willRetry) break;
+			attempts?.push({
+				index: attempt,
+				error: normalizeError(error, signal).toSnapshot()
+			});
 		}
 		throw lastError;
 	}
@@ -1766,7 +2120,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 +2133,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 +2147,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 +2160,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 +2342,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 +2356,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 +2389,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);
@@ -2142,7 +2523,7 @@ 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;
@@ -2235,7 +2616,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 +2635,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 +2681,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,35 +2695,67 @@ 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.`);
+	}
 };
 
 //#endregion
@@ -2382,7 +2795,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 +2811,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 +2856,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 +2879,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
@@ -2782,7 +3199,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,7 +3280,10 @@ 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;
@@ -2997,7 +3417,10 @@ function fromGemini(geminiClient) {
 			};
 		},
 		async *createStream(params, options) {
-			if (!geminiClient.generateContentStream) throw new LLMError("stream: true requires a Gemini client with generateContentStream", "validation");
+			if (!geminiClient.generateContentStream) throw new LLMError("stream: true requires a Gemini client with generateContentStream", "invalid_params", {
+				code: "unsupported_capability",
+				issues: { capability: "generateContentStream" }
+			});
 			const request = buildGeminiRequest(params);
 			request.config = {
 				...request.config,
@@ -3145,7 +3568,10 @@ function buildBedrockRequest(params, toolUseSupportedModels, nativeStructuredOut
 	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" }
+		});
 	}
 	const systemParts = [systemMessage?.content, jsonInstruction].filter((s) => Boolean(s));
 	const request = {
@@ -3257,7 +3683,10 @@ function fromBedrock(bedrockClient, options) {
 			};
 		},
 		async *createStream(params, requestOptions) {
-			if (!bedrockClient.converseStream) throw new LLMError("stream: true requires a Bedrock client with converseStream", "validation");
+			if (!bedrockClient.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);
 			const { stream } = await bedrockClient.converseStream(request, requestOptions);
 			const blockKinds = new Map();
@@ -3299,12 +3728,18 @@ function fromBedrock(bedrockClient, options) {
 					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 ("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);
+				throw new LLMError(detail, "api", {
+					status,
+					code: status >= 500 ? "server_error" : void 0
+				});
 			}
 		}
 	} } };
@@ -3313,7 +3748,10 @@ function fromBedrock(bedrockClient, options) {
 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 +3776,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 +3947,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;
@@ -3785,6 +4229,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