opencode-puter-auth 1.0.38 → 1.0.41

package/dist/account-rotation.js

@@ -0,0 +1,431 @@
+/**
+ * Account Rotation Manager for opencode-puter-auth
+ *
+ * Provides automatic account rotation when rate limits are encountered.
+ * When an account returns a rate limit error (429/403), the manager:
+ * 1. Adds the account to a cooldown list
+ * 2. Switches to the next available account
+ * 3. Returns to the original account after cooldown expires
+ *
+ * This enables longer uninterrupted usage by cycling through multiple
+ * Puter accounts when individual accounts hit rate limits.
+ *
+ * @example
+ * ```ts
+ * const rotation = new AccountRotationManager(authManager, {
+ *   cooldownMs: 300000, // 5 minutes
+ *   enabled: true,
+ * });
+ *
+ * // Get the next available account (respecting cooldowns)
+ * const account = await rotation.getNextAvailableAccount();
+ *
+ * // Mark an account as rate-limited
+ * rotation.addToCooldown('mihai_chindris', 'Rate limit exceeded');
+ * ```
+ */
+/**
+ * Default cooldown duration for rate-limited accounts (5 minutes)
+ * Accounts typically need longer cooldown than models since Puter's
+ * account-level limits are stricter.
+ */
+export const DEFAULT_ACCOUNT_COOLDOWN_MS = 300000;
+/**
+ * Error thrown when all accounts are on cooldown
+ */
+export class AllAccountsOnCooldownError extends Error {
+    accountStatuses;
+    nextAvailableIn;
+    constructor(statuses) {
+        const usernames = statuses.map(s => s.username).join(', ');
+        const nextAvailable = Math.min(...statuses.map(s => s.cooldownRemainingMs));
+        super(`All accounts on cooldown: ${usernames}. Next available in ${Math.round(nextAvailable / 1000)}s`);
+        this.name = 'AllAccountsOnCooldownError';
+        this.accountStatuses = statuses;
+        this.nextAvailableIn = nextAvailable;
+    }
+}
+/**
+ * Manages automatic account rotation when rate limits are encountered.
+ *
+ * Works with PuterAuthManager to cycle through multiple accounts,
+ * ensuring uninterrupted service even when individual accounts
+ * hit their rate limits.
+ */
+export class AccountRotationManager {
+    authManager;
+    cooldownMap = new Map();
+    usageStats = new Map();
+    cooldownMs;
+    enabled;
+    strategy;
+    currentIndex = 0;
+    logger;
+    /**
+     * Create a new AccountRotationManager
+     *
+     * @param authManager - The PuterAuthManager instance
+     * @param options - Configuration options
+     * @param logger - Optional logger for debugging
+     */
+    constructor(authManager, options = {}, logger) {
+        this.authManager = authManager;
+        this.cooldownMs = options.cooldownMs ?? DEFAULT_ACCOUNT_COOLDOWN_MS;
+        this.enabled = options.enabled ?? true;
+        this.strategy = options.strategy ?? 'round-robin';
+        this.logger = logger;
+    }
+    /**
+     * Check if an account is currently on cooldown
+     *
+     * @param username - Account username to check
+     * @returns true if the account is on cooldown
+     */
+    isAccountOnCooldown(username) {
+        const entry = this.cooldownMap.get(username);
+        if (!entry)
+            return false;
+        if (Date.now() >= entry.expiresAt) {
+            this.cooldownMap.delete(username);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get remaining cooldown time for an account
+     *
+     * @param username - Account username to check
+     * @returns Remaining cooldown in ms, or 0 if not on cooldown
+     */
+    getCooldownRemaining(username) {
+        const entry = this.cooldownMap.get(username);
+        if (!entry)
+            return 0;
+        const remaining = entry.expiresAt - Date.now();
+        if (remaining <= 0) {
+            this.cooldownMap.delete(username);
+            return 0;
+        }
+        return remaining;
+    }
+    /**
+     * Add an account to the cooldown list
+     *
+     * Each consecutive rate limit increases the cooldown duration
+     * exponentially (up to 4x base cooldown).
+     *
+     * @param username - Account username to add to cooldown
+     * @param reason - Reason for the cooldown
+     */
+    addToCooldown(username, reason) {
+        const existing = this.cooldownMap.get(username);
+        const consecutiveRateLimits = (existing?.consecutiveRateLimits ?? 0) + 1;
+        // Exponential backoff: 1x, 2x, 3x, 4x (max)
+        const multiplier = Math.min(consecutiveRateLimits, 4);
+        const duration = this.cooldownMs * multiplier;
+        this.cooldownMap.set(username, {
+            expiresAt: Date.now() + duration,
+            reason,
+            consecutiveRateLimits,
+        });
+        // Update stats
+        const stats = this.usageStats.get(username) ?? { lastUsedAt: 0, rateLimitCount: 0 };
+        stats.rateLimitCount++;
+        this.usageStats.set(username, stats);
+        const durationSecs = Math.round(duration / 1000);
+        this.logger?.warn(`Account ${username} cooldown: ${durationSecs}s (${consecutiveRateLimits}x)`);
+    }
+    /**
+     * Remove an account from cooldown (e.g., after successful request)
+     *
+     * @param username - Account username to remove from cooldown
+     */
+    removeFromCooldown(username) {
+        if (this.cooldownMap.has(username)) {
+            this.cooldownMap.delete(username);
+            this.logger?.debug(`Account ${username} removed from cooldown`);
+        }
+    }
+    /**
+     * Mark an account as recently used
+     *
+     * @param username - Account username that was used
+     */
+    markAsUsed(username) {
+        const stats = this.usageStats.get(username) ?? { lastUsedAt: 0, rateLimitCount: 0 };
+        stats.lastUsedAt = Date.now();
+        this.usageStats.set(username, stats);
+    }
+    /**
+     * Get status of all accounts
+     *
+     * @returns Array of account statuses
+     */
+    getAccountStatuses() {
+        const accounts = this.authManager.getAllAccounts();
+        return accounts.map(account => {
+            const cooldownRemaining = this.getCooldownRemaining(account.username);
+            const entry = this.cooldownMap.get(account.username);
+            const stats = this.usageStats.get(account.username);
+            return {
+                username: account.username,
+                isOnCooldown: cooldownRemaining > 0,
+                cooldownRemainingMs: cooldownRemaining,
+                cooldownReason: entry?.reason,
+                lastUsedAt: stats?.lastUsedAt ?? account.lastUsed,
+                rateLimitCount: stats?.rateLimitCount ?? 0,
+            };
+        });
+    }
+    /**
+     * Get list of available accounts (not on cooldown)
+     *
+     * @returns Array of available accounts
+     */
+    getAvailableAccounts() {
+        return this.authManager.getAllAccounts().filter(account => !this.isAccountOnCooldown(account.username));
+    }
+    /**
+     * Get count of accounts currently on cooldown
+     *
+     * @returns Number of accounts on cooldown
+     */
+    getAccountsOnCooldownCount() {
+        const accounts = this.authManager.getAllAccounts();
+        return accounts.filter(a => this.isAccountOnCooldown(a.username)).length;
+    }
+    /**
+     * Select the next account to use based on strategy
+     *
+     * @param availableAccounts - List of available accounts
+     * @returns The selected account
+     */
+    selectNextAccount(availableAccounts) {
+        if (availableAccounts.length === 0) {
+            throw new Error('No available accounts');
+        }
+        if (availableAccounts.length === 1) {
+            return availableAccounts[0];
+        }
+        switch (this.strategy) {
+            case 'least-recently-used': {
+                // Find the account with the oldest lastUsedAt
+                let oldest = availableAccounts[0];
+                let oldestTime = this.usageStats.get(oldest.username)?.lastUsedAt ?? oldest.lastUsed ?? 0;
+                for (const account of availableAccounts) {
+                    const lastUsed = this.usageStats.get(account.username)?.lastUsedAt ?? account.lastUsed ?? 0;
+                    if (lastUsed < oldestTime) {
+                        oldest = account;
+                        oldestTime = lastUsed;
+                    }
+                }
+                return oldest;
+            }
+            case 'round-robin':
+            default: {
+                // Cycle through accounts in order
+                const allAccounts = this.authManager.getAllAccounts();
+                // Find next available account starting from currentIndex
+                for (let i = 0; i < allAccounts.length; i++) {
+                    const idx = (this.currentIndex + i) % allAccounts.length;
+                    const account = allAccounts[idx];
+                    if (availableAccounts.includes(account)) {
+                        this.currentIndex = (idx + 1) % allAccounts.length;
+                        return account;
+                    }
+                }
+                // Fallback to first available
+                return availableAccounts[0];
+            }
+        }
+    }
+    /**
+     * Get the next available account, potentially rotating from current
+     *
+     * If the current account is on cooldown or has been rate-limited,
+     * switches to the next available account.
+     *
+     * @returns Rotation result with the selected account
+     * @throws AllAccountsOnCooldownError if all accounts are on cooldown
+     */
+    async getNextAvailableAccount() {
+        const allAccounts = this.authManager.getAllAccounts();
+        const totalAccounts = allAccounts.length;
+        if (totalAccounts === 0) {
+            throw new Error('No accounts configured. Run `puter-auth login` to add an account.');
+        }
+        // If rotation is disabled, just return current account
+        if (!this.enabled) {
+            const current = this.authManager.getActiveAccount();
+            if (!current) {
+                throw new Error('No active account');
+            }
+            return {
+                account: current,
+                wasRotated: false,
+                accountsOnCooldown: this.getAccountsOnCooldownCount(),
+                totalAccounts,
+            };
+        }
+        const availableAccounts = this.getAvailableAccounts();
+        const accountsOnCooldown = totalAccounts - availableAccounts.length;
+        // If all accounts are on cooldown, throw error with details
+        if (availableAccounts.length === 0) {
+            const statuses = this.getAccountStatuses();
+            throw new AllAccountsOnCooldownError(statuses);
+        }
+        const currentAccount = this.authManager.getActiveAccount();
+        const currentUsername = currentAccount?.username;
+        // Check if current account is available
+        const currentIsAvailable = currentAccount &&
+            availableAccounts.some(a => a.username === currentAccount.username);
+        if (currentIsAvailable && accountsOnCooldown === 0) {
+            // Current account is fine and no rotation needed
+            return {
+                account: currentAccount,
+                wasRotated: false,
+                accountsOnCooldown: 0,
+                totalAccounts,
+            };
+        }
+        // Need to select a (potentially different) account
+        const selectedAccount = this.selectNextAccount(availableAccounts);
+        const wasRotated = selectedAccount.username !== currentUsername;
+        // If we selected a different account, switch to it
+        if (wasRotated) {
+            const targetIndex = allAccounts.findIndex(a => a.username === selectedAccount.username);
+            if (targetIndex >= 0) {
+                await this.authManager.switchAccount(targetIndex);
+                this.logger?.info(`Rotated to account: ${selectedAccount.username}`);
+            }
+        }
+        // Mark as used
+        this.markAsUsed(selectedAccount.username);
+        return {
+            account: selectedAccount,
+            wasRotated,
+            previousUsername: wasRotated ? currentUsername : undefined,
+            accountsOnCooldown,
+            totalAccounts,
+        };
+    }
+    /**
+     * Handle a rate limit error by adding current account to cooldown
+     * and returning the next available account
+     *
+     * @param error - The rate limit error
+     * @returns Next available account, or null if all on cooldown
+     */
+    async handleRateLimitError(error) {
+        const currentAccount = this.authManager.getActiveAccount();
+        if (currentAccount) {
+            this.addToCooldown(currentAccount.username, error.message);
+        }
+        try {
+            return await this.getNextAvailableAccount();
+        }
+        catch (e) {
+            if (e instanceof AllAccountsOnCooldownError) {
+                return null;
+            }
+            throw e;
+        }
+    }
+    /**
+     * Clear all cooldowns (useful for testing or manual reset)
+     */
+    clearCooldowns() {
+        this.cooldownMap.clear();
+        this.logger?.debug('All account cooldowns cleared');
+    }
+    /**
+     * Reset all statistics
+     */
+    resetStats() {
+        this.usageStats.clear();
+        this.currentIndex = 0;
+        this.logger?.debug('Account rotation stats reset');
+    }
+    /**
+     * Update configuration
+     */
+    configure(options) {
+        if (options.cooldownMs !== undefined) {
+            this.cooldownMs = options.cooldownMs;
+        }
+        if (options.enabled !== undefined) {
+            this.enabled = options.enabled;
+        }
+        if (options.strategy !== undefined) {
+            this.strategy = options.strategy;
+        }
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return {
+            cooldownMs: this.cooldownMs,
+            enabled: this.enabled,
+            strategy: this.strategy,
+        };
+    }
+    /**
+     * Check if rotation is needed (current account on cooldown)
+     */
+    isRotationNeeded() {
+        if (!this.enabled)
+            return false;
+        const current = this.authManager.getActiveAccount();
+        if (!current)
+            return false;
+        return this.isAccountOnCooldown(current.username);
+    }
+    /**
+     * Get a summary of the rotation state
+     */
+    getSummary() {
+        const allAccounts = this.authManager.getAllAccounts();
+        const available = this.getAvailableAccounts();
+        const current = this.authManager.getActiveAccount();
+        return {
+            enabled: this.enabled,
+            totalAccounts: allAccounts.length,
+            availableAccounts: available.length,
+            onCooldown: allAccounts.length - available.length,
+            currentAccount: current?.username ?? null,
+            strategy: this.strategy,
+        };
+    }
+}
+/**
+ * Global AccountRotationManager instance
+ */
+let globalAccountRotationManager = null;
+/**
+ * Get the global AccountRotationManager instance
+ *
+ * @param authManager - The auth manager (required on first call)
+ * @param options - Configuration options
+ * @param logger - Optional logger
+ * @returns The global AccountRotationManager instance
+ */
+export function getGlobalAccountRotationManager(authManager, options, logger) {
+    if (!globalAccountRotationManager) {
+        if (!authManager) {
+            throw new Error('AuthManager required when creating AccountRotationManager');
+        }
+        globalAccountRotationManager = new AccountRotationManager(authManager, options, logger);
+    }
+    else if (options) {
+        globalAccountRotationManager.configure(options);
+    }
+    return globalAccountRotationManager;
+}
+/**
+ * Reset the global AccountRotationManager (useful for testing)
+ */
+export function resetGlobalAccountRotationManager() {
+    globalAccountRotationManager = null;
+}
+//# sourceMappingURL=account-rotation.js.map

package/dist/account-rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-rotation.js","sourceRoot":"","sources":["../src/account-rotation.ts"],"names":[],"mappings":"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"}

package/dist/ai-provider/puter-chat-language-model.d.ts

@@ -3,12 +3,19 @@
  *
  * Implements the AI SDK LanguageModelV3 interface using the official @heyputer/puter.js SDK.
  * This enables Puter to work as a proper AI SDK provider in OpenCode.
+ *
+ * Features automatic model fallback when rate limits are encountered.
  */
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult } from '@ai-sdk/provider';
 import type { PuterChatSettings, PuterChatConfig } from './puter-chat-settings.js';
 /**
  * Puter Chat Language Model implementing LanguageModelV3.
  * Uses the official @heyputer/puter.js SDK for all API calls.
+ *
+ * Features automatic model fallback when rate limits are encountered:
+ * - Detects rate limit errors (429, 403)
+ * - Automatically switches to free OpenRouter models
+ * - Tracks model cooldowns to avoid repeated failures
  */
 export declare class PuterChatLanguageModel implements LanguageModelV3 {
     readonly specificationVersion: "v3";
@@ -17,6 +24,8 @@ export declare class PuterChatLanguageModel implements LanguageModelV3 {
     private readonly settings;
     private readonly config;
     private puterInstance;
+    private readonly fallbackManager;
+    private readonly logger;
     constructor(modelId: string, settings: PuterChatSettings, config: PuterChatConfig);
     /**
      * Initialize the Puter SDK with auth token.
@@ -37,6 +46,10 @@ export declare class PuterChatLanguageModel implements LanguageModelV3 {
     private convertTools;
     /**
      * Build options for Puter SDK chat call.
+     *
+     * @param options - AI SDK call options
+     * @param streaming - Whether to enable streaming
+     * @param modelOverride - Optional model to use instead of this.modelId (for fallback)
      */
     private buildSDKOptions;
     /**
@@ -53,10 +66,16 @@ export declare class PuterChatLanguageModel implements LanguageModelV3 {
     private extractTextContent;
     /**
      * Non-streaming generation using Puter SDK.
+     *
+     * Automatically falls back to alternative models when rate limits are hit,
+     * unless `disableFallback` is set in settings.
      */
     doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
     /**
      * Streaming generation using Puter SDK.
+     *
+     * Automatically falls back to alternative models when rate limits are hit,
+     * unless `disableFallback` is set in settings.
      */
     doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }

package/dist/ai-provider/puter-chat-language-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"puter-chat-language-model.d.ts","sourceRoot":"","sources":["../../src/ai-provider/puter-chat-language-model.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAW5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAiGnF;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D,QAAQ,CAAC,oBAAoB,EAAG,IAAI,CAAU;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,aAAa,CAAyB;gBAG5C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,eAAe;IAQzB;;OAEG;YACW,YAAY;IA0B1B;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAE5C;IAED;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA4E/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiCvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAgBhB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAyD7F;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;CA2E1F"}
+{"version":3,"file":"puter-chat-language-model.d.ts","sourceRoot":"","sources":["../../src/ai-provider/puter-chat-language-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAW5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAsGnF;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D,QAAQ,CAAC,oBAAoB,EAAG,IAAI,CAAU;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAG9B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,eAAe;IAczB;;OAEG;YACW,YAAY;IA0B1B;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAE5C;IAED;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA4E/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAqCvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAgBhB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;;;;OAKG;IACG,UAAU,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,6BAA6B,CAAC;IA2F7F;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;CA2G1F"}

package/dist/ai-provider/puter-chat-language-model.js

@@ -3,10 +3,19 @@
  *
  * Implements the AI SDK LanguageModelV3 interface using the official @heyputer/puter.js SDK.
  * This enables Puter to work as a proper AI SDK provider in OpenCode.
+ *
+ * Features automatic model fallback when rate limits are encountered.
  */
+import { getGlobalFallbackManager, } from '../fallback.js';
+import { createLogger } from '../logger.js';
 /**
  * Puter Chat Language Model implementing LanguageModelV3.
  * Uses the official @heyputer/puter.js SDK for all API calls.
+ *
+ * Features automatic model fallback when rate limits are encountered:
+ * - Detects rate limit errors (429, 403)
+ * - Automatically switches to free OpenRouter models
+ * - Tracks model cooldowns to avoid repeated failures
  */
 export class PuterChatLanguageModel {
     specificationVersion = 'v3';
@@ -15,11 +24,17 @@ export class PuterChatLanguageModel {
     settings;
     config;
     puterInstance = null;
+    fallbackManager;
+    logger;
     constructor(modelId, settings, config) {
         this.modelId = modelId;
         this.settings = settings;
         this.config = config;
         this.provider = config.provider;
+        // Initialize fallback manager with config options
+        this.fallbackManager = getGlobalFallbackManager(config.fallback);
+        // Create logger (uses console by default, can be configured)
+        this.logger = createLogger({ debug: false }); // Will be quiet unless debug enabled
     }
     /**
      * Initialize the Puter SDK with auth token.
@@ -144,13 +159,17 @@ export class PuterChatLanguageModel {
     }
     /**
      * Build options for Puter SDK chat call.
+     *
+     * @param options - AI SDK call options
+     * @param streaming - Whether to enable streaming
+     * @param modelOverride - Optional model to use instead of this.modelId (for fallback)
      */
-    buildSDKOptions(options, streaming) {
+    buildSDKOptions(options, streaming, modelOverride) {
         // Filter to only function tools
         const functionTools = options.tools?.filter((tool) => tool.type === 'function');
         const tools = this.convertTools(functionTools);
         const sdkOptions = {
-            model: this.modelId,
+            model: modelOverride ?? this.modelId,
             stream: streaming,
         };
         // Only add optional params if they have values
@@ -232,13 +251,43 @@ export class PuterChatLanguageModel {
     }
     /**
      * Non-streaming generation using Puter SDK.
+     *
+     * Automatically falls back to alternative models when rate limits are hit,
+     * unless `disableFallback` is set in settings.
      */
     async doGenerate(options) {
         const puter = await this.initPuterSDK();
         const messages = this.convertPromptToMessages(options.prompt);
-        const sdkOptions = this.buildSDKOptions(options, false);
         const warnings = [];
-        const response = await puter.ai.chat(messages, sdkOptions);
+        // Check if fallback is disabled for this request
+        const useFallback = !this.settings.disableFallback;
+        // Define the operation that will be executed (possibly with fallback)
+        const executeChat = async (model) => {
+            const sdkOptions = this.buildSDKOptions(options, false, model);
+            return await puter.ai.chat(messages, sdkOptions);
+        };
+        let response;
+        let actualModelUsed = this.modelId;
+        let wasFallback = false;
+        if (useFallback) {
+            // Execute with fallback support
+            const fallbackResult = await this.fallbackManager.executeWithFallback(this.modelId, executeChat, this.logger);
+            response = fallbackResult.result;
+            actualModelUsed = fallbackResult.usedModel;
+            wasFallback = fallbackResult.wasFallback;
+            if (wasFallback) {
+                // Add a warning that fallback was used
+                warnings.push({
+                    type: 'other',
+                    message: `Model ${this.modelId} rate limited, used fallback: ${actualModelUsed}`,
+                });
+            }
+        }
+        else {
+            // Execute without fallback
+            const sdkOptions = this.buildSDKOptions(options, false);
+            response = await puter.ai.chat(messages, sdkOptions);
+        }
         const content = [];
         // Extract text content (handles both string and array formats)
         const textContent = this.extractTextContent(response.message?.content);
@@ -277,7 +326,7 @@ export class PuterChatLanguageModel {
             finishReason: this.mapFinishReason(response.finish_reason),
             usage: this.mapUsage(response.usage),
             warnings,
-            request: { body: { messages, options: sdkOptions } },
+            request: { body: { messages, model: actualModelUsed } },
             response: {
                 body: response,
             },
@@ -285,14 +334,42 @@ export class PuterChatLanguageModel {
     }
     /**
      * Streaming generation using Puter SDK.
+     *
+     * Automatically falls back to alternative models when rate limits are hit,
+     * unless `disableFallback` is set in settings.
      */
     async doStream(options) {
         const puter = await this.initPuterSDK();
         const messages = this.convertPromptToMessages(options.prompt);
-        const sdkOptions = this.buildSDKOptions(options, true);
         const warnings = [];
         const generateId = this.config.generateId;
-        const streamResponse = await puter.ai.chat(messages, sdkOptions);
+        // Check if fallback is disabled for this request
+        const useFallback = !this.settings.disableFallback;
+        // Define the operation that initiates the stream
+        const initiateStream = async (model) => {
+            const sdkOptions = this.buildSDKOptions(options, true, model);
+            return await puter.ai.chat(messages, sdkOptions);
+        };
+        let streamResponse;
+        let actualModelUsed = this.modelId;
+        if (useFallback) {
+            // Execute stream initiation with fallback support
+            const fallbackResult = await this.fallbackManager.executeWithFallback(this.modelId, initiateStream, this.logger);
+            streamResponse = fallbackResult.result;
+            actualModelUsed = fallbackResult.usedModel;
+            if (fallbackResult.wasFallback) {
+                // Add a warning that fallback was used
+                warnings.push({
+                    type: 'other',
+                    message: `Model ${this.modelId} rate limited, used fallback: ${actualModelUsed}`,
+                });
+            }
+        }
+        else {
+            // Execute without fallback
+            const sdkOptions = this.buildSDKOptions(options, true);
+            streamResponse = await puter.ai.chat(messages, sdkOptions);
+        }
         // Create a transform stream to convert Puter chunks to AI SDK format
         const self = this;
         let textId = null;
@@ -350,7 +427,7 @@ export class PuterChatLanguageModel {
         });
         return {
             stream,
-            request: { body: { messages, options: sdkOptions } },
+            request: { body: { messages, model: actualModelUsed } },
         };
     }
 }