opencode-puter-auth 1.0.38 → 1.0.41

package/README.md

@@ -363,6 +363,191 @@ Create `~/.config/opencode/puter.json` for advanced settings:
 | `auto_create_temp_user` | `true` | Auto-create temp account |
 | `max_retries` | `3` | Retry failed requests |
 | `cache_ttl_ms` | `300000` | Model list cache TTL (5 min) |
+| `fallback_enabled` | `true` | Enable automatic model fallback on rate limits |
+| `fallback_models` | See below | Custom list of fallback models |
+| `fallback_cooldown_ms` | `60000` | Cooldown period for rate-limited models (1 min) |
+| `account_rotation_enabled` | `true` | Enable automatic account rotation |
+| `account_rotation_strategy` | `round-robin` | Strategy: `round-robin` or `least-recently-used` |
+| `account_rotation_cooldown_ms` | `300000` | Cooldown for rate-limited accounts (5 min) |
+
+## Automatic Model Fallback
+
+When a model returns HTTP 429 (rate limited) or 403 (forbidden), the plugin automatically tries free OpenRouter models. This keeps your workflow running even when premium models are temporarily unavailable.
+
+### How It Works
+
+1. You request a model (e.g., `claude-opus-4-5`)
+2. If that model returns a rate limit error, it goes into "cooldown"
+3. The plugin automatically tries the next available free model
+4. A warning is logged showing which fallback model was used
+5. Your request completes without manual intervention
+
+### Default Fallback Models
+
+When rate limits are hit, these free models are tried in order:
+
+| Priority | Model | Description |
+|----------|-------|-------------|
+| 1 | `openrouter:xiaomi/mimo-v2-flash:free` | #1 on SWE-bench, Claude Sonnet 4.5 level |
+| 2 | `openrouter:deepseek/deepseek-r1-0528:free` | o1-level reasoning |
+| 3 | `openrouter:mistralai/devstral-2512:free` | Agentic coding specialist |
+| 4 | `openrouter:qwen/qwen3-coder:free` | 480B MoE coding model |
+| 5 | `openrouter:google/gemini-2.0-flash-exp:free` | 1M context, fast |
+| 6 | `openrouter:meta-llama/llama-4-maverick:free` | General purpose |
+| 7 | `openrouter:openai/gpt-oss-120b:free` | OpenAI open weights |
+
+### Configuration
+
+In `~/.config/opencode/puter.json`:
+
+```json
+{
+  "fallback_enabled": true,
+  "fallback_cooldown_ms": 60000,
+  "fallback_models": [
+    "openrouter:xiaomi/mimo-v2-flash:free",
+    "openrouter:deepseek/deepseek-r1-0528:free",
+    "openrouter:mistralai/devstral-2512:free"
+  ]
+}
+```
+
+### Disable Fallback
+
+To disable fallback globally:
+
+```json
+{
+  "fallback_enabled": false
+}
+```
+
+To disable fallback for a specific request (programmatic usage):
+
+```typescript
+import { createPuter } from 'opencode-puter-auth';
+
+const puter = createPuter({ authToken: 'your-token' });
+const model = puter('claude-opus-4-5', { disableFallback: true });
+```
+
+### Cooldown Behavior
+
+- Rate-limited models are put on cooldown for `fallback_cooldown_ms` (default: 1 minute)
+- Models on cooldown are skipped in favor of available models
+- Cooldown automatically expires, allowing the model to be retried
+- If all models (including fallbacks) are exhausted, the original error is thrown
+
+## Account Rotation (Multi-Account Support)
+
+For even more resilience, you can configure multiple Puter accounts. When one account hits rate limits, the plugin automatically rotates to the next available account.
+
+### How It Works
+
+1. Add multiple Puter accounts using `puter-auth login`
+2. When the active account hits a rate limit, it goes into "cooldown"
+3. The plugin automatically switches to the next available account
+4. Your request continues without interruption
+5. Cooldown accounts become available again after the cooldown period
+
+### Adding Multiple Accounts
+
+```bash
+# Add your first account
+puter-auth login
+
+# Add additional accounts (opens browser for each)
+puter-auth login
+
+# View all accounts
+puter-auth status
+```
+
+### Rotation Strategies
+
+The plugin supports two rotation strategies:
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| `round-robin` (default) | Cycles through accounts in order | Even distribution |
+| `least-recently-used` | Picks the account used longest ago | Maximizing cooldown recovery |
+
+### Configuration
+
+In `~/.config/opencode/puter.json`:
+
+```json
+{
+  "account_rotation_enabled": true,
+  "account_rotation_strategy": "round-robin",
+  "account_rotation_cooldown_ms": 300000
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `account_rotation_enabled` | `true` | Enable automatic account rotation |
+| `account_rotation_strategy` | `round-robin` | Strategy: `round-robin` or `least-recently-used` |
+| `account_rotation_cooldown_ms` | `300000` | Cooldown duration for rate-limited accounts (5 min) |
+
+### Cooldown Behavior
+
+Account cooldowns use exponential backoff:
+- First rate limit: 1x cooldown (5 minutes)
+- Second consecutive: 2x cooldown (10 minutes)
+- Third consecutive: 3x cooldown (15 minutes)
+- Fourth+ consecutive: 4x cooldown (20 minutes max)
+
+This prevents hammering accounts that are consistently being rate-limited.
+
+### Fallback vs Rotation
+
+The plugin supports both **model fallback** and **account rotation**, and they work together:
+
+| Feature | Model Fallback | Account Rotation |
+|---------|---------------|------------------|
+| **Scope** | Different models, same account | Same model, different accounts |
+| **Use case** | Premium model unavailable | Account rate-limited |
+| **Default cooldown** | 1 minute | 5 minutes |
+| **Order of operations** | Tried first | Tried after fallback exhausted |
+
+When a request fails:
+1. First, model fallback tries different models on the current account
+2. If all models fail, account rotation switches to a different account
+3. Model fallback then runs again on the new account
+
+### Programmatic Usage
+
+```typescript
+import { 
+  AccountRotationManager, 
+  getGlobalAccountRotationManager,
+  AllAccountsOnCooldownError 
+} from 'opencode-puter-auth';
+
+// Get the global rotation manager
+const rotation = getGlobalAccountRotationManager(authManager, {
+  cooldownMs: 300000,
+  strategy: 'least-recently-used',
+});
+
+// Check current status
+const summary = rotation.getSummary();
+console.log(`${summary.availableAccounts}/${summary.totalAccounts} accounts available`);
+
+// Handle rate limit errors
+try {
+  await makeRequest();
+} catch (error) {
+  const result = await rotation.handleRateLimitError(error);
+  if (result) {
+    console.log(`Rotated to account: ${result.account.username}`);
+    await makeRequest(); // Retry with new account
+  } else {
+    throw new AllAccountsOnCooldownError(rotation.getAccountStatuses());
+  }
+}
+```
 
 ### Debug Logging
 
@@ -390,6 +575,15 @@ Auth state changes:
 [puter-auth] 15:30:45 Auth: Switched account - other_user
 ```
 
