vern-llm 2.1.0 → 2.2.0

package/README.md

@@ -36,10 +36,10 @@ pnpm add vern-llm
 ```ts
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
-import { fromAnthropic, VernLLM } from 'vern-llm';
+import { fromAnthropic, fromOpenAI, VernLLM } from 'vern-llm';
 
 const llm = new VernLLM({
-  client: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  client: fromOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY })),
   model: 'gpt-4o',
   maxRetries: 3,
   timeoutMs: 10_000,

package/dist/index.cjs

@@ -187,13 +187,14 @@ const defaultFallbackOn = (error) => {
 * or `fallbackOn` chose to stop early. Carries each attempt in order so
 * an outage across providers stays debuggable without reproducing it.
 * Extends `LLMError` so `isLLMError` and any `instanceof LLMError` check
-* still passes, inheriting the last failure's `type` so existing
-* type-based handling keeps working on a fallback-exhausted error too.
+* still passes, inheriting the last failure's `type`/`status`/`retryAfterMs`
+* so existing type-based handling, including reading `retryAfterMs` on an
+* `'api'`-typed error, keeps working on a fallback-exhausted error too.
 */
 var FallbackExhaustedError = class extends LLMError {
 	constructor(attempts) {
 		const last = attempts[attempts.length - 1]?.error;
-		super(`${attempts.length} provider${attempts.length === 1 ? "" : "s"} attempted and failed: ${attempts.map((a) => `${a.provider}(${a.error.type})`).join(" then ")}`, last?.type ?? "unknown", last?.status, void 0, last, void 0, "fallback_exhausted");
+		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");
 		this.attempts = attempts;
 	}
 };
@@ -914,6 +915,52 @@ function extractStatus(err) {
 	if (typeof error.$metadata?.httpStatusCode === "number") return error.$metadata.httpStatusCode;
 	return void 0;
 }
+/**
+* POSIX/libuv error codes libuv (and so Node's `fetch`/undici) attaches to
+* genuine transport-level failures: connection refused, DNS lookup
+* failure, connection reset mid-request, a connect that never completed,
+* DNS server unreachable, broken pipe, or host/network unreachable.
+* Deliberately narrow: only codes that can only mean "the connection
+* itself failed," not anything that could also indicate an application
+* error.
+*/
+const NETWORK_ERROR_CODES = new Set([
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"ECONNRESET",
+	"ETIMEDOUT",
+	"EAI_AGAIN",
+	"EPIPE",
+	"ECONNABORTED",
+	"EHOSTUNREACH",
+	"ENETUNREACH"
+]);
+/** `fetch`'s own wording for a transport-level failure, across runtimes/browsers. */
+const NETWORK_ERROR_MESSAGES = new Set([
+	"fetch failed",
+	"failed to fetch",
+	"load failed",
+	"networkerror when attempting to fetch resource."
+]);
+/**
+* Whether `error` is, with reasonable confidence, a transport-level
+* failure (never reached the provider, as opposed to the provider itself
+* responding with an error) rather than some other unexpected exception.
+* Checked via explicit, well-known signals only, so a genuinely unknown
+* error never gets misclassified as a connection failure just because it
+* also lacked an HTTP status.
+*/
+function isNetworkError(error) {
+	if (!error || typeof error !== "object") return false;
+	const err = error;
+	if (typeof err.code === "string" && NETWORK_ERROR_CODES.has(err.code)) return true;
+	if (typeof err.message === "string" && NETWORK_ERROR_MESSAGES.has(err.message.toLowerCase())) return true;
+	if (err.cause && typeof err.cause === "object") {
+		const cause = err.cause;
+		if (typeof cause.code === "string" && NETWORK_ERROR_CODES.has(cause.code)) return true;
+	}
+	return false;
+}
 function formatSafely(value) {
 	try {
 		return JSON.stringify(value, null, 2) ?? String(value);
@@ -944,13 +991,16 @@ function describeError(err) {
 function normalizeError(error, signal) {
 	if (signal?.aborted) return new LLMError("LLM request aborted", "aborted");
 	if (error instanceof LLMError) {
-		if (error.status === 429 && error.code === void 0) error.code = "provider_rate_limited";
+		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";
+		}
 		return error;
 	}
 	const status = extractStatus(error);
 	const retryAfterMs = extractRetryAfterMs(error);
-	if (status !== void 0) return new LLMError("LLM request failed", "api", status, void 0, error, retryAfterMs, status === 429 ? "provider_rate_limited" : void 0);
-	return new LLMError("LLM request failed", "unknown", void 0, void 0, error, retryAfterMs);
+	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);
 }
 
 //#endregion
@@ -1483,6 +1533,7 @@ var CallExecutor = class {
 			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");
 				const toolCalls = parseWireToolCalls(wireToolCalls);
 				this.validateToolCallArguments(toolCalls, params.tools);
 				this.breaker?.recordSuccess(model);
@@ -1743,7 +1794,7 @@ var CallExecutor = class {
 		await waitForRetry(delay, signal);
 	}
 	isNonRetryableToolContractError(error) {
-		return error instanceof LLMError && (error.code === "unknown_tool" || error.code === "duplicate_tool_call_id");
+		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) {
@@ -1756,11 +1807,12 @@ var CallExecutor = class {
 	}
 	/**
 	* Decides whether a failed attempt should count toward the circuit
-	* breaker's failure threshold. A model hallucinating a tool name or
-	* reusing a call id isn't the provider being unhealthy, it's a model
-	* response defect that will very likely recur regardless of provider
-	* health, so it shouldn't push a healthy provider's circuit toward
-	* opening. Mirrors the same reasoning `shouldRetry` already applies to
+	* breaker's failure threshold. A model hallucinating a tool name,
+	* 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.
 	*/
 	countsTowardBreaker(error) {
@@ -1823,7 +1875,8 @@ var TokenBucket = class {
 	refill() {
 		if (this.refillPerMs === 0) return;
 		const now = Date.now();
-		this.available = Math.min(this.capacity, this.available + (now - this.lastRefill) * this.refillPerMs);
+		const elapsedMs = now - this.lastRefill;
+		this.available = Math.min(this.capacity, this.available + Math.max(0, elapsedMs) * this.refillPerMs);
 		this.lastRefill = now;
 	}
 	/** Refills, then takes `amount` if available. Leaves the bucket untouched if it can't. */
@@ -1916,7 +1969,6 @@ var RateLimiter = class {
 				release: this.makeRelease(estimatedTokens),
 				waitedMs: 0
 			};
-			if (this.maxQueueSize > 0 && this.queue.length >= this.maxQueueSize) throw this.queueFullError();
 			return this.enqueue(estimatedTokens, attempt.reason, signal);
 		}
 		if (this.maxQueueSize > 0 && this.queue.length >= this.maxQueueSize) throw this.queueFullError();
@@ -2247,8 +2299,8 @@ var VernLLM = class {
 	}
 	async cachedCall(params) {
 		const { call: callParams,...cacheParams } = params;
-		const { reserveUsage, refundUsage,...restCallParams } = callParams;
-		if (reserveUsage || refundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedCall; set them at the top level instead.");
+		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.stream) {
 			const streamParams = restCallParams;
 			return this.cacheOrchestrator.runCachedStream({
@@ -3571,6 +3623,20 @@ function fromOpenAICompatible(client, options = {}) {
 		}
 	} } };
 }
+/**
+* Named alias for the OpenAI SDK itself. A raw `new OpenAI(...)` instance
+* structurally matches most of `LLMClient`, but newer `openai` SDK major
+* versions have widened `ChatCompletionContentPart` (e.g. adding a `file`
+* variant) in ways that no longer structurally satisfy VernLLM's
+* provider-agnostic `ContentBlock[]` on `userContent`, so passing the SDK
+* instance directly can fail to typecheck depending on the installed
+* `openai` version. Wrapping with `fromOpenAI()` (a plain alias of
+* `fromOpenAICompatible()`) sidesteps that by translating through
+* `unknown` at the boundary, and also picks up multimodal image
+* translation and `createStream` wiring that a raw client doesn't have.
+* See Migration Notes for details.
+*/
+const fromOpenAI = fromOpenAICompatible;
 /** Groqs SDK matches the OpenAI wire format */
 const fromGroq = fromOpenAICompatible;
 /**
@@ -3628,8 +3694,6 @@ const fromNvidiaNIM = fromOpenAICompatible;
 const fromVercelAIGateway = fromOpenAICompatible;
 /** Cloudflare Workers AI exposes an OpenAI-compatible endpoint */
 const fromCloudflareWorkersAI = fromOpenAICompatible;
-/** GitHub Models is OpenAI-compatible */
-const fromGitHubModels = fromOpenAICompatible;
 /** Nebius AI Studio is OpenAI-compatible */
 const fromNebius = fromOpenAICompatible;
 /** SambaNova Cloud's API is OpenAI-compatible */
@@ -3656,8 +3720,6 @@ const fromSnowflakeCortex = fromOpenAICompatible;
 const fromAnyscale = fromOpenAICompatible;
 /** Lepton AI's inference API is OpenAI-compatible */
 const fromLepton = fromOpenAICompatible;
-/** kluster.ai's inference API is OpenAI-compatible */
-const fromKlusterAI = fromOpenAICompatible;
 /** Inference.net's API is OpenAI-compatible */
 const fromInferenceNet = fromOpenAICompatible;
 /** Infermatic's API is OpenAI-compatible */
@@ -3695,12 +3757,10 @@ exports.fromFetch = fromFetch
 exports.fromFireworks = fromFireworks
 exports.fromFriendli = fromFriendli
 exports.fromGemini = fromGemini
-exports.fromGitHubModels = fromGitHubModels
 exports.fromGroq = fromGroq
 exports.fromHyperbolic = fromHyperbolic
 exports.fromInferenceNet = fromInferenceNet
 exports.fromInfermatic = fromInfermatic
-exports.fromKlusterAI = fromKlusterAI
 exports.fromLMStudio = fromLMStudio
 exports.fromLambdaLabs = fromLambdaLabs
 exports.fromLepton = fromLepton
@@ -3711,6 +3771,7 @@ exports.fromNebius = fromNebius
 exports.fromNovita = fromNovita
 exports.fromNvidiaNIM = fromNvidiaNIM
 exports.fromOllama = fromOllama
+exports.fromOpenAI = fromOpenAI
 exports.fromOpenAICompatible = fromOpenAICompatible
 exports.fromOpenRouter = fromOpenRouter
 exports.fromParasail = fromParasail