@jaypie/llm 1.3.10 → 1.3.11

package/dist/cjs/index.d.cts

@@ -1,6 +1,7 @@
 import * as _jaypie_types from '@jaypie/types';
 import { JsonObject, AnyValue, NaturalMap, NaturalSchema, JsonReturn } from '@jaypie/types';
 import { z } from 'zod/v4';
+import { JaypieError } from '@jaypie/errors';
 
 /**
  * Provider-neutral reasoning-effort levels — a five-point relative scale that
@@ -324,7 +325,7 @@ declare enum LlmResponseStatus {
     Incomplete = "incomplete",
     InProgress = "in_progress"
 }
-interface LlmError {
+interface LlmError$1 {
     detail?: string;
     status: number | string;
     title: string;
@@ -593,6 +594,15 @@ interface LlmOperateOptions {
     turns?: boolean | number;
     user?: string;
 }
+/**
+ * A single model name, or a preference-ordered array of model names.
+ * An array is interpreted as a fallback chain: index 0 is primary, later
+ * entries are tried in order when earlier ones fail (provider auto-detected
+ * per entry). Accepted by the `Llm` constructor and static/instance
+ * `operate`/`send`/`stream` methods; normalized to a scalar model plus a
+ * derived fallback chain before reaching providers.
+ */
+type LlmModelOption = string | string[];
 interface LlmOptions {
     apiKey?: string;
     /** Chain of fallback providers to try if primary fails */
@@ -610,7 +620,7 @@ interface LlmUsageItem {
 type LlmUsage = LlmUsageItem[];
 interface LlmOperateResponse {
     content?: string | JsonObject;
-    error?: LlmError;
+    error?: LlmError$1;
     /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
     fallbackAttempts?: number;
     /** Whether a fallback provider was used instead of the primary */
@@ -636,9 +646,13 @@ declare class Llm implements LlmProvider {
     private _llm;
     private _options;
     private _provider;
-    constructor(providerName?: LlmProviderName | string, options?: LlmOptions);
+    constructor(providerName?: LlmProviderName | string, options?: Omit<LlmOptions, "model"> & {
+        model?: LlmModelOption;
+    });
     private createProvider;
-    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<string | JsonObject>;
     /**
      * Resolves the fallback chain from instance config and per-call options.
      * Per-call options take precedence over instance config.
@@ -649,23 +663,27 @@ declare class Llm implements LlmProvider {
      * Creates a fallback Llm instance lazily when needed.
      */
     private createFallbackInstance;
-    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
-    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
-    static send(message: string, options?: LlmMessageOptions & {
+    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<LlmOperateResponse>;
+    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): AsyncIterable<LlmStreamChunk>;
+    static send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): Promise<string | JsonObject>;
-    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         apiKey?: string;
         fallback?: LlmFallbackConfig[] | false;
         llm?: LlmProviderName;
-        model?: string;
+        model?: string | string[];
     }): Promise<LlmOperateResponse>;
-    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): AsyncIterable<LlmStreamChunk>;
 }
 
@@ -696,6 +714,87 @@ declare class JaypieToolkit extends Toolkit {
 }
 declare const toolkit: JaypieToolkit;
 
