@jaypie/llm 1.3.10 → 1.3.11

package/dist/cjs/index.cjs

@@ -404,6 +404,36 @@ function determineModelProvider(input) {
     };
 }
 
+/**
+ * Normalizes a `model` option that may be a single model name or a
+ * preference-ordered array of model names.
+ *
+ * A `string[]` is interpreted as a fallback chain: index `0` is the primary
+ * model, indices `1..` become fallback entries with an auto-detected provider
+ * (reusing `determineModelProvider`, exactly as the constructor's first
+ * argument does).
+ *
+ * Returns the primary model plus the derived fallback chain. A bare string
+ * yields an empty chain and is unchanged.
+ */
+function resolveModelChain(model) {
+    if (!Array.isArray(model)) {
+        return { fallback: [], model };
+    }
+    if (model.length === 0) {
+        throw new errors.ConfigurationError("model array must contain at least one model name");
+    }
+    const [primary, ...rest] = model;
+    const fallback = rest.map((name) => {
+        const determined = determineModelProvider(name);
+        if (!determined.provider) {
+            throw new errors.ConfigurationError(`Unable to determine provider from model: ${name}`);
+        }
+        return { model: determined.model, provider: determined.provider };
+    });
+    return { fallback, model: primary };
+}
+
 //
 //
 // Abstract Base Adapter
@@ -1489,17 +1519,23 @@ function tryParseNumber(input, options) {
 /**
  * Categories of errors for retry logic
  */
-var ErrorCategory;
+exports.ErrorCategory = void 0;
 (function (ErrorCategory) {
     /** Error is transient and can be retried */
     ErrorCategory["Retryable"] = "retryable";
-    /** Error is due to rate limiting */
+    /** Error is due to short-term rate limiting (retry after a delay) */
     ErrorCategory["RateLimit"] = "rate_limit";
+    /**
+     * Provider quota is exhausted or the account cannot be billed
+     * (insufficient funds, daily quota, plan limit). Terminal and actionable —
+     * retrying within the request budget will not help.
+     */
+    ErrorCategory["Quota"] = "quota";
     /** Error cannot be recovered from */
     ErrorCategory["Unrecoverable"] = "unrecoverable";
     /** Error type is unknown */
     ErrorCategory["Unknown"] = "unknown";
-})(ErrorCategory || (ErrorCategory = {}));
+})(exports.ErrorCategory || (exports.ErrorCategory = {}));
 
 /**
  * Transient network error detection utility.
@@ -1585,6 +1621,99 @@ function isTransientNetworkError(error) {
     return false;
 }
 
+//
+//
+// Constants
+//
+/**
+ * Transient structured-output compile failures. The provider caches the
+ * compiled grammar after a successful compile, so an immediate retry of the
+ * identical request typically succeeds (issue #422).
+ */
+const RETRYABLE_MESSAGE_PATTERNS = [
+    "grammar compilation timed out",
+    "grammar compilation timeout",
+];
+/** Billing / insufficient-funds signals — the account cannot be charged. */
+const BILLING_MESSAGE_PATTERNS = [
+    "insufficient_quota",
+    "insufficient funds",
+    "insufficient credit",
+    "credit balance",
+    "billing",
+    "payment required",
+    "plan and billing",
+];
+/** Exhausted usage quota (per-day / per-model limits). */
+const QUOTA_MESSAGE_PATTERNS = [
+    "quota exceeded",
+    "exceeded your current quota",
+    "resource_exhausted",
+    "quota_exceeded",
+];
+//
+//
+// Helpers
+//
+function extractMessage(error) {
+    if (error instanceof Error)
+        return error.message.toLowerCase();
+    if (typeof error === "string")
+        return error.toLowerCase();
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string")
+            return message.toLowerCase();
+    }
+    return "";
+}
+//
+//
+// Main
+//
+/**
+ * Shared, provider-agnostic first pass over an error. Returns a
+ * {@link ClassifiedError} when the message unambiguously identifies a
+ * cross-provider condition (retryable structured-output timeout, exhausted
+ * quota, or a billing failure), or `undefined` to defer to the adapter's own
+ * status/name classification.
+ *
+ * Adapters call this before their existing logic so that, for example, a
+ * `429` carrying a daily-quota message is classified as {@link
+ * ErrorCategory.Quota} rather than {@link ErrorCategory.RateLimit}.
+ */
+function classifyProviderError(error) {
+    const message = extractMessage(error);
+    if (!message)
+        return undefined;
+    for (const pattern of RETRYABLE_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return { category: exports.ErrorCategory.Retryable, error, shouldRetry: true };
+        }
+    }
+    for (const pattern of BILLING_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return {
+                category: exports.ErrorCategory.Quota,
+                error,
+                reason: "billing",
+                shouldRetry: false,
+            };
+        }
+    }
+    for (const pattern of QUOTA_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return {
+                category: exports.ErrorCategory.Quota,
+                error,
+                reason: "quota",
+                shouldRetry: false,
+            };
+        }
+    }
+    return undefined;
+}
+
 //
 //
 // Constants