+Fallback behavior:
+
+```
+[puter-auth] 15:30:45 Request: claude-opus-4-5
+[puter-auth] 15:30:45 Rate limited (429), adding to cooldown
+[puter-auth] 15:30:45 Fallback: trying openrouter:xiaomi/mimo-v2-flash:free
+[puter-auth] 15:30:47 Response: 200 OK (used fallback model)
+```
+
 ## Custom Tools
 
 The plugin adds these tools to OpenCode:

package/dist/account-rotation.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 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');
+ * ```
+ */
+import type { PuterAccount } from './types.js';
+import type { Logger } from './logger.js';
+/**
+ * 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 declare const DEFAULT_ACCOUNT_COOLDOWN_MS = 300000;
+/**
+ * Configuration options for AccountRotationManager
+ */
+export interface AccountRotationOptions {
+    /** Cooldown duration in milliseconds (default: 5 minutes) */
+    cooldownMs?: number;
+    /** Whether account rotation is enabled (default: true) */
+    enabled?: boolean;
+    /** Strategy for selecting next account: 'round-robin' | 'least-recently-used' */
+    strategy?: 'round-robin' | 'least-recently-used';
+}
+/**
+ * Status of an individual account in the rotation pool
+ */
+export interface AccountStatus {
+    /** Account username */
+    username: string;
+    /** Whether the account is currently on cooldown */
+    isOnCooldown: boolean;
+    /** Remaining cooldown time in ms (0 if not on cooldown) */
+    cooldownRemainingMs: number;
+    /** Reason for cooldown (if on cooldown) */
+    cooldownReason?: string;
+    /** When the account was last used (Unix timestamp) */
+    lastUsedAt?: number;
+    /** Number of times this account has been rate-limited */
+    rateLimitCount: number;
+}
+/**
+ * Result of account rotation attempt
+ */
+export interface AccountRotationResult {
+    /** The account that was selected */
+    account: PuterAccount;
+    /** Whether this account was rotated to (vs. being the primary) */
+    wasRotated: boolean;
+    /** Username of the previous account (if rotated) */
+    previousUsername?: string;
+    /** Number of accounts currently on cooldown */
+    accountsOnCooldown: number;
+    /** Total accounts available */
+    totalAccounts: number;
+}
+/**
+ * Error thrown when all accounts are on cooldown
+ */
+export declare class AllAccountsOnCooldownError extends Error {
+    readonly accountStatuses: AccountStatus[];
+    readonly nextAvailableIn: number;
+    constructor(statuses: AccountStatus[]);
+}
+/**
+ * Interface for the auth manager (to avoid circular dependency)
+ */
+export interface IAuthManager {
+    getActiveAccount(): PuterAccount | null;
+    getAllAccounts(): PuterAccount[];
+    switchAccount(index: number): Promise<boolean>;
+    isAuthenticated(): boolean;
+}
+/**
+ * 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 declare class AccountRotationManager {
+    private authManager;
+    private cooldownMap;
+    private usageStats;
+    private cooldownMs;
+    private enabled;
+    private strategy;
+    private currentIndex;
+    private logger?;
+    /**
+     * Create a new AccountRotationManager
+     *
+     * @param authManager - The PuterAuthManager instance
+     * @param options - Configuration options
+     * @param logger - Optional logger for debugging
+     */
+    constructor(authManager: IAuthManager, options?: AccountRotationOptions, 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: string): boolean;
+    /**
+     * 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: string): number;
+    /**
+     * 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: string, reason: string): void;
+    /**
+     * Remove an account from cooldown (e.g., after successful request)
+     *
+     * @param username - Account username to remove from cooldown
+     */
+    removeFromCooldown(username: string): void;
+    /**
+     * Mark an account as recently used
+     *
+     * @param username - Account username that was used
+     */
+    markAsUsed(username: string): void;
+    /**
+     * Get status of all accounts
+     *
+     * @returns Array of account statuses
+     */
+    getAccountStatuses(): AccountStatus[];
+    /**
+     * Get list of available accounts (not on cooldown)
+     *
+     * @returns Array of available accounts
+     */
+    getAvailableAccounts(): PuterAccount[];
+    /**
+     * Get count of accounts currently on cooldown
+     *
+     * @returns Number of accounts on cooldown
+     */
+    getAccountsOnCooldownCount(): number;
+    /**
+     * Select the next account to use based on strategy
+     *
+     * @param availableAccounts - List of available accounts
+     * @returns The selected account
+     */
+    private selectNextAccount;
+    /**
+     * 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
+     */
+    getNextAvailableAccount(): Promise<AccountRotationResult>;
+    /**
+     * 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
+     */
+    handleRateLimitError(error: Error): Promise<AccountRotationResult | null>;
+    /**
+     * Clear all cooldowns (useful for testing or manual reset)
+     */
+    clearCooldowns(): void;
+    /**
+     * Reset all statistics
+     */
+    resetStats(): void;
+    /**
+     * Update configuration
+     */
+    configure(options: Partial<AccountRotationOptions>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<AccountRotationOptions>;
+    /**
+     * Check if rotation is needed (current account on cooldown)
+     */
+    isRotationNeeded(): boolean;
+    /**
+     * Get a summary of the rotation state
+     */
+    getSummary(): {
+        enabled: boolean;
+        totalAccounts: number;
+        availableAccounts: number;
+        onCooldown: number;
+        currentAccount: string | null;
+        strategy: string;
+    };
+}
+/**
+ * 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 declare function getGlobalAccountRotationManager(authManager?: IAuthManager, options?: AccountRotationOptions, logger?: Logger): AccountRotationManager;
+/**
+ * Reset the global AccountRotationManager (useful for testing)
+ */
+export declare function resetGlobalAccountRotationManager(): void;
+//# sourceMappingURL=account-rotation.d.ts.map

package/dist/account-rotation.d.ts.map

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