+/**
+ * Categories of errors for retry logic
+ */
+declare enum ErrorCategory {
+    /** Error is transient and can be retried */
+    Retryable = "retryable",
+    /** Error is due to short-term rate limiting (retry after a delay) */
+    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.
+     */
+    Quota = "quota",
+    /** Error cannot be recovered from */
+    Unrecoverable = "unrecoverable",
+    /** Error type is unknown */
+    Unknown = "unknown"
+}
+
+interface LlmErrorOptions {
+    /** Provider name that produced the error (e.g. "anthropic", "google") */
+    provider?: string;
+    /** Model in use when the error occurred */
+    model?: string;
+    /** Milliseconds to wait before retrying, when the provider suggests one */
+    retryAfterMs?: number;
+    /** The original provider error, preserved for inspection */
+    cause?: unknown;
+}
+/**
+ * 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`.
+ */
+declare class LlmError extends JaypieError {
+    readonly category: ErrorCategory;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
+    constructor(message: string, category: ErrorCategory, { status, title, provider, model, retryAfterMs, cause, }?: LlmErrorOptions & {
+        status?: number;
+        title?: string;
+    });
+}
+/**
+ * Short-term rate limiting (per-minute 429). Terminal within the request
+ * budget; `retryAfterMs` carries the provider's suggested wait when available.
+ */
+declare class LlmRateLimitError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * Provider quota is exhausted or the account cannot be billed. Terminal and
+ * actionable. `reason` distinguishes an exhausted usage quota from insufficient
+ * funds.
+ */
+declare class LlmQuotaError extends LlmError {
+    readonly reason: "quota" | "billing";
+    constructor(message: string, { reason, ...options }?: LlmErrorOptions & {
+        reason?: "quota" | "billing";
+    });
+}
+/**
+ * The request cannot be recovered from (bad request, authentication,
+ * permission, not found). Terminal.
+ */
+declare class LlmUnrecoverableError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * A transient or unknown error survived the retry budget. Terminal only because
+ * retries were exhausted; the underlying condition may succeed later.
+ */
+declare class LlmTransientError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+
 /**
  * Extracts reasoning text from LLM history items.
  *
@@ -798,5 +897,5 @@ declare class XaiProvider implements LlmProvider {
     stream(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
 }
 
-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 type { LlmEffort, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+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 };
+export type { LlmEffort, LlmErrorOptions, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };

package/dist/cjs/index.d.ts

@@ -1,13 +1,16 @@
 export { default as Llm } from "./Llm.js";
 export * as LLM from "./constants.js";
 export type { LlmEffort } from "./constants.js";
-export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, } from "./types/LlmProvider.interface.js";
+export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, } from "./types/LlmProvider.interface.js";
 export { LlmMessageRole, LlmMessageType, LlmProgressEventType, } from "./types/LlmProvider.interface.js";
 export { isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, } from "./types/LlmOperateInput.guards.js";
 export type { LlmTool } from "./types/LlmTool.interface.js";
 export type { LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, } from "./types/LlmStreamChunk.interface.js";
 export { LlmStreamChunkType } from "./types/LlmStreamChunk.interface.js";
 export { JaypieToolkit, toolkit, Toolkit, tools } from "./tools/index.js";
+export { LlmError, LlmQuotaError, LlmRateLimitError, LlmTransientError, LlmUnrecoverableError, } from "./errors/LlmError.js";
+export type { LlmErrorOptions } from "./errors/LlmError.js";
+export { ErrorCategory } from "./operate/types.js";
 export { extractReasoning } from "./util/extractReasoning.js";
 export { jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, } from "./util/jsonSchema.js";
 export { BedrockProvider } from "./providers/bedrock/index.js";

package/dist/cjs/operate/retry/RetryExecutor.d.ts

@@ -1,13 +1,20 @@
 import { HookRunner, LlmHooks } from "../hooks/HookRunner.js";
 import { RetryPolicy } from "./RetryPolicy.js";
+import { ClassifiedError } from "../types.js";
 export interface RetryContext {
     input: unknown;
     options?: unknown;
     providerRequest: unknown;
+    /** Provider name, carried onto the thrown LlmError */
+    provider?: string;
+    /** Model in use, carried onto the thrown LlmError */
+    model?: string;
 }
 export interface ErrorClassifier {
     isRetryable(error: unknown): boolean;
     isKnownError(error: unknown): boolean;
+    /** Full classification, used to throw a typed LlmError on terminal failure */
+    classify(error: unknown): ClassifiedError;
 }
 export interface RetryExecutorConfig {
     errorClassifier: ErrorClassifier;
@@ -27,6 +34,12 @@ export declare class RetryExecutor {
     private readonly hookRunner;
     private readonly errorClassifier;
     constructor(config: RetryExecutorConfig);
+    /**
+     * 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`.
+     */
+    private toTerminalError;
     /**
      * Execute an operation with retry logic.
      * Each attempt receives an AbortSignal. On failure, the signal is aborted

package/dist/cjs/operate/types.d.ts

@@ -97,8 +97,14 @@ export interface ProviderToolDefinition {
 export declare enum ErrorCategory {
     /** Error is transient and can be retried */
     Retryable = "retryable",
-    /** Error is due to rate limiting */
+    /** Error is due to short-term rate limiting (retry after a delay) */
     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.
+     */
+    Quota = "quota",
     /** Error cannot be recovered from */
     Unrecoverable = "unrecoverable",
     /** Error type is unknown */
@@ -116,6 +122,11 @@ export interface ClassifiedError {
     shouldRetry: boolean;
     /** Suggested delay before retry (if applicable) */
     suggestedDelayMs?: number;
+    /**
+     * For {@link ErrorCategory.Quota}, distinguishes an exhausted usage quota
+     * from an account that cannot be billed (insufficient funds).
+     */
+    reason?: "quota" | "billing";
 }
 import type { ResponseBuilder } from "./response/ResponseBuilder.js";
 /**

package/dist/cjs/types/LlmProvider.interface.d.ts

@@ -295,6 +295,15 @@ export interface LlmOperateOptions {
     turns?: boolean | number;
     user?: string;
 }
+/**
+ * A single model name, or a preference-ordered array of model names.
+ * An array is interpreted as a fallback chain: index 0 is primary, later
+ * entries are tried in order when earlier ones fail (provider auto-detected
+ * per entry). Accepted by the `Llm` constructor and static/instance
+ * `operate`/`send`/`stream` methods; normalized to a scalar model plus a
+ * derived fallback chain before reaching providers.
+ */
+export type LlmModelOption = string | string[];
 export interface LlmOptions {
     apiKey?: string;
     /** Chain of fallback providers to try if primary fails */

package/dist/cjs/util/classifyProviderError.d.ts

@@ -0,0 +1,13 @@
+import { ClassifiedError } from "../operate/types.js";
+/**
+ * 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}.
+ */
+export declare function classifyProviderError(error: unknown): ClassifiedError | undefined;

package/dist/cjs/util/resolveModelChain.d.ts

@@ -0,0 +1,17 @@
+import { LlmFallbackConfig } from "../types/LlmProvider.interface.js";
+/**
+ * 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.
+ */
+export declare function resolveModelChain(model?: string | string[]): {
+    model?: string;
+    fallback: LlmFallbackConfig[];
+};

package/dist/esm/Llm.d.ts

@@ -1,15 +1,19 @@
 import { JsonObject } from "@jaypie/types";
 import { LlmProviderName } from "./constants.js";
-import { LlmFallbackConfig, LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider } from "./types/LlmProvider.interface.js";
+import { LlmFallbackConfig, LlmHistory, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider } from "./types/LlmProvider.interface.js";
 import { LlmStreamChunk } from "./types/LlmStreamChunk.interface.js";
 declare class Llm implements LlmProvider {
     private _fallbackConfig?;
     private _llm;
     private _options;
     private _provider;
-    constructor(providerName?: LlmProviderName | string, options?: LlmOptions);
+    constructor(providerName?: LlmProviderName | string, options?: Omit<LlmOptions, "model"> & {
+        model?: LlmModelOption;
+    });
     private createProvider;
-    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<string | JsonObject>;
     /**
      * Resolves the fallback chain from instance config and per-call options.
      * Per-call options take precedence over instance config.
@@ -20,23 +24,27 @@ declare class Llm implements LlmProvider {
      * Creates a fallback Llm instance lazily when needed.
      */
     private createFallbackInstance;
-    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
-    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
-    static send(message: string, options?: LlmMessageOptions & {
+    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<LlmOperateResponse>;
+    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): AsyncIterable<LlmStreamChunk>;
+    static send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): Promise<string | JsonObject>;
-    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         apiKey?: string;
         fallback?: LlmFallbackConfig[] | false;
         llm?: LlmProviderName;
-        model?: string;
+        model?: string | string[];
     }): Promise<LlmOperateResponse>;
-    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): AsyncIterable<LlmStreamChunk>;
 }
 export default Llm;