@@ -2358,12 +2487,17 @@ class AnthropicAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         const errorName = error?.constructor?.name;
         // Check for rate limit error
         if (errorName === "RateLimitError") {
             return {
                 error,
-                category: ErrorCategory.RateLimit,
+                category: exports.ErrorCategory.RateLimit,
                 shouldRetry: false,
                 suggestedDelayMs: 60000,
             };
@@ -2372,7 +2506,7 @@ class AnthropicAdapter extends BaseProviderAdapter {
         if (RETRYABLE_ERROR_NAMES.includes(errorName)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
@@ -2380,7 +2514,7 @@ class AnthropicAdapter extends BaseProviderAdapter {
         if (NOT_RETRYABLE_ERROR_NAMES.includes(errorName)) {
             return {
                 error,
-                category: ErrorCategory.Unrecoverable,
+                category: exports.ErrorCategory.Unrecoverable,
                 shouldRetry: false,
             };
         }
@@ -2388,14 +2522,14 @@ class AnthropicAdapter extends BaseProviderAdapter {
         if (isTransientNetworkError(error)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
         // Unknown error - treat as potentially retryable
         return {
             error,
-            category: ErrorCategory.Unknown,
+            category: exports.ErrorCategory.Unknown,
             shouldRetry: true,
         };
     }
@@ -2966,6 +3100,11 @@ class BedrockAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         const errorName = error?.constructor?.name;
         const errorMessage = error?.message ?? "";
         if (errorName === "ThrottlingException" ||
@@ -2973,7 +3112,7 @@ class BedrockAdapter extends BaseProviderAdapter {
             errorMessage.includes("Too Many Requests")) {
             return {
                 error,
-                category: ErrorCategory.RateLimit,
+                category: exports.ErrorCategory.RateLimit,
                 shouldRetry: false,
                 suggestedDelayMs: 60000,
             };
@@ -2984,7 +3123,7 @@ class BedrockAdapter extends BaseProviderAdapter {
             errorMessage.includes("InternalServerException")) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
@@ -2995,20 +3134,20 @@ class BedrockAdapter extends BaseProviderAdapter {
             errorMessage.includes("ValidationException")) {
             return {
                 error,
-                category: ErrorCategory.Unrecoverable,
+                category: exports.ErrorCategory.Unrecoverable,
                 shouldRetry: false,
             };
         }
         if (isTransientNetworkError(error)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
         return {
             error,
-            category: ErrorCategory.Unknown,
+            category: exports.ErrorCategory.Unknown,
             shouldRetry: true,
         };
     }
@@ -3635,6 +3774,11 @@ class GoogleAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         const geminiError = error;
         // Extract status code from error
         const statusCode = geminiError.status || geminiError.code;
@@ -3642,7 +3786,7 @@ class GoogleAdapter extends BaseProviderAdapter {
         if (statusCode === 429) {
             return {
                 error,
-                category: ErrorCategory.RateLimit,
+                category: exports.ErrorCategory.RateLimit,
                 shouldRetry: false,
                 suggestedDelayMs: 60000,
             };
@@ -3652,7 +3796,7 @@ class GoogleAdapter extends BaseProviderAdapter {
             RETRYABLE_STATUS_CODES$1.includes(statusCode)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
@@ -3661,7 +3805,7 @@ class GoogleAdapter extends BaseProviderAdapter {
             NOT_RETRYABLE_STATUS_CODES.includes(statusCode)) {
             return {
                 error,
-                category: ErrorCategory.Unrecoverable,
+                category: exports.ErrorCategory.Unrecoverable,
                 shouldRetry: false,
             };
         }
@@ -3671,7 +3815,7 @@ class GoogleAdapter extends BaseProviderAdapter {
             errorMessage.includes("quota exceeded")) {
             return {
                 error,
-                category: ErrorCategory.RateLimit,
+                category: exports.ErrorCategory.RateLimit,
                 shouldRetry: false,
                 suggestedDelayMs: 60000,
             };
@@ -3681,7 +3825,7 @@ class GoogleAdapter extends BaseProviderAdapter {
             errorMessage.includes("ECONNREFUSED")) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
@@ -3689,14 +3833,14 @@ class GoogleAdapter extends BaseProviderAdapter {
         if (isTransientNetworkError(error)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
         // Unknown error - treat as potentially retryable
         return {
             error,
-            category: ErrorCategory.Unknown,
+            category: exports.ErrorCategory.Unknown,
             shouldRetry: true,
         };
     }
@@ -4583,11 +4727,16 @@ class OpenAiAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         // Check for rate limit error
         if (error instanceof RateLimitError$1) {
             return {
                 error,
-                category: ErrorCategory.RateLimit,
+                category: exports.ErrorCategory.RateLimit,
                 shouldRetry: false, // Rate limit requires waiting, not immediate retry
                 suggestedDelayMs: 60000, // 1 minute default
             };
@@ -4597,7 +4746,7 @@ class OpenAiAdapter extends BaseProviderAdapter {
             if (error instanceof ErrorType) {
                 return {
                     error,
-                    category: ErrorCategory.Retryable,
+                    category: exports.ErrorCategory.Retryable,
                     shouldRetry: true,
                 };
             }
@@ -4607,7 +4756,7 @@ class OpenAiAdapter extends BaseProviderAdapter {
             if (error instanceof ErrorType) {
                 return {
                     error,
-                    category: ErrorCategory.Unrecoverable,
+                    category: exports.ErrorCategory.Unrecoverable,
                     shouldRetry: false,
                 };
             }
@@ -4616,14 +4765,14 @@ class OpenAiAdapter extends BaseProviderAdapter {
         if (isTransientNetworkError(error)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
         // Unknown error - treat as potentially retryable
         return {
             error,
-            category: ErrorCategory.Unknown,
+            category: exports.ErrorCategory.Unknown,
             shouldRetry: true,
         };
     }
@@ -5351,6 +5500,11 @@ class OpenRouterAdapter extends BaseProviderAdapter {
     // Error Classification
     //
     classifyError(error) {
+        // Shared first pass: retryable structured-output timeouts (#422),
+        // quota exhaustion, and billing failures classify the same across providers.
+        const shared = classifyProviderError(error);
+        if (shared)
+            return shared;
         // Check if error has a status code (HTTP error)
         const errorWithStatus = error;
         const statusCode = errorWithStatus.status || errorWithStatus.statusCode;
@@ -5359,7 +5513,7 @@ class OpenRouterAdapter extends BaseProviderAdapter {
             if (statusCode === RATE_LIMIT_STATUS_CODE) {
                 return {
                     error,
-                    category: ErrorCategory.RateLimit,
+                    category: exports.ErrorCategory.RateLimit,
                     shouldRetry: false,
                     suggestedDelayMs: 60000,
                 };
@@ -5368,7 +5522,7 @@ class OpenRouterAdapter extends BaseProviderAdapter {
             if (RETRYABLE_STATUS_CODES.includes(statusCode)) {
                 return {
                     error,
-                    category: ErrorCategory.Retryable,
+                    category: exports.ErrorCategory.Retryable,
                     shouldRetry: true,
                 };
             }
@@ -5376,7 +5530,7 @@ class OpenRouterAdapter extends BaseProviderAdapter {
             if (statusCode >= 400 && statusCode < 500) {
                 return {
                     error,
-                    category: ErrorCategory.Unrecoverable,
+                    category: exports.ErrorCategory.Unrecoverable,
                     shouldRetry: false,
                 };
             }
@@ -5387,7 +5541,7 @@ class OpenRouterAdapter extends BaseProviderAdapter {
             errorMessage.includes("too many requests")) {
             return {
                 error,
-                category: ErrorCategory.RateLimit,
+                category: exports.ErrorCategory.RateLimit,
                 shouldRetry: false,
                 suggestedDelayMs: 60000,
             };
@@ -5396,14 +5550,14 @@ class OpenRouterAdapter extends BaseProviderAdapter {
         if (isTransientNetworkError(error)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
         // Unknown error - treat as potentially retryable
         return {
             error,
-            category: ErrorCategory.Unknown,
+            category: exports.ErrorCategory.Unknown,
             shouldRetry: true,
         };
     }
@@ -5627,7 +5781,7 @@ class XaiAdapter extends OpenAiAdapter {
         if (isTransientIngestError(error)) {
             return {
                 error,
-                category: ErrorCategory.Retryable,
+                category: exports.ErrorCategory.Retryable,
                 shouldRetry: true,
             };
         }
@@ -6715,6 +6869,122 @@ function createStaleRejectionGuard() {
     };
 }
 
+//
+//
+// Base
+//
+/**
+ * Normalized, provider-agnostic LLM error. Thrown by the operate/stream retry
+ * layer when a request cannot be completed, so consumers can `catch` a stable
+ * type regardless of which provider failed. Extends {@link JaypieError} so
+ * `isJaypieError()` and `.status` continue to work; the original provider error
+ * is preserved on `.cause`.
+ */
+class LlmError extends errors.JaypieError {
+    constructor(message, category, { status = 502, title = "Bad Gateway", provider, model, retryAfterMs, cause, } = {}) {
+        super(message, { status, title }, { _type: "LlmError" });
+        this.name = "LlmError";
+        this.category = category;
+        this.provider = provider;
+        this.model = model;
+        this.retryAfterMs = retryAfterMs;
+        this.cause = cause;
+    }
+}
+//
+//
+// Subclasses
+//
+/**
+ * Short-term rate limiting (per-minute 429). Terminal within the request
+ * budget; `retryAfterMs` carries the provider's suggested wait when available.
+ */
+class LlmRateLimitError extends LlmError {
+    constructor(message, options = {}) {
+        super(message, exports.ErrorCategory.RateLimit, {
+            status: 429,
+            title: "Too Many Requests",
+            ...options,
+        });
+        this.name = "LlmRateLimitError";
+    }
+}
+/**
+ * Provider quota is exhausted or the account cannot be billed. Terminal and
+ * actionable. `reason` distinguishes an exhausted usage quota from insufficient
+ * funds.
+ */
+class LlmQuotaError extends LlmError {
+    constructor(message, { reason = "quota", ...options } = {}) {
+        super(message, exports.ErrorCategory.Quota, {
+            status: 402,
+            title: "Payment Required",
+            ...options,
+        });
+        this.name = "LlmQuotaError";
+        this.reason = reason;
+    }
+}
+/**
+ * The request cannot be recovered from (bad request, authentication,
+ * permission, not found). Terminal.
+ */
+class LlmUnrecoverableError extends LlmError {
+    constructor(message, options = {}) {
+        super(message, exports.ErrorCategory.Unrecoverable, {
+            status: 502,
+            title: "Bad Gateway",
+            ...options,
+        });
+        this.name = "LlmUnrecoverableError";
+    }
+}
+/**
+ * A transient or unknown error survived the retry budget. Terminal only because
+ * retries were exhausted; the underlying condition may succeed later.
+ */
+class LlmTransientError extends LlmError {
+    constructor(message, options = {}) {
+        super(message, exports.ErrorCategory.Retryable, {
+            status: 504,
+            title: "Gateway Timeout",
+            ...options,
+        });
+        this.name = "LlmTransientError";
+    }
+}
+
+/**
+ * Map a {@link ClassifiedError} to the matching {@link LlmError} subclass,
+ * preserving the original error as `cause`. Used by the retry layer to throw a
+ * stable, catchable type instead of a bare gateway error.
+ */
+function toLlmError(classified, context = {}) {
+    const original = classified.error;
+    const message = original instanceof Error ? original.message : String(original);
+    const options = {
+        cause: original,
+        model: context.model,
+        provider: context.provider,
+        retryAfterMs: classified.suggestedDelayMs,
+    };
+    switch (classified.category) {
+        case exports.ErrorCategory.RateLimit:
+            return new LlmRateLimitError(message, options);
+        case exports.ErrorCategory.Quota:
+            return new LlmQuotaError(message, {
+                ...options,
+                reason: classified.reason ?? "quota",
+            });
+        case exports.ErrorCategory.Unrecoverable:
+            return new LlmUnrecoverableError(message, options);
+        case exports.ErrorCategory.Retryable:
+        case exports.ErrorCategory.Unknown:
+        default:
+            return new LlmTransientError(message, options);
+    }
+}
+
 //
 //
 // Main
@@ -6729,6 +6999,18 @@ class RetryExecutor {
         this.hookRunner = config.hookRunner ?? hookRunner;
         this.errorClassifier = config.errorClassifier;
     }
+    /**
+     * Build the typed, provider-agnostic error thrown when a request cannot be
+     * completed — classified (rate limit / quota / unrecoverable / transient)
+     * and carrying the provider, model, and original error as `cause`.
+     */
+    toTerminalError(error, context) {
+        const classified = this.errorClassifier.classify(error);
+        return toLlmError(classified, {
+            model: context.model,
+            provider: context.provider,
+        });
+    }
     /**
      * Execute an operation with retry logic.
      * Each attempt receives an AbortSignal. On failure, the signal is aborted
@@ -6772,8 +7054,7 @@ class RetryExecutor {
                             providerRequest: options.context.providerRequest,
                             error,
                         });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        throw new errors.BadGatewayError(errorMessage);
+                        throw this.toTerminalError(error, options.context);
                     }
                     // Check if error is not retryable
                     if (!this.errorClassifier.isRetryable(error)) {
@@ -6785,8 +7066,7 @@ class RetryExecutor {
                             providerRequest: options.context.providerRequest,
                             error,
                         });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        throw new errors.BadGatewayError(errorMessage);
+                        throw this.toTerminalError(error, options.context);
                     }
                     // Warn if this is an unknown error type
                     if (!this.errorClassifier.isKnownError(error)) {
@@ -6829,6 +7109,7 @@ const MAX_CONSECUTIVE_TOOL_ERRORS = 6;
  */
 function createErrorClassifier(adapter) {
     return {
+        classify: (error) => adapter.classifyError(error),
         isRetryable: (error) => adapter.isRetryableError(error),
         isKnownError: (error) => {
             const classified = adapter.classifyError(error);
@@ -7082,7 +7363,9 @@ class OperateLoop {
             const response = await retryExecutor.execute((signal) => this.adapter.executeRequest(this.client, providerRequest, signal), {
                 context: {
                     input: state.currentInput,
+                    model: options.model ?? this.adapter.defaultModel,
                     options,
+                    provider: this.adapter.name,
                     providerRequest,
                 },
                 hooks: hooksWithProgress,
@@ -7705,9 +7988,11 @@ class StreamLoop {
                         !this.adapter.isRetryableError(error)) {
                         log.error(`Stream request failed after ${this.retryPolicy.maxRetries} retries`);
                         log.var({ error });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
                         llmSpan?.finish();
-                        throw new errors.BadGatewayError(errorMessage);
+                        throw toLlmError(this.adapter.classifyError(error), {
+                            model: options.model ?? this.adapter.defaultModel,
+                            provider: this.adapter.name,
+                        });
                     }
                     const delay = this.retryPolicy.getDelayForAttempt(attempt);
                     log.warn(`Stream request failed. Retrying in ${delay}ms...`);
@@ -9178,7 +9463,14 @@ class XaiProvider {
 
 class Llm {
     constructor(providerName = DEFAULT.PROVIDER.NAME, options = {}) {
-        const { fallback, model } = options;
+        const { fallback: fallbackOption, model: modelOption } = options;
+        // A `model` array is sugar for a preference-ordered fallback chain:
+        // index 0 is primary, the rest become fallback entries (provider
+        // auto-detected). Any explicit `fallback` is appended after the chain.
+        const { fallback: modelFallback, model } = resolveModelChain(modelOption);
+        const fallback = modelFallback.length || fallbackOption
+            ? [...modelFallback, ...(fallbackOption ?? [])]
+            : undefined;
         let finalProvider = providerName;
         let finalModel = model;
         // Legacy: accept "gemini" but warn
@@ -9250,6 +9542,11 @@ class Llm {
         }
     }
     async send(message, options) {
+        if (options && Array.isArray(options.model)) {
+            // `send` has no fallback machinery; use the primary model only
+            const { model } = resolveModelChain(options.model);
+            return this._llm.send(message, { ...options, model });
+        }
         return this._llm.send(message, options);
     }
     /**
@@ -9282,8 +9579,21 @@ class Llm {
         if (!this._llm.operate) {
             throw new errors.NotImplementedError(`Provider ${this._provider} does not support operate method`);
         }
-        const fallbackChain = this.resolveFallbackChain(options);
-        const optionsWithoutFallback = { ...options, fallback: false };
+        // A per-call `model` array becomes primary + a derived fallback chain
+        // prepended to any resolved chain.
+        const { fallback: modelFallback, model: perCallModel } = resolveModelChain(options.model);
+        const resolvedOptions = {
+            ...options,
+            model: perCallModel,
+        };
+        const fallbackChain = [
+            ...modelFallback,
+            ...this.resolveFallbackChain(resolvedOptions),
+        ];
+        const optionsWithoutFallback = {
+            ...resolvedOptions,
+            fallback: false,
+        };
         let lastError;
         let attempts = 0;
         // Try primary provider first
@@ -9332,33 +9642,45 @@ class Llm {
         if (!this._llm.stream) {
             throw new errors.NotImplementedError(`Provider ${this._provider} does not support stream method`);
         }
-        yield* this._llm.stream(input, options);
+        // `stream` has no instance-level fallback machinery; an array model uses
+        // the primary and ignores the rest.
+        const { model } = resolveModelChain(options.model);
+        const streamOptions = { ...options, model };
+        yield* this._llm.stream(input, streamOptions);
     }
     static async send(message, options) {
         const { llm, apiKey, model, ...messageOptions } = options || {};
-        const instance = new Llm(llm, { apiKey, model });
+        // A `model` array derives a fallback chain; `send` has no fallback
+        // machinery, so the primary model is used and the chain is ignored.
+        const { model: primaryModel } = resolveModelChain(model);
+        const instance = new Llm(llm, { apiKey, model: primaryModel });
         return instance.send(message, messageOptions);
     }
     static async operate(input, options) {
         const { apiKey, fallback, llm, model, ...operateOptions } = options || {};
+        // A `model` array becomes primary + derived fallback chain
+        const { fallback: modelFallback, model: primaryModel } = resolveModelChain(model);
         let finalLlm = llm;
-        let finalModel = model;
-        if (!llm && model) {
-            const determined = determineModelProvider(model);
+        let finalModel = primaryModel;
+        if (!llm && primaryModel) {
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider) {
                 finalLlm = determined.provider;
             }
         }
-        else if (llm && model) {
+        else if (llm && primaryModel) {
             // When both llm and model are provided, check if they conflict
-            const determined = determineModelProvider(model);
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider && determined.provider !== llm) {
                 // Don't pass the conflicting model to the constructor
                 finalModel = undefined;
             }
         }
         // Resolve fallback for static method: pass to instance if array, pass to operate options if false
-        const instanceFallback = Array.isArray(fallback) ? fallback : undefined;
+        const explicitFallback = Array.isArray(fallback) ? fallback : [];
+        const instanceFallback = modelFallback.length || explicitFallback.length
+            ? [...modelFallback, ...explicitFallback]
+            : undefined;
         const operateFallback = fallback === false ? false : undefined;
         const instance = new Llm(finalLlm, {
             apiKey,
@@ -9372,23 +9694,29 @@ class Llm {
     }
     static stream(input, options) {
         const { llm, apiKey, model, ...streamOptions } = options || {};
+        // A `model` array becomes primary + derived fallback chain
+        const { fallback: modelFallback, model: primaryModel } = resolveModelChain(model);
         let finalLlm = llm;
-        let finalModel = model;
-        if (!llm && model) {
-            const determined = determineModelProvider(model);
+        let finalModel = primaryModel;
+        if (!llm && primaryModel) {
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider) {
                 finalLlm = determined.provider;
             }
         }
-        else if (llm && model) {
+        else if (llm && primaryModel) {
             // When both llm and model are provided, check if they conflict
-            const determined = determineModelProvider(model);
+            const determined = determineModelProvider(primaryModel);
             if (determined.provider && determined.provider !== llm) {
                 // Don't pass the conflicting model to the constructor
                 finalModel = undefined;
             }
         }
-        const instance = new Llm(finalLlm, { apiKey, model: finalModel });
+        const instance = new Llm(finalLlm, {
+            apiKey,
+            fallback: modelFallback.length ? modelFallback : undefined,
+            model: finalModel,
+        });
         return instance.stream(input, streamOptions);
     }
 }
@@ -9692,6 +10020,11 @@ exports.GoogleProvider = GoogleProvider;
 exports.JaypieToolkit = JaypieToolkit;
 exports.LLM = constants;
 exports.Llm = Llm;
+exports.LlmError = LlmError;
+exports.LlmQuotaError = LlmQuotaError;
+exports.LlmRateLimitError = LlmRateLimitError;
+exports.LlmTransientError = LlmTransientError;
+exports.LlmUnrecoverableError = LlmUnrecoverableError;
 exports.OpenRouterProvider = OpenRouterProvider;
 exports.Toolkit = Toolkit;
 exports.XaiProvider = XaiProvider;