@jaypie/llm 1.3.9 → 1.3.11

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-import { ConfigurationError, BadGatewayError, TooManyRequestsError, NotImplementedError } from '@jaypie/errors';
+import { ConfigurationError, JaypieError, BadGatewayError, TooManyRequestsError, NotImplementedError } from '@jaypie/errors';
 import log$1, { log as log$2 } from '@jaypie/logger';
 import { z } from 'zod/v4';
 import { placeholders, JAYPIE, resolveValue, sleep } from '@jaypie/kit';
@@ -11,35 +11,21 @@ import { resolve } from 'path';
 import { getS3FileBuffer, getEnvSecret } from '@jaypie/aws';
 import { fetchWeatherApi } from 'openmeteo';
 
-const FIRST_CLASS_PROVIDER = {
-    // https://docs.anthropic.com/en/docs/about-claude/models/overview
-    ANTHROPIC: {
-        DEFAULT: "claude-sonnet-4-6",
-        LARGE: "claude-opus-4-8",
-        SMALL: "claude-sonnet-4-6",
-        TINY: "claude-haiku-4-5",
-    },
-    // https://ai.google.dev/gemini-api/docs/models
-    GOOGLE: {
-        DEFAULT: "gemini-3.1-pro-preview",
-        LARGE: "gemini-3.1-pro-preview",
-        SMALL: "gemini-3.5-flash",
-        TINY: "gemini-3.1-flash-lite",
-    },
-    // https://developers.openai.com/api/docs/models
-    OPENAI: {
-        DEFAULT: "gpt-5.4",
-        LARGE: "gpt-5.5",
-        SMALL: "gpt-5.4-mini",
-        TINY: "gpt-5.4-nano",
-    },
-    // https://docs.x.ai/developers/models
-    XAI: {
-        DEFAULT: "grok-latest",
-        LARGE: "grok-latest",
-        SMALL: "grok-4-1-fast-reasoning",
-        TINY: "grok-4-1-fast-non-reasoning",
-    },
+/**
+ * Provider-neutral reasoning-effort levels — a five-point relative scale that
+ * deliberately borrows no provider's vocabulary. Each adapter translates these
+ * to its provider's native control (OpenAI `reasoning.effort`, Anthropic
+ * `output_config.effort`, Gemini `thinkingLevel`/`thinkingBudget`, Grok
+ * `reasoning_effort`, OpenRouter `reasoning.effort`), spreading the scale across
+ * the provider's available range. Omitting `effort` leaves the provider default
+ * untouched, so it is safe to set across a fallback chain.
+ */
+const EFFORT = {
+    LOWEST: "lowest",
+    LOW: "low",
+    MEDIUM: "medium",
+    HIGH: "high",
+    HIGHEST: "highest",
 };
 const MODEL = {
     // Anthropic
@@ -53,19 +39,33 @@ const MODEL = {
     GEMINI_FLASH_LITE: "gemini-3.1-flash-lite",
     GEMINI_PRO: "gemini-3.1-pro-preview",
     // OpenAI
+    SOL: "gpt-5.6-sol",
+    TERRA: "gpt-5.6-terra",
+    LUNA: "gpt-5.6-luna",
+    /** @deprecated use MODEL.SOL (gpt-5.6-sol) */
     GPT: "gpt-5.5",
+    /** @deprecated use MODEL.TERRA (gpt-5.6-terra) */
     GPT_MINI: "gpt-5.4-mini",
+    /** @deprecated use MODEL.LUNA (gpt-5.6-luna) */
     GPT_NANO: "gpt-5.4-nano",
     // xAI
     GROK: "grok-latest",
+    // OpenRouter (provider-prefixed routes; traversed by the OpenRouter hot test)
+    OPENROUTER: {
+        GLM: "z-ai/glm-5.2",
+        LUNA: "openai/gpt-5.6-luna",
+        SONNET: "anthropic/claude-sonnet-5",
+    },
 };
 const GOOGLE_PROVIDER = {
     // https://ai.google.dev/gemini-api/docs/models
+    DEFAULT: MODEL.GEMINI_FLASH,
+    /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.GOOGLE.DEFAULT, or pick a specific model from MODEL.*. */
     MODEL: {
-        DEFAULT: FIRST_CLASS_PROVIDER.GOOGLE.DEFAULT,
-        LARGE: FIRST_CLASS_PROVIDER.GOOGLE.LARGE,
-        SMALL: FIRST_CLASS_PROVIDER.GOOGLE.SMALL,
-        TINY: FIRST_CLASS_PROVIDER.GOOGLE.TINY,
+        DEFAULT: "gemini-3.1-pro-preview",
+        LARGE: "gemini-3.1-pro-preview",
+        SMALL: "gemini-3.5-flash",
+        TINY: "gemini-3.1-flash-lite",
     },
     MODEL_MATCH_WORDS: ["gemini", "google"],
     NAME: "google",
@@ -77,6 +77,10 @@ const GOOGLE_PROVIDER = {
 const PROVIDER = {
     // https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html
     BEDROCK: {
+        // Bedrock has no MODEL.* catalog entry yet; keep the literal default id.
+        // nova-pro is the Amazon-native model that reliably does tools+structured.
+        DEFAULT: "amazon.nova-pro-v1:0",
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.BEDROCK.DEFAULT. */
         MODEL: {
             DEFAULT: "amazon.nova-lite-v1:0",
             LARGE: "amazon.nova-pro-v1:0",
@@ -97,22 +101,26 @@ const PROVIDER = {
     },
     ANTHROPIC: {
         // https://docs.anthropic.com/en/docs/about-claude/models/overview
+        DEFAULT: MODEL.SONNET,
         MAX_TOKENS: {
             // Non-streaming ceiling: responses above ~16K output tokens risk HTTP
             // timeouts; streaming requests resolve to the model maximum instead
             // (see util/maxOutputTokens.ts)
             DEFAULT: 16384,
         },
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.ANTHROPIC.DEFAULT, or pick a specific model from MODEL.*. */
         MODEL: {
-            DEFAULT: FIRST_CLASS_PROVIDER.ANTHROPIC.DEFAULT,
-            LARGE: FIRST_CLASS_PROVIDER.ANTHROPIC.LARGE,
-            SMALL: FIRST_CLASS_PROVIDER.ANTHROPIC.SMALL,
-            TINY: FIRST_CLASS_PROVIDER.ANTHROPIC.TINY,
+            DEFAULT: "claude-sonnet-4-6",
+            LARGE: "claude-opus-4-8",
+            SMALL: "claude-sonnet-4-6",
+            TINY: "claude-haiku-4-5",
         },
         MODEL_MATCH_WORDS: [
             "anthropic",
             "claude",
+            "fable",
             "haiku",
+            "mythos",
             "opus",
             "sonnet",
         ],
@@ -135,21 +143,25 @@ const PROVIDER = {
     GOOGLE: GOOGLE_PROVIDER,
     OPENAI: {
         // https://platform.openai.com/docs/models
+        DEFAULT: MODEL.SOL,
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.OPENAI.DEFAULT, or pick a specific model from MODEL.*. */
         MODEL: {
-            DEFAULT: FIRST_CLASS_PROVIDER.OPENAI.DEFAULT,
-            LARGE: FIRST_CLASS_PROVIDER.OPENAI.LARGE,
-            SMALL: FIRST_CLASS_PROVIDER.OPENAI.SMALL,
-            TINY: FIRST_CLASS_PROVIDER.OPENAI.TINY,
+            DEFAULT: "gpt-5.4",
+            LARGE: "gpt-5.5",
+            SMALL: "gpt-5.4-mini",
+            TINY: "gpt-5.4-nano",
         },
-        MODEL_MATCH_WORDS: ["openai", "gpt", /^o\d/],
+        MODEL_MATCH_WORDS: ["gpt", "luna", "openai", "sol", "terra", /^o\d/],
         NAME: "openai",
     },
     OPENROUTER: {
+        DEFAULT: MODEL.OPENROUTER.SONNET,
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.OPENROUTER.DEFAULT, or pick a specific route from MODEL.OPENROUTER.*. */
         MODEL: {
-            DEFAULT: `anthropic/${FIRST_CLASS_PROVIDER.ANTHROPIC.DEFAULT}`,
-            LARGE: `anthropic/${FIRST_CLASS_PROVIDER.ANTHROPIC.LARGE}`,
-            SMALL: `anthropic/${FIRST_CLASS_PROVIDER.ANTHROPIC.SMALL}`,
-            TINY: `anthropic/${FIRST_CLASS_PROVIDER.ANTHROPIC.TINY}`,
+            DEFAULT: "anthropic/claude-sonnet-4-6",
+            LARGE: "anthropic/claude-opus-4-8",
+            SMALL: "anthropic/claude-sonnet-4-6",
+            TINY: "anthropic/claude-haiku-4-5",
         },
         MODEL_MATCH_WORDS: ["openrouter"],
         NAME: "openrouter",
@@ -164,11 +176,13 @@ const PROVIDER = {
         // https://docs.x.ai/docs/models
         API_KEY: "XAI_API_KEY",
         BASE_URL: "https://api.x.ai/v1",
+        DEFAULT: MODEL.GROK,
+        /** @deprecated Size tiers are retired in 2.0. Use PROVIDER.XAI.DEFAULT, or pick a specific model from MODEL.*. */
         MODEL: {
-            DEFAULT: FIRST_CLASS_PROVIDER.XAI.DEFAULT,
-            LARGE: FIRST_CLASS_PROVIDER.XAI.LARGE,
-            SMALL: FIRST_CLASS_PROVIDER.XAI.SMALL,
-            TINY: FIRST_CLASS_PROVIDER.XAI.TINY,
+            DEFAULT: "grok-latest",
+            LARGE: "grok-latest",
+            SMALL: "grok-4-1-fast-reasoning",
+            TINY: "grok-4-1-fast-non-reasoning",
         },
         MODEL_MATCH_WORDS: ["grok", "xai"],
         NAME: "xai",
@@ -176,6 +190,7 @@ const PROVIDER = {
 };
 // Last: Defaults
 const DEFAULT = {
+    /** @deprecated Size tiers are retired in 2.0. Use DEFAULT.PROVIDER.DEFAULT, or pick a specific model from MODEL.*. */
     MODEL: {
         BASE: PROVIDER.OPENAI.MODEL.DEFAULT,
         LARGE: PROVIDER.OPENAI.MODEL.LARGE,
@@ -184,6 +199,10 @@ const DEFAULT = {
     },
     PROVIDER: PROVIDER.OPENAI,
 };
+/**
+ * @deprecated Size-tier catalogs are retired in 2.0. Pick specific models from
+ * MODEL.* (grouped by provider via MODEL_MATCH_WORDS / determineModelProvider).
+ */
 // Only include "first class" models, not OpenRouter or other proxy services
 const ALL = {
     BASE: [
@@ -236,6 +255,7 @@ var constants = /*#__PURE__*/Object.freeze({
     __proto__: null,
     ALL: ALL,
     DEFAULT: DEFAULT,
+    EFFORT: EFFORT,
     MODEL: MODEL,
     PROVIDER: PROVIDER
 });
@@ -243,7 +263,7 @@ var constants = /*#__PURE__*/Object.freeze({
 function determineModelProvider(input) {
     if (!input) {
         return {
-            model: DEFAULT.PROVIDER.MODEL.DEFAULT,
+            model: DEFAULT.PROVIDER.DEFAULT,
             provider: DEFAULT.PROVIDER.NAME,
         };
     }
@@ -266,85 +286,42 @@ function determineModelProvider(input) {
     // Check if input is a provider name
     if (input === PROVIDER.BEDROCK.NAME) {
         return {
-            model: PROVIDER.BEDROCK.MODEL.DEFAULT,
+            model: PROVIDER.BEDROCK.DEFAULT,
             provider: PROVIDER.BEDROCK.NAME,
         };
     }
     if (input === PROVIDER.ANTHROPIC.NAME) {
         return {
-            model: PROVIDER.ANTHROPIC.MODEL.DEFAULT,
+            model: PROVIDER.ANTHROPIC.DEFAULT,
             provider: PROVIDER.ANTHROPIC.NAME,
         };
     }
     if (input === PROVIDER.GOOGLE.NAME || input === "gemini") {
         return {
-            model: PROVIDER.GOOGLE.MODEL.DEFAULT,
+            model: PROVIDER.GOOGLE.DEFAULT,
             provider: PROVIDER.GOOGLE.NAME,
         };
     }
     if (input === PROVIDER.OPENAI.NAME) {
         return {
-            model: PROVIDER.OPENAI.MODEL.DEFAULT,
+            model: PROVIDER.OPENAI.DEFAULT,
             provider: PROVIDER.OPENAI.NAME,
         };
     }
     if (input === PROVIDER.OPENROUTER.NAME) {
         return {
-            model: PROVIDER.OPENROUTER.MODEL.DEFAULT,
+            model: PROVIDER.OPENROUTER.DEFAULT,
             provider: PROVIDER.OPENROUTER.NAME,
         };
     }
     if (input === PROVIDER.XAI.NAME) {
         return {
-            model: PROVIDER.XAI.MODEL.DEFAULT,
+            model: PROVIDER.XAI.DEFAULT,
             provider: PROVIDER.XAI.NAME,
         };
     }
-    // Check if input matches an Anthropic model exactly
-    for (const [, modelValue] of Object.entries(PROVIDER.ANTHROPIC.MODEL)) {
-        if (input === modelValue) {
-            return {
-                model: input,
-                provider: PROVIDER.ANTHROPIC.NAME,
-            };
-        }
-    }
-    // Check if input matches a Gemini model exactly
-    for (const [, modelValue] of Object.entries(PROVIDER.GOOGLE.MODEL)) {
-        if (input === modelValue) {
-            return {
-                model: input,
-                provider: PROVIDER.GOOGLE.NAME,
-            };
-        }
-    }
-    // Check if input matches an OpenAI model exactly
-    for (const [, modelValue] of Object.entries(PROVIDER.OPENAI.MODEL)) {
-        if (input === modelValue) {
-            return {
-                model: input,
-                provider: PROVIDER.OPENAI.NAME,
-            };
-        }
-    }
-    // Check if input matches an OpenRouter model exactly
-    for (const [, modelValue] of Object.entries(PROVIDER.OPENROUTER.MODEL)) {
-        if (input === modelValue) {
-            return {
-                model: input,
-                provider: PROVIDER.OPENROUTER.NAME,
-            };
-        }
-    }
-    // Check if input matches an xAI model exactly
-    for (const [, modelValue] of Object.entries(PROVIDER.XAI.MODEL)) {
-        if (input === modelValue) {
-            return {
-                model: input,
-                provider: PROVIDER.XAI.NAME,
-            };
-        }
-    }
+    // Exact model ids are classified by the "/" rule and MODEL_MATCH_WORDS below,
+    // so no per-provider id catalog is consulted here.
     // Assume OpenRouter for models containing "/" (e.g., "openai/gpt-4", "anthropic/claude-3-opus")
     // This check must come before match words so that "openai/gpt-4" is not matched by "openai" keyword
     if (input.includes("/")) {
@@ -424,6 +401,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 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 ConfigurationError(`Unable to determine provider from model: ${name}`);
+        }
+        return { model: determined.model, provider: determined.provider };
+    });
+    return { fallback, model: primary };
+}
+
 //
 //
 // Abstract Base Adapter
@@ -461,6 +468,125 @@ class BaseProviderAdapter {
     }
 }
 
+/**
+ * Per-provider translation of the provider-neutral {@link LlmEffort} scale.
+ *
+ * The neutral enum (lowest → low → medium → high → highest) is a relative
+ * five-point scale. Each table below maps it onto the target provider's native
+ * effort control, keeping `medium`/`high` semantically aligned across providers
+ * and using each provider's extra bottom (`minimal`) or top (`xhigh`/`max`)
+ * rung where one exists. Providers with fewer levels collapse the ends and mark
+ * the result `papered`. A single `effort` value is therefore safe to reuse
+ * across providers and fallback chains.
+ */
+/** Consistent debug message for a papered-over effort level. */
+function paperedEffortMessage({ model, provider, requested, value, }) {
+    return `[llm] effort '${requested}' has no distinct tier on ${provider} model '${model}'; using '${value}'`;
+}
+// OpenAI Responses API `reasoning.effort`.
+// Full ladder: minimal | low | medium | high | xhigh (plus `none`). Availability
+// is not uniform across the gpt-5 line:
+//   - `xhigh` was introduced at gpt-5.2 and has been continuous since, so it is
+//     safe for our gpt-5.4 default and everything newer.
+//   - `minimal` shipped on gpt-5/5.1, was dropped at gpt-5.2, and returned on
+//     the current line; because that history is non-monotonic we only trust it
+//     from gpt-5.4 (our default floor) onward.
+// Outside those windows (older gpt-5, o-series) the extreme rung is clamped and
+// the mapping reports `papered: true`.
+const OPENAI_EFFORT = {
+    [EFFORT.LOWEST]: "minimal",
+    [EFFORT.LOW]: "low",
+    [EFFORT.MEDIUM]: "medium",
+    [EFFORT.HIGH]: "high",
+    [EFFORT.HIGHEST]: "xhigh",
+};
+function openAiGptVersion(model) {
+    const match = model.match(/^gpt-(\d+)(?:\.(\d+))?/);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: match[2] ? Number(match[2]) : 0 };
+}
+function atLeast(version, major, minor) {
+    if (!version)
+        return false;
+    return (version.major > major || (version.major === major && version.minor >= minor));
+}
+function toOpenAiEffort(effort, { model }) {
+    const native = OPENAI_EFFORT[effort];
+    const version = openAiGptVersion(model);
+    // `minimal` only from gpt-5.4 (non-monotonic history; absent on o-series)
+    if (native === "minimal" && !atLeast(version, 5, 4)) {
+        return { papered: true, value: "low" };
+    }
+    // `xhigh` from gpt-5.2 onward (absent on older gpt-5 and o-series)
+    if (native === "xhigh" && !atLeast(version, 5, 2)) {
+        return { papered: true, value: "high" };
+    }
+    return { papered: false, value: native };
+}
+// xAI Grok `reasoning_effort` — low | medium | high. No sub-low or top rung, so
+// `lowest` collapses onto `low` and `highest` onto `high`.
+const XAI_EFFORT = {
+    [EFFORT.LOWEST]: { papered: true, value: "low" },
+    [EFFORT.LOW]: { papered: false, value: "low" },
+    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
+    [EFFORT.HIGH]: { papered: false, value: "high" },
+    [EFFORT.HIGHEST]: { papered: true, value: "high" },
+};
+function toXaiEffort(effort) {
+    return XAI_EFFORT[effort];
+}
+// Anthropic `output_config.effort` — low | medium | high | xhigh | max. No
+// sub-low rung, so `lowest` collapses onto `low`; `highest` reaches `max`.
+const ANTHROPIC_EFFORT = {
+    [EFFORT.LOWEST]: { papered: true, value: "low" },
+    [EFFORT.LOW]: { papered: false, value: "low" },
+    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
+    [EFFORT.HIGH]: { papered: false, value: "high" },
+    [EFFORT.HIGHEST]: { papered: false, value: "max" },
+};
+function toAnthropicEffort(effort) {
+    return ANTHROPIC_EFFORT[effort];
+}
+// Gemini 3.x `thinkingConfig.thinkingLevel` — MINIMAL | LOW | MEDIUM | HIGH. No
+// top rung above HIGH, so `highest` collapses onto HIGH.
+const GEMINI_THINKING_LEVEL = {
+    [EFFORT.LOWEST]: { papered: false, value: "MINIMAL" },
+    [EFFORT.LOW]: { papered: false, value: "LOW" },
+    [EFFORT.MEDIUM]: { papered: false, value: "MEDIUM" },
+    [EFFORT.HIGH]: { papered: false, value: "HIGH" },
+    [EFFORT.HIGHEST]: { papered: true, value: "HIGH" },
+};
+function toGeminiThinkingLevel(effort) {
+    return GEMINI_THINKING_LEVEL[effort];
+}
+// Gemini 2.5 `thinkingConfig.thinkingBudget` — every tier is a distinct token
+// budget, so nothing is papered over. Floor (512) clears every 2.5 minimum;
+// ceiling (24,576) is valid across 2.5 Pro (max 32,768) and Flash (max 24,576).
+const GEMINI_THINKING_BUDGET = {
+    [EFFORT.LOWEST]: 512,
+    [EFFORT.LOW]: 4096,
+    [EFFORT.MEDIUM]: 8192,
+    [EFFORT.HIGH]: 16384,
+    [EFFORT.HIGHEST]: 24576,
+};
+function toGeminiThinkingBudget(effort) {
+    return { papered: false, value: GEMINI_THINKING_BUDGET[effort] };
+}
+// OpenRouter `reasoning.effort` — accepts the full minimal..xhigh ladder and
+// maps to the routed provider's nearest supported level itself, so nothing is
+// papered here.
+const OPENROUTER_EFFORT = {
+    [EFFORT.LOWEST]: "minimal",
+    [EFFORT.LOW]: "low",
+    [EFFORT.MEDIUM]: "medium",
+    [EFFORT.HIGH]: "high",
+    [EFFORT.HIGHEST]: "xhigh",
+};
+function toOpenRouterEffort(effort) {
+    return { papered: false, value: OPENROUTER_EFFORT[effort] };
+}
+
 // Enums
 var LlmMessageRole;
 (function (LlmMessageRole) {
@@ -1394,8 +1520,14 @@ var ErrorCategory;
 (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 */
@@ -1486,11 +1618,120 @@ 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: ErrorCategory.Retryable, error, shouldRetry: true };
+        }
+    }
+    for (const pattern of BILLING_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return {
+                category: ErrorCategory.Quota,
+                error,
+                reason: "billing",
+                shouldRetry: false,
+            };
+        }
+    }
+    for (const pattern of QUOTA_MESSAGE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return {
+                category: ErrorCategory.Quota,
+                error,
+                reason: "quota",
+                shouldRetry: false,
+            };
+        }
+    }
+    return undefined;
+}
+
 //
 //
 // Constants
 //
 const STRUCTURED_OUTPUT_TOOL_NAME$3 = "structured_output";
+/**
+ * Whether `output_config.effort` may be sent for this model. Anthropic added
+ * the effort control on the Claude 4.5 line and up (the 5 family); older models
+ * reject it. Parsing major/minor avoids matching a minor "5" in legacy ids
+ * like `claude-3-5-sonnet`.
+ */
+function supportsAnthropicEffort(model) {
+    const match = model.match(/claude-[a-z]+-(\d+)(?:-(\d+))?/);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = match[2] !== undefined ? Number(match[2]) : 0;
+    if (major >= 5)
+        return true;
+    return major === 4 && minor >= 5;
+}
 const STRUCTURED_OUTPUT_NON_PARSE_STOP_REASONS = new Set([
     "refusal",
     "max_tokens",
@@ -1756,7 +1997,7 @@ class AnthropicAdapter extends BaseProviderAdapter {
     constructor() {
         super(...arguments);
         this.name = PROVIDER.ANTHROPIC.NAME;
-        this.defaultModel = PROVIDER.ANTHROPIC.MODEL.DEFAULT;
+        this.defaultModel = PROVIDER.ANTHROPIC.DEFAULT;
         // Session-level cache of models observed to reject `temperature` at runtime.
         // Populated by executeRequest on 400 errors so repeat calls skip the param.
         this.runtimeNoTemperatureModels = new Set();
@@ -1896,6 +2137,24 @@ class AnthropicAdapter extends BaseProviderAdapter {
         if (request.providerOptions) {
             Object.assign(anthropicRequest, request.providerOptions);
         }
+        // Normalized reasoning effort -> output_config.effort (merged so a format
+        // config above survives). First-class effort wins over providerOptions.
+        if (request.effort &&
+            supportsAnthropicEffort(anthropicRequest.model)) {
+            const mapping = toAnthropicEffort(request.effort);
+            if (mapping.papered) {
+                log$2.debug(paperedEffortMessage({
+                    model: anthropicRequest.model,
+                    provider: this.name,
+                    requested: request.effort,
+                    value: mapping.value,
+                }));
+            }
+            anthropicRequest.output_config = {
+                ...anthropicRequest.output_config,
+                effort: mapping.value,
+            };
+        }
         // First-class temperature takes precedence over providerOptions
         if (request.temperature !== undefined) {
             anthropicRequest.temperature = request.temperature;
@@ -1990,9 +2249,13 @@ class AnthropicAdapter extends BaseProviderAdapter {
      */
     toFallbackStructuredOutputRequest(request) {
         const { output_config, ...rest } = request;
-        if (!output_config)
+        if (!output_config?.format)
             return request;
         const fallbackRequest = { ...rest };
+        // Preserve an effort setting; only the structured-output format falls back.
+        if (output_config.effort) {
+            fallbackRequest.output_config = { effort: output_config.effort };
+        }
         const fakeTool = {
             name: STRUCTURED_OUTPUT_TOOL_NAME$3,
             description: "Output a structured JSON object, " +
@@ -2221,6 +2484,11 @@ 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") {
@@ -2436,7 +2704,7 @@ class BedrockAdapter extends BaseProviderAdapter {
     constructor() {
         super(...arguments);
         this.name = PROVIDER.BEDROCK.NAME;
-        this.defaultModel = PROVIDER.BEDROCK.MODEL.DEFAULT;
+        this.defaultModel = PROVIDER.BEDROCK.DEFAULT;
         this._modelsFallbackToStructuredOutputTool = new Set();
         this._modelsWithoutTemperature = new Set();
     }
@@ -2829,6 +3097,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" ||
@@ -2942,6 +3215,11 @@ const STRUCTURED_OUTPUT_TOOL_NAME$1 = "structured_output";
 // (including 2.5 thinking) do not support the combo and fall back to the
 // legacy `structured_output` fake-tool emulation.
 const GEMINI_3_PATTERN = /^gemini-3/;
+// Reasoning-effort control differs by generation: Gemini 3.x takes the
+// `thinkingLevel` enum, Gemini 2.5 takes an integer `thinkingBudget`. Sending
+// the wrong one errors, and models outside these families have no thinking
+// control, so effort is only applied when one of these matches.
+const GEMINI_25_PATTERN = /^gemini-2\.5/;
 /**
  * Detect 4xx errors that indicate the model itself does not support the
  * `responseJsonSchema` + tools combo. Triggers the runtime fallback to the
@@ -2988,7 +3266,7 @@ class GoogleAdapter extends BaseProviderAdapter {
     constructor() {
         super(...arguments);
         this.name = PROVIDER.GOOGLE.NAME;
-        this.defaultModel = PROVIDER.GOOGLE.MODEL.DEFAULT;
+        this.defaultModel = PROVIDER.GOOGLE.DEFAULT;
         // Session-level cache of Gemini 3 models observed to reject the native
         // `responseJsonSchema` + tools combo. When a model is in this set,
         // buildRequest engages the legacy fake-tool path instead.
@@ -3116,6 +3394,42 @@ class GoogleAdapter extends BaseProviderAdapter {
                 ...request.providerOptions,
             };
         }
+        // Normalized reasoning effort -> thinkingConfig. Gemini 3.x uses the
+        // thinkingLevel enum; 2.5 uses an integer thinkingBudget. Merged so a
+        // providerOptions.thinkingConfig survives; first-class effort wins.
+        if (request.effort) {
+            const model = geminiRequest.model;
+            let thinkingConfig;
+            let papered = false;
+            let value;
+            if (GEMINI_3_PATTERN.test(model)) {
+                const mapping = toGeminiThinkingLevel(request.effort);
+                ({ papered, value } = mapping);
+                thinkingConfig = { thinkingLevel: mapping.value };
+            }
+            else if (GEMINI_25_PATTERN.test(model)) {
+                const mapping = toGeminiThinkingBudget(request.effort);
+                ({ papered, value } = mapping);
+                thinkingConfig = { thinkingBudget: mapping.value };
+            }
+            if (thinkingConfig) {
+                if (papered) {
+                    log$2.debug(paperedEffortMessage({
+                        model,
+                        provider: this.name,
+                        requested: request.effort,
+                        value: value,
+                    }));
+                }
+                geminiRequest.config = {
+                    ...geminiRequest.config,
+                    thinkingConfig: {
+                        ...geminiRequest.config?.thinkingConfig,
+                        ...thinkingConfig,
+                    },
+                };
+            }
+        }
         // First-class temperature takes precedence over providerOptions
         if (request.temperature !== undefined) {
             geminiRequest.config = {
@@ -3457,6 +3771,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;
@@ -4035,7 +4354,7 @@ class OpenAiAdapter extends BaseProviderAdapter {
     constructor() {
         super(...arguments);
         this.name = PROVIDER.OPENAI.NAME;
-        this.defaultModel = PROVIDER.OPENAI.MODEL.DEFAULT;
+        this.defaultModel = PROVIDER.OPENAI.DEFAULT;
         // Session-level cache of models observed to reject `temperature` at runtime.
         // Populated by executeRequest on 400 errors so repeat calls skip the param.
         this.runtimeNoTemperatureModels = new Set();
@@ -4051,6 +4370,14 @@ class OpenAiAdapter extends BaseProviderAdapter {
             return false;
         return !MODELS_WITHOUT_TEMPERATURE$1.some((pattern) => pattern.test(model));
     }
+    /** Whether `reasoning.effort` may be sent for this model. Overridden by xAI. */
+    supportsReasoningEffort(model) {
+        return isReasoningModel(model);
+    }
+    /** Translate a normalized effort to this provider's `reasoning.effort` value. */
+    mapReasoningEffort(effort, model) {
+        return toOpenAiEffort(effort, { model });
+    }
     //
     // Request Building
     //
@@ -4089,6 +4416,24 @@ class OpenAiAdapter extends BaseProviderAdapter {
         if (request.providerOptions) {
             Object.assign(openaiRequest, request.providerOptions);
         }
+        // Normalized reasoning effort -> reasoning.effort (merged so the
+        // summary:auto above survives). First-class effort wins over providerOptions.
+        if (request.effort && this.supportsReasoningEffort(model)) {
+            const mapping = this.mapReasoningEffort(request.effort, model);
+            if (mapping.papered) {
+                log$2.debug(paperedEffortMessage({
+                    model,
+                    provider: this.name,
+                    requested: request.effort,
+                    value: mapping.value,
+                }));
+            }
+            const existingReasoning = openaiRequest.reasoning ?? {};
+            openaiRequest.reasoning = {
+                ...existingReasoning,
+                effort: mapping.value,
+            };
+        }
         // First-class temperature takes precedence over providerOptions
         if (request.temperature !== undefined) {
             openaiRequest.temperature = request.temperature;
@@ -4379,6 +4724,11 @@ 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 {
@@ -4683,7 +5033,7 @@ class OpenRouterAdapter extends BaseProviderAdapter {
     constructor() {
         super(...arguments);
         this.name = PROVIDER.OPENROUTER.NAME;
-        this.defaultModel = PROVIDER.OPENROUTER.MODEL.DEFAULT;
+        this.defaultModel = PROVIDER.OPENROUTER.DEFAULT;
         // Session-level cache of models observed to reject native
         // `response_format: json_schema`. When a model is in this set, buildRequest
         // engages the legacy fake-tool path instead of native structured output.
@@ -4776,6 +5126,15 @@ class OpenRouterAdapter extends BaseProviderAdapter {
         if (request.providerOptions) {
             Object.assign(openRouterRequest, request.providerOptions);
         }
+        // Normalized reasoning effort -> reasoning.effort. OpenRouter accepts the
+        // full ladder and maps to the routed provider's nearest supported level.
+        // First-class effort wins over providerOptions.
+        if (request.effort) {
+            openRouterRequest.reasoning = {
+                ...openRouterRequest.reasoning,
+                effort: toOpenRouterEffort(request.effort).value,
+            };
+        }
         // First-class temperature takes precedence over providerOptions
         if (request.temperature !== undefined) {
             openRouterRequest.temperature =
@@ -5138,6 +5497,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;
@@ -5394,8 +5758,21 @@ class XaiAdapter extends OpenAiAdapter {
         super(...arguments);
         // @ts-expect-error Narrowing override: xAI name differs from parent's literal "openai"
         this.name = PROVIDER.XAI.NAME;
-        // @ts-expect-error Narrowing override: xAI default model differs from parent's literal
-        this.defaultModel = PROVIDER.XAI.MODEL.DEFAULT;
+        this.defaultModel = PROVIDER.XAI.DEFAULT;
+    }
+    /**
+     * Grok gates reasoning effort by model, not by the OpenAI `gpt-*`/`o*`
+     * patterns. Only explicit `*-reasoning` models accept `reasoning_effort`;
+     * bare grok-4 reasons implicitly and rejects it, so we stay conservative and
+     * only opt in models whose name advertises reasoning.
+     */
+    supportsReasoningEffort(model) {
+        if (/non-reasoning/.test(model))
+            return false;
+        return /reasoning/.test(model);
+    }
+    mapReasoningEffort(effort) {
+        return toXaiEffort(effort);
     }
     classifyError(error) {
         if (isTransientIngestError(error)) {
@@ -6489,6 +6866,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 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, 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, 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, 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, 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 ErrorCategory.RateLimit:
+            return new LlmRateLimitError(message, options);
+        case ErrorCategory.Quota:
+            return new LlmQuotaError(message, {
+                ...options,
+                reason: classified.reason ?? "quota",
+            });
+        case ErrorCategory.Unrecoverable:
+            return new LlmUnrecoverableError(message, options);
+        case ErrorCategory.Retryable:
+        case ErrorCategory.Unknown:
+        default:
+            return new LlmTransientError(message, options);
+    }
+}
+
 //
 //
 // Main
@@ -6503,6 +6996,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
@@ -6546,8 +7051,7 @@ class RetryExecutor {
                             providerRequest: options.context.providerRequest,
                             error,
                         });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        throw new BadGatewayError(errorMessage);
+                        throw this.toTerminalError(error, options.context);
                     }
                     // Check if error is not retryable
                     if (!this.errorClassifier.isRetryable(error)) {
@@ -6559,8 +7063,7 @@ class RetryExecutor {
                             providerRequest: options.context.providerRequest,
                             error,
                         });
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        throw new BadGatewayError(errorMessage);
+                        throw this.toTerminalError(error, options.context);
                     }
                     // Warn if this is an unknown error type
                     if (!this.errorClassifier.isKnownError(error)) {
@@ -6603,6 +7106,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);
@@ -6672,6 +7176,7 @@ class OperateLoop {
                 }
                 // Rebuild request with updated history for next turn
                 request = {
+                    effort: options.effort,
                     format: state.formattedFormat,
                     instructions: options.instructions,
                     messages: state.currentInput,
@@ -6775,6 +7280,7 @@ class OperateLoop {
     }
     buildInitialRequest(state, options) {
         return {
+            effort: options.effort,
             format: state.formattedFormat,
             instructions: options.instructions,
             messages: state.currentInput,
@@ -6854,7 +7360,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,
@@ -7289,6 +7797,7 @@ class StreamLoop {
                 }
                 // Rebuild request with updated history for next turn
                 request = {
+                    effort: options.effort,
                     format: state.formattedFormat,
                     instructions: options.instructions,
                     messages: state.currentInput,
@@ -7364,6 +7873,7 @@ class StreamLoop {
     }
     buildInitialRequest(state, options) {
         return {
+            effort: options.effort,
             format: state.formattedFormat,
             instructions: options.instructions,
             messages: state.currentInput,
@@ -7475,9 +7985,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 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...`);
@@ -7927,7 +8439,7 @@ async function createStructuredCompletion$1(client, messages, model, responseSch
 
 // Main class implementation
 class AnthropicProvider {
-    constructor(model = PROVIDER.ANTHROPIC.MODEL.DEFAULT, { apiKey } = {}) {
+    constructor(model = PROVIDER.ANTHROPIC.DEFAULT, { apiKey } = {}) {
         this.log = getLogger$5();
         this.conversationHistory = [];
         this.model = model;
@@ -8035,7 +8547,7 @@ async function initializeClient$4({ region, } = {}) {
 }
 
 class BedrockProvider {
-    constructor(model = PROVIDER.BEDROCK.MODEL.DEFAULT, { region } = {}) {
+    constructor(model = PROVIDER.BEDROCK.DEFAULT, { region } = {}) {
         this.log = getLogger$4();
         this.conversationHistory = [];
         this.model = model;
@@ -8278,7 +8790,7 @@ function prepareMessages$2(message, { data, placeholders } = {}) {
 }
 
 class GoogleProvider {
-    constructor(model = PROVIDER.GOOGLE.MODEL.DEFAULT, { apiKey } = {}) {
+    constructor(model = PROVIDER.GOOGLE.DEFAULT, { apiKey } = {}) {
         this.log = getLogger$3();
         this.conversationHistory = [];
         this.model = model;
@@ -8480,7 +8992,7 @@ async function createTextCompletion(client, { messages, model, }) {
 }
 
 class OpenAiProvider {
-    constructor(model = PROVIDER.OPENAI.MODEL.DEFAULT, { apiKey } = {}) {
+    constructor(model = PROVIDER.OPENAI.DEFAULT, { apiKey } = {}) {
         this.log = getLogger$2();
         this.conversationHistory = [];
         this.model = model;
@@ -8711,7 +9223,7 @@ async function initializeClient$1({ apiKey, } = {}) {
 }
 // Get default model from environment or constants
 function getDefaultModel() {
-    return process.env.OPENROUTER_MODEL || PROVIDER.OPENROUTER.MODEL.DEFAULT;
+    return process.env.OPENROUTER_MODEL || PROVIDER.OPENROUTER.DEFAULT;
 }
 function formatSystemMessage(systemPrompt, { data, placeholders: placeholders$1 } = {}) {
     const content = placeholders$1?.system === false
@@ -8863,7 +9375,7 @@ async function initializeClient({ apiKey, } = {}) {
 }
 
 class XaiProvider {
-    constructor(model = PROVIDER.XAI.MODEL.DEFAULT, { apiKey } = {}) {
+    constructor(model = PROVIDER.XAI.DEFAULT, { apiKey } = {}) {
         this.log = getLogger$2();
         this.conversationHistory = [];
         this.model = model;
@@ -8948,7 +9460,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
@@ -8994,23 +9513,25 @@ class Llm {
         const { apiKey, model } = options;
         switch (providerName) {
             case PROVIDER.ANTHROPIC.NAME:
-                return new AnthropicProvider(model || PROVIDER.ANTHROPIC.MODEL.DEFAULT, { apiKey });
+                return new AnthropicProvider(model || PROVIDER.ANTHROPIC.DEFAULT, {
+                    apiKey,
+                });
             case PROVIDER.BEDROCK.NAME:
-                return new BedrockProvider(model || PROVIDER.BEDROCK.MODEL.DEFAULT);
+                return new BedrockProvider(model || PROVIDER.BEDROCK.DEFAULT);
             case PROVIDER.GOOGLE.NAME:
-                return new GoogleProvider(model || PROVIDER.GOOGLE.MODEL.DEFAULT, {
+                return new GoogleProvider(model || PROVIDER.GOOGLE.DEFAULT, {
                     apiKey,
                 });
             case PROVIDER.OPENAI.NAME:
-                return new OpenAiProvider(model || PROVIDER.OPENAI.MODEL.DEFAULT, {
+                return new OpenAiProvider(model || PROVIDER.OPENAI.DEFAULT, {
                     apiKey,
                 });
             case PROVIDER.OPENROUTER.NAME:
-                return new OpenRouterProvider(model || PROVIDER.OPENROUTER.MODEL.DEFAULT, {
+                return new OpenRouterProvider(model || PROVIDER.OPENROUTER.DEFAULT, {
                     apiKey,
                 });
             case PROVIDER.XAI.NAME:
-                return new XaiProvider(model || PROVIDER.XAI.MODEL.DEFAULT, {
+                return new XaiProvider(model || PROVIDER.XAI.DEFAULT, {
                     apiKey,
                 });
             default:
@@ -9018,6 +9539,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);
     }
     /**
@@ -9050,8 +9576,21 @@ class Llm {
         if (!this._llm.operate) {
             throw new 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
@@ -9100,33 +9639,45 @@ class Llm {
         if (!this._llm.stream) {
             throw new 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,
@@ -9140,23 +9691,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);
     }
 }
@@ -9454,5 +10011,5 @@ const toolkit = new JaypieToolkit(tools);
     [LlmMessageRole.Developer]: "user",
 });
 
-export { BedrockProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmStreamChunkType, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
+export { BedrockProvider, ErrorCategory, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmError, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmQuotaError, LlmRateLimitError, LlmStreamChunkType, LlmTransientError, LlmUnrecoverableError, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
 //# sourceMappingURL=index.js.map