package/dist/esm/errors/LlmError.d.ts

@@ -0,0 +1,62 @@
+import { JaypieError } from "@jaypie/errors";
+import { ErrorCategory } from "../operate/types.js";
+export interface LlmErrorOptions {
+    /** Provider name that produced the error (e.g. "anthropic", "google") */
+    provider?: string;
+    /** Model in use when the error occurred */
+    model?: string;
+    /** Milliseconds to wait before retrying, when the provider suggests one */
+    retryAfterMs?: number;
+    /** The original provider error, preserved for inspection */
+    cause?: unknown;
+}
+/**
+ * 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`.
+ */
+export declare class LlmError extends JaypieError {
+    readonly category: ErrorCategory;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
+    constructor(message: string, category: ErrorCategory, { status, title, provider, model, retryAfterMs, cause, }?: LlmErrorOptions & {
+        status?: number;
+        title?: string;
+    });
+}
+/**
+ * Short-term rate limiting (per-minute 429). Terminal within the request
+ * budget; `retryAfterMs` carries the provider's suggested wait when available.
+ */
+export declare class LlmRateLimitError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * Provider quota is exhausted or the account cannot be billed. Terminal and
+ * actionable. `reason` distinguishes an exhausted usage quota from insufficient
+ * funds.
+ */
+export declare class LlmQuotaError extends LlmError {
+    readonly reason: "quota" | "billing";
+    constructor(message: string, { reason, ...options }?: LlmErrorOptions & {
+        reason?: "quota" | "billing";
+    });
+}
+/**
+ * The request cannot be recovered from (bad request, authentication,
+ * permission, not found). Terminal.
+ */
+export declare class LlmUnrecoverableError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * A transient or unknown error survived the retry budget. Terminal only because
+ * retries were exhausted; the underlying condition may succeed later.
+ */
+export declare class LlmTransientError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}

package/dist/esm/errors/toLlmError.d.ts

@@ -0,0 +1,11 @@
+import { ClassifiedError } from "../operate/types.js";
+import { LlmError } from "./LlmError.js";
+/**
+ * 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.
+ */
+export declare function toLlmError(classified: ClassifiedError, context?: {
+    provider?: string;
+    model?: string;
+}): LlmError;

package/dist/esm/index.d.ts

@@ -1,6 +1,7 @@
 import * as _jaypie_types from '@jaypie/types';
 import { JsonObject, AnyValue, NaturalMap, NaturalSchema, JsonReturn } from '@jaypie/types';
 import { z } from 'zod/v4';
+import { JaypieError } from '@jaypie/errors';
 
 /**
  * Provider-neutral reasoning-effort levels — a five-point relative scale that
@@ -324,7 +325,7 @@ declare enum LlmResponseStatus {
     Incomplete = "incomplete",
     InProgress = "in_progress"
 }
-interface LlmError {
+interface LlmError$1 {
     detail?: string;
     status: number | string;
     title: string;
@@ -593,6 +594,15 @@ interface LlmOperateOptions {
     turns?: boolean | number;
     user?: string;
 }
+/**
+ * A single model name, or a preference-ordered array of model names.
+ * An array is interpreted as a fallback chain: index 0 is primary, later
+ * entries are tried in order when earlier ones fail (provider auto-detected
+ * per entry). Accepted by the `Llm` constructor and static/instance
+ * `operate`/`send`/`stream` methods; normalized to a scalar model plus a
+ * derived fallback chain before reaching providers.
+ */
+type LlmModelOption = string | string[];
 interface LlmOptions {
     apiKey?: string;
     /** Chain of fallback providers to try if primary fails */
@@ -610,7 +620,7 @@ interface LlmUsageItem {
 type LlmUsage = LlmUsageItem[];
 interface LlmOperateResponse {
     content?: string | JsonObject;
-    error?: LlmError;
+    error?: LlmError$1;
     /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
     fallbackAttempts?: number;
     /** Whether a fallback provider was used instead of the primary */
@@ -636,9 +646,13 @@ declare class Llm implements LlmProvider {
     private _llm;
     private _options;
     private _provider;
-    constructor(providerName?: LlmProviderName | string, options?: LlmOptions);
+    constructor(providerName?: LlmProviderName | string, options?: Omit<LlmOptions, "model"> & {
+        model?: LlmModelOption;
+    });
     private createProvider;
-    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<string | JsonObject>;
     /**
      * Resolves the fallback chain from instance config and per-call options.
      * Per-call options take precedence over instance config.
@@ -649,23 +663,27 @@ declare class Llm implements LlmProvider {
      * Creates a fallback Llm instance lazily when needed.
      */
     private createFallbackInstance;
-    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
-    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
-    static send(message: string, options?: LlmMessageOptions & {
+    operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): Promise<LlmOperateResponse>;
+    stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
+        model?: LlmModelOption;
+    }): AsyncIterable<LlmStreamChunk>;
+    static send(message: string, options?: Omit<LlmMessageOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): Promise<string | JsonObject>;
-    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         apiKey?: string;
         fallback?: LlmFallbackConfig[] | false;
         llm?: LlmProviderName;
-        model?: string;
+        model?: string | string[];
     }): Promise<LlmOperateResponse>;
-    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: LlmOperateOptions & {
+    static stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         llm?: LlmProviderName;
         apiKey?: string;
-        model?: string;
+        model?: string | string[];
     }): AsyncIterable<LlmStreamChunk>;
 }
 
@@ -696,6 +714,87 @@ declare class JaypieToolkit extends Toolkit {
 }
 declare const toolkit: JaypieToolkit;
 
+/**
+ * Categories of errors for retry logic
+ */
+declare enum ErrorCategory {
+    /** Error is transient and can be retried */
+    Retryable = "retryable",
+    /** Error is due to short-term rate limiting (retry after a delay) */
+    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.
+     */
+    Quota = "quota",
+    /** Error cannot be recovered from */
+    Unrecoverable = "unrecoverable",
+    /** Error type is unknown */
+    Unknown = "unknown"
+}
+
+interface LlmErrorOptions {
+    /** Provider name that produced the error (e.g. "anthropic", "google") */
+    provider?: string;
+    /** Model in use when the error occurred */
+    model?: string;
+    /** Milliseconds to wait before retrying, when the provider suggests one */
+    retryAfterMs?: number;
+    /** The original provider error, preserved for inspection */
+    cause?: unknown;
+}
+/**
+ * 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`.
+ */
+declare class LlmError extends JaypieError {
+    readonly category: ErrorCategory;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
+    constructor(message: string, category: ErrorCategory, { status, title, provider, model, retryAfterMs, cause, }?: LlmErrorOptions & {
+        status?: number;
+        title?: string;
+    });
+}
+/**
+ * Short-term rate limiting (per-minute 429). Terminal within the request
+ * budget; `retryAfterMs` carries the provider's suggested wait when available.
+ */
+declare class LlmRateLimitError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * Provider quota is exhausted or the account cannot be billed. Terminal and
+ * actionable. `reason` distinguishes an exhausted usage quota from insufficient
+ * funds.
+ */
+declare class LlmQuotaError extends LlmError {
+    readonly reason: "quota" | "billing";
+    constructor(message: string, { reason, ...options }?: LlmErrorOptions & {
+        reason?: "quota" | "billing";
+    });
+}
+/**
+ * The request cannot be recovered from (bad request, authentication,
+ * permission, not found). Terminal.
+ */
+declare class LlmUnrecoverableError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+/**
+ * A transient or unknown error survived the retry budget. Terminal only because
+ * retries were exhausted; the underlying condition may succeed later.
+ */
+declare class LlmTransientError extends LlmError {
+    constructor(message: string, options?: LlmErrorOptions);
+}
+
 /**
  * Extracts reasoning text from LLM history items.
  *
@@ -798,5 +897,5 @@ declare class XaiProvider implements LlmProvider {
     stream(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
 }
 
-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 type { LlmEffort, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+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 };
+export type { LlmEffort, LlmErrorOptions, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };