@azumag/opencode-rate-limit-fallback 1.24.0 → 1.27.0

package/README.md

@@ -12,6 +12,11 @@ OpenCode plugin that automatically switches to fallback models when rate limited
 - Three fallback modes: `cycle`, `stop`, and `retry-last`
 - Session model tracking for sequential fallback across multiple rate limits
 - Cooldown period to prevent immediate retry on rate-limited models
+- **Exponential backoff with configurable retry policies**
+  - Supports immediate, exponential, and linear backoff strategies
+  - Jitter to prevent thundering herd problem
+  - Configurable retry limits and timeouts
+  - Retry statistics tracking
 - Toast notifications for user feedback
 - Subagent session support with automatic fallback propagation to parent sessions
 - Configurable maximum subagent nesting depth
@@ -64,6 +69,15 @@ Create a configuration file at one of these locations:
     { "providerID": "google", "modelID": "gemini-2.5-pro" },
     { "providerID": "google", "modelID": "gemini-2.5-flash" }
   ],
+  "retryPolicy": {
+    "maxRetries": 3,
+    "strategy": "exponential",
+    "baseDelayMs": 1000,
+    "maxDelayMs": 30000,
+    "jitterEnabled": true,
+    "jitterFactor": 0.1,
+    "timeoutMs": 60000
+  },
   "metrics": {
     "enabled": true,
     "output": {
@@ -85,6 +99,7 @@ Create a configuration file at one of these locations:
 | `fallbackModels` | array | See below | List of fallback models in priority order |
 | `maxSubagentDepth` | number | `10` | Maximum nesting depth for subagent hierarchies |
 | `enableSubagentFallback` | boolean | `true` | Enable/disable fallback for subagent sessions |
+| `retryPolicy` | object | See below | Retry policy configuration (see below) |
 
 ### Fallback Modes
 
@@ -94,6 +109,64 @@ Create a configuration file at one of these locations:
 | `"stop"` | Stop and show error when all models are exhausted |
 | `"retry-last"` | Try the last model once more, then reset to first on next prompt |
 
+### Retry Policy
+
+The retry policy controls how the plugin handles retry attempts after rate limits, with support for exponential backoff to reduce API pressure.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxRetries` | number | `3` | Maximum retry attempts before giving up |
+| `strategy` | string | `"immediate"` | Backoff strategy: `"immediate"`, `"exponential"`, or `"linear"` |
+| `baseDelayMs` | number | `1000` | Base delay in milliseconds for backoff calculation |
+| `maxDelayMs` | number | `30000` | Maximum delay in milliseconds |
+| `jitterEnabled` | boolean | `false` | Add random jitter to delays to prevent thundering herd |
+| `jitterFactor` | number | `0.1` | Jitter factor (0.1 = 10% variance) |
+| `timeoutMs` | number | `undefined` | Overall timeout for all retry attempts (optional) |
+
+#### Retry Strategies
+
+**Immediate** (default, no backoff)
+```
+delay = 0ms
+```
+Retries immediately without any delay. This is the original behavior and maintains backward compatibility.
+
+**Exponential** (recommended for production)
+```
+delay = min(baseDelayMs * (2 ^ attempt), maxDelayMs)
+delay = delay * (1 + random(-jitterFactor, jitterFactor))  // if jitter enabled
+```
+Exponential backoff that doubles the delay after each attempt. This is the standard pattern for rate limit handling.
+
+Example with `baseDelayMs: 1000`, `maxDelayMs: 30000`, and `jitterFactor: 0.1`:
+- Attempt 0: ~1000ms (with jitter: 900-1100ms)
+- Attempt 1: ~2000ms (with jitter: 1800-2200ms)
+- Attempt 2: ~4000ms (with jitter: 3600-4400ms)
+- Attempt 3: ~8000ms (with jitter: 7200-8800ms)
+- Attempt 4+: ~16000ms (capped at maxDelayMs: 30000ms)
+
+**Linear**
+```
+delay = min(baseDelayMs * (attempt + 1), maxDelayMs)
+delay = delay * (1 + random(-jitterFactor, jitterFactor))  // if jitter enabled
+```
+Linear backoff that increases delay by a constant amount after each attempt.
+
+Example with `baseDelayMs: 1000` and `maxDelayMs: 5000`:
+- Attempt 0: ~1000ms
+- Attempt 1: ~2000ms
+- Attempt 2: ~3000ms
+- Attempt 3: ~4000ms
+- Attempt 4+: ~5000ms (capped at maxDelayMs)
+
+#### Jitter
+
+Jitter adds random variation to delay times to prevent the "thundering herd" problem, where multiple clients retry simultaneously and overwhelm the API.
+
+- Recommended for production environments with multiple concurrent users
+- `jitterFactor: 0.1` adds ±10% variance to delay times
+- Example: With base delay of 1000ms and jitterFactor 0.1, actual delay will be 900-1100ms
+
 ### Default Fallback Models
 
 If no configuration is provided, the following models are used:
@@ -136,6 +209,7 @@ When OpenCode uses subagents (e.g., for complex tasks requiring specialized agen
 The plugin includes a metrics collection feature that tracks:
 - Rate limit events per provider/model
 - Fallback statistics (total, successful, failed, average duration)
+- **Retry statistics** (total attempts, successes, failures, average delay)
 - Model performance (requests, successes, failures, response time)
 
 ### Metrics Configuration
@@ -191,6 +265,23 @@ Fallbacks:
   Failed: 1
   Avg Duration: 1.25s
 
+Retries:
+----------------------------------------
+  Total: 12
+  Successful: 8
+  Failed: 4
+  Avg Delay: 2.5s
+
+  By Model:
+    anthropic/claude-3-5-sonnet-20250514:
+      Attempts: 5
+      Successes: 3
+      Success Rate: 60.0%
+    google/gemini-2.5-pro:
+      Attempts: 7
+      Successes: 5
+      Success Rate: 71.4%
+
 Model Performance:
 ----------------------------------------
   google/gemini-2.5-pro:
@@ -225,6 +316,22 @@ Model Performance:
       }
     }
   },
+  "retries": {
+    "total": 12,
+    "successful": 8,
+    "failed": 4,
+    "averageDelay": 2500,
+    "byModel": {
+      "anthropic/claude-3-5-sonnet-20250514": {
+        "attempts": 5,
+        "successes": 3
+      },
+      "google/gemini-2.5-pro": {
+        "attempts": 7,
+        "successes": 5
+      }
+    }
+  },
   "modelPerformance": {
     "google/gemini-2.5-pro": {
       "requests": 10,
@@ -248,6 +355,15 @@ anthropic/claude-3-5-sonnet-20250514,5,1739148000000,1739149740000,3500
 total,successful,failed,avg_duration_ms
 3,2,1,1250
 
+=== RETRIES_SUMMARY ===
+total,successful,failed,avg_delay_ms
+12,8,4,2500
+
+=== RETRIES_BY_MODEL ===
+model,attempts,successes,success_rate
+anthropic/claude-3-5-sonnet-20250514,5,3,60.0
+google/gemini-2.5-pro,7,5,71.4
+
 === MODEL_PERFORMANCE ===
 model,requests,successes,failures,avg_response_time_ms,success_rate
 google/gemini-2.5-pro,10,9,1,850,90.0

package/dist/src/fallback/FallbackHandler.d.ts

@@ -20,6 +20,7 @@ export declare class FallbackHandler {
     private fallbackMessages;
     private metricsManager;
     private subagentTracker;
+    private retryManager;
     constructor(config: PluginConfig, client: OpenCodeClient, logger: Logger, metricsManager: MetricsManager, subagentTracker: SubagentTracker);
     /**
      * Check and mark fallback in progress for deduplication

package/dist/src/fallback/FallbackHandler.js

@@ -4,6 +4,7 @@
 import { SESSION_ENTRY_TTL_MS } from '../types/index.js';
 import { ModelSelector } from './ModelSelector.js';
 import { extractMessageParts, convertPartsToSDKFormat, safeShowToast, getStateKey, getModelKey, DEDUP_WINDOW_MS, STATE_TIMEOUT_MS } from '../utils/helpers.js';
+import { RetryManager } from '../retry/RetryManager.js';
 /**
  * Fallback Handler class for orchestrating the fallback retry flow
  */
@@ -21,6 +22,8 @@ export class FallbackHandler {
     metricsManager;
     // Subagent tracker reference
     subagentTracker;
+    // Retry manager reference
+    retryManager;
     constructor(config, client, logger, metricsManager, subagentTracker) {
         this.config = config;
         this.client = client;
@@ -33,6 +36,8 @@ export class FallbackHandler {
         this.retryState = new Map();
         this.fallbackInProgress = new Map();
         this.fallbackMessages = new Map();
+        // Initialize retry manager
+        this.retryManager = new RetryManager(config.retryPolicy || {}, logger);
     }
     /**
      * Check and mark fallback in progress for deduplication
@@ -188,6 +193,32 @@ export class FallbackHandler {
             const state = this.getOrCreateRetryState(sessionID, lastUserMessage.info.id);
             const stateKey = getStateKey(sessionID, lastUserMessage.info.id);
             const fallbackKey = getStateKey(dedupSessionID, lastUserMessage.info.id);
+            // Check if retry should be attempted (using retry manager)
+            if (!this.retryManager.canRetry(dedupSessionID, lastUserMessage.info.id)) {
+                await safeShowToast(this.client, {
+                    body: {
+                        title: "Fallback Exhausted",
+                        message: "All retry attempts failed",
+                        variant: "error",
+                        duration: 5000,
+                    },
+                });
+                this.logger.warn('Retry exhausted', { sessionID: dedupSessionID, messageID: lastUserMessage.info.id });
+                this.retryState.delete(stateKey);
+                this.fallbackInProgress.delete(fallbackKey);
+                // Record retry failure metric
+                if (this.metricsManager) {
+                    this.metricsManager.recordRetryFailure();
+                }
+                return;
+            }
+            // Get delay for next retry
+            const delay = this.retryManager.getRetryDelay(dedupSessionID, lastUserMessage.info.id);
+            // Apply delay if configured
+            if (delay > 0) {
+                this.logger.debug(`Applying retry delay`, { delayMs: delay });
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
             // Select the next fallback model
             const nextModel = await this.modelSelector.selectFallbackModel(currentProviderID, currentModelID, state.attemptedModels);
             // Show error if no model is available
@@ -208,6 +239,12 @@ export class FallbackHandler {
             }
             state.attemptedModels.add(getModelKey(nextModel.providerID, nextModel.modelID));
             state.lastAttemptTime = Date.now();
+            // Record retry attempt
+            this.retryManager.recordRetry(dedupSessionID, lastUserMessage.info.id, nextModel.modelID, delay);
+            // Record retry metric
+            if (this.metricsManager) {
+                this.metricsManager.recordRetryAttempt(nextModel.modelID, delay);
+            }
             // Extract message parts
             const parts = extractMessageParts(lastUserMessage);
             if (parts.length === 0) {
@@ -217,7 +254,7 @@ export class FallbackHandler {
             await safeShowToast(this.client, {
                 body: {
                     title: "Retrying",
-                    message: `Using ${nextModel.providerID}/${nextModel.modelID}`,
+                    message: `Using ${nextModel.providerID}/${nextModel.modelID}${delay > 0 ? ` (after ${delay}ms)` : ''}`,
                     variant: "info",
                     duration: 3000,
                 },
@@ -234,6 +271,11 @@ export class FallbackHandler {
             });
             // Retry with the selected model
             await this.retryWithModel(dedupSessionID, nextModel, parts, hierarchy);
+            // Record retry success
+            this.retryManager.recordSuccess(dedupSessionID, nextModel.modelID);
+            if (this.metricsManager) {
+                this.metricsManager.recordRetrySuccess(nextModel.modelID);
+            }
             // Clean up state
             this.retryState.delete(stateKey);
         }
@@ -245,6 +287,10 @@ export class FallbackHandler {
                 error: errorMessage,
                 name: errorName,
             });
+            // Record retry failure on error
+            const rootSessionID = this.subagentTracker.getRootSession(sessionID);
+            const targetSessionID = rootSessionID || sessionID;
+            this.retryManager.recordFailure(targetSessionID);
         }
     }
     /**
@@ -327,6 +373,7 @@ export class FallbackHandler {
             }
         }
         this.modelSelector.cleanupStaleEntries();
+        this.retryManager.cleanupStaleEntries(SESSION_ENTRY_TTL_MS);
     }
     /**
      * Clean up all resources
@@ -337,5 +384,6 @@ export class FallbackHandler {
         this.retryState.clear();
         this.fallbackInProgress.clear();
         this.fallbackMessages.clear();
+        this.retryManager.destroy();
     }
 }

package/dist/src/metrics/MetricsManager.d.ts

@@ -49,6 +49,18 @@ export declare class MetricsManager {
      * Record a failed model request
      */
     recordModelFailure(providerID: string, modelID: string): void;
+    /**
+     * Record a retry attempt
+     */
+    recordRetryAttempt(modelID: string, delay: number): void;
+    /**
+     * Record a successful retry
+     */
+    recordRetrySuccess(modelID: string): void;
+    /**
+     * Record a failed retry
+     */
+    recordRetryFailure(): void;
     /**
      * Get a copy of the current metrics
      */

package/dist/src/metrics/MetricsManager.js

@@ -23,6 +23,13 @@ export class MetricsManager {
                 averageDuration: 0,
                 byTargetModel: new Map(),
             },
+            retries: {
+                total: 0,
+                successful: 0,
+                failed: 0,
+                averageDelay: 0,
+                byModel: new Map(),
+            },
             modelPerformance: new Map(),
             startedAt: Date.now(),
             generatedAt: Date.now(),
@@ -56,6 +63,13 @@ export class MetricsManager {
                 averageDuration: 0,
                 byTargetModel: new Map(),
             },
+            retries: {
+                total: 0,
+                successful: 0,
+                failed: 0,
+                averageDelay: 0,
+                byModel: new Map(),
+            },
             modelPerformance: new Map(),
             startedAt: Date.now(),
             generatedAt: Date.now(),
@@ -177,6 +191,44 @@ export class MetricsManager {
         existing.failures++;
         this.metrics.modelPerformance.set(key, existing);
     }
+    /**
+     * Record a retry attempt
+     */
+    recordRetryAttempt(modelID, delay) {
+        if (!this.config.enabled)
+            return;
+        this.metrics.retries.total++;
+        // Update average delay
+        const totalDelay = this.metrics.retries.averageDelay * (this.metrics.retries.total - 1);
+        this.metrics.retries.averageDelay = (totalDelay + delay) / this.metrics.retries.total;
+        // Update model-specific stats
+        let modelStats = this.metrics.retries.byModel.get(modelID);
+        if (!modelStats) {
+            modelStats = { attempts: 0, successes: 0 };
+            this.metrics.retries.byModel.set(modelID, modelStats);
+        }
+        modelStats.attempts++;
+    }
+    /**
+     * Record a successful retry
+     */
+    recordRetrySuccess(modelID) {
+        if (!this.config.enabled)
+            return;
+        this.metrics.retries.successful++;
+        const modelStats = this.metrics.retries.byModel.get(modelID);
+        if (modelStats) {
+            modelStats.successes++;
+        }
+    }
+    /**
+     * Record a failed retry
+     */
+    recordRetryFailure() {
+        if (!this.config.enabled)
+            return;
+        this.metrics.retries.failed++;
+    }
     /**
      * Get a copy of the current metrics
      */
@@ -209,6 +261,10 @@ export class MetricsManager {
                 ...metrics.fallbacks,
                 byTargetModel: Object.fromEntries(Array.from(metrics.fallbacks.byTargetModel.entries()).map(([k, v]) => [k, v])),
             },
+            retries: {
+                ...metrics.retries,
+                byModel: Object.fromEntries(Array.from(metrics.retries.byModel.entries()).map(([k, v]) => [k, v])),
+            },
             modelPerformance: Object.fromEntries(Array.from(metrics.modelPerformance.entries()).map(([k, v]) => [k, v])),
             startedAt: metrics.startedAt,
             generatedAt: metrics.generatedAt,
@@ -263,6 +319,29 @@ export class MetricsManager {
             }
         }
         lines.push("");
+        // Retries
+        lines.push("Retries:");
+        lines.push("-".repeat(40));
+        lines.push(`  Total: ${metrics.retries.total}`);
+        lines.push(`  Successful: ${metrics.retries.successful}`);
+        lines.push(`  Failed: ${metrics.retries.failed}`);
+        if (metrics.retries.averageDelay > 0) {
+            lines.push(`  Avg Delay: ${(metrics.retries.averageDelay / 1000).toFixed(2)}s`);
+        }
+        if (metrics.retries.byModel.size > 0) {
+            lines.push("");
+            lines.push("  By Model:");
+            for (const [model, data] of metrics.retries.byModel.entries()) {
+                lines.push(`    ${model}:`);
+                lines.push(`      Attempts: ${data.attempts}`);
+                lines.push(`      Successes: ${data.successes}`);
+                if (data.attempts > 0) {
+                    const successRate = ((data.successes / data.attempts) * 100).toFixed(1);
+                    lines.push(`      Success Rate: ${successRate}%`);
+                }
+            }
+        }
+        lines.push("");
         // Model Performance
         lines.push("Model Performance:");
         lines.push("-".repeat(40));
@@ -326,6 +405,29 @@ export class MetricsManager {
             ].join(","));
         }
         lines.push("");
+        // Retries Summary CSV
+        lines.push("=== RETRIES_SUMMARY ===");
+        lines.push(`total,successful,failed,avg_delay_ms`);
+        lines.push([
+            metrics.retries.total,
+            metrics.retries.successful,
+            metrics.retries.failed,
+            metrics.retries.averageDelay || 0,
+        ].join(","));
+        lines.push("");
+        // Retries by Model CSV
+        lines.push("=== RETRIES_BY_MODEL ===");
+        lines.push("model,attempts,successes,success_rate");
+        for (const [model, data] of metrics.retries.byModel.entries()) {
+            const successRate = data.attempts > 0 ? ((data.successes / data.attempts) * 100).toFixed(1) : "0";
+            lines.push([
+                model,
+                data.attempts,
+                data.successes,
+                successRate,
+            ].join(","));
+        }
+        lines.push("");
         // Model Performance CSV
         lines.push("=== MODEL_PERFORMANCE ===");
         lines.push("model,requests,successes,failures,avg_response_time_ms,success_rate");

package/dist/src/retry/RetryManager.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Retry Manager - Manages retry attempts with exponential backoff
+ */
+import type { Logger } from '../../logger.js';
+import type { RetryPolicy, RetryAttempt, RetryStats } from '../types/index.js';
+/**
+ * Retry Manager class for managing retry attempts with configurable backoff strategies
+ */
+export declare class RetryManager {
+    private retryAttempts;
+    private config;
+    private logger;
+    private retryStats;
+    constructor(config: Partial<RetryPolicy> | undefined, logger: Logger);
+    /**
+     * Validate retry policy configuration
+     */
+    private validateConfig;
+    /**
+     * Generate a unique key for session and message combination
+     */
+    private getKey;
+    /**
+     * Check if retry should be attempted
+     */
+    canRetry(sessionID: string, messageID: string): boolean;
+    /**
+     * Get delay for next retry attempt based on strategy
+     */
+    getRetryDelay(sessionID: string, messageID: string): number;
+    /**
+     * Calculate exponential backoff delay
+     */
+    private calculateExponentialDelay;
+    /**
+     * Calculate linear backoff delay
+     */
+    private calculateLinearDelay;
+    /**
+     * Apply jitter to delay
+     */
+    private applyJitter;
+    /**
+     * Record a retry attempt
+     */
+    recordRetry(sessionID: string, messageID: string, modelID: string, delay: number): void;
+    /**
+     * Update retry statistics
+     */
+    private updateStats;
+    /**
+     * Record a successful retry
+     */
+    recordSuccess(sessionID: string, modelID: string): void;
+    /**
+     * Record a failed retry
+     */
+    recordFailure(sessionID: string): void;
+    /**
+     * Get retry statistics for a session
+     */
+    getRetryStats(sessionID: string): RetryStats | null;
+    /**
+     * Get retry attempt information
+     */
+    getRetryAttempt(sessionID: string, messageID: string): RetryAttempt | null;
+    /**
+     * Reset retry state for a specific session/message
+     */
+    reset(sessionID: string, messageID?: string): void;
+    /**
+     * Clean up stale retry entries
+     */
+    cleanupStaleEntries(maxAge?: number): void;
+    /**
+     * Get current retry configuration
+     */
+    getConfig(): RetryPolicy;
+    /**
+     * Update retry configuration
+     */
+    updateConfig(config: Partial<RetryPolicy>): void;
+    /**
+     * Clean up all resources
+     */
+    destroy(): void;
+}

package/dist/src/retry/RetryManager.js

@@ -0,0 +1,289 @@
+/**
+ * Retry Manager - Manages retry attempts with exponential backoff
+ */
+import { DEFAULT_RETRY_POLICY, VALID_RETRY_STRATEGIES } from '../types/index.js';
+/**
+ * Retry Manager class for managing retry attempts with configurable backoff strategies
+ */
+export class RetryManager {
+    retryAttempts;
+    config;
+    logger;
+    retryStats;
+    constructor(config = {}, logger) {
+        this.config = { ...DEFAULT_RETRY_POLICY, ...config };
+        this.logger = logger;
+        this.retryAttempts = new Map();
+        this.retryStats = new Map();
+        // Validate config
+        this.validateConfig();
+    }
+    /**
+     * Validate retry policy configuration
+     */
+    validateConfig() {
+        if (!VALID_RETRY_STRATEGIES.includes(this.config.strategy)) {
+            this.logger.warn('Invalid strategy, using default', { strategy: this.config.strategy });
+            this.config.strategy = DEFAULT_RETRY_POLICY.strategy;
+        }
+        if (this.config.maxRetries < 0) {
+            this.logger.warn('Invalid maxRetries, using default', { maxRetries: this.config.maxRetries });
+            this.config.maxRetries = DEFAULT_RETRY_POLICY.maxRetries;
+        }
+        if (this.config.baseDelayMs < 0) {
+            this.logger.warn('Invalid baseDelayMs, using default', { baseDelayMs: this.config.baseDelayMs });
+            this.config.baseDelayMs = DEFAULT_RETRY_POLICY.baseDelayMs;
+        }
+        if (this.config.maxDelayMs < 0) {
+            this.logger.warn('Invalid maxDelayMs, using default', { maxDelayMs: this.config.maxDelayMs });
+            this.config.maxDelayMs = DEFAULT_RETRY_POLICY.maxDelayMs;
+        }
+        if (this.config.baseDelayMs > this.config.maxDelayMs) {
+            this.logger.warn('baseDelayMs > maxDelayMs, swapping values');
+            [this.config.baseDelayMs, this.config.maxDelayMs] = [this.config.maxDelayMs, this.config.baseDelayMs];
+        }
+        if (this.config.jitterFactor < 0 || this.config.jitterFactor > 1) {
+            this.logger.warn('Invalid jitterFactor, using default', { jitterFactor: this.config.jitterFactor });
+            this.config.jitterFactor = DEFAULT_RETRY_POLICY.jitterFactor;
+        }
+        if (this.config.timeoutMs !== undefined && this.config.timeoutMs < 0) {
+            this.logger.warn('Invalid timeoutMs, ignoring', { timeoutMs: this.config.timeoutMs });
+            this.config.timeoutMs = undefined;
+        }
+    }
+    /**
+     * Generate a unique key for session and message combination
+     */
+    getKey(sessionID, messageID) {
+        return `${sessionID}:${messageID}`;
+    }
+    /**
+     * Check if retry should be attempted
+     */
+    canRetry(sessionID, messageID) {
+        const key = this.getKey(sessionID, messageID);
+        const attempt = this.retryAttempts.get(key);
+        if (!attempt) {
+            return this.config.maxRetries > 0;
+        }
+        // Check timeout
+        if (this.config.timeoutMs) {
+            const elapsed = Date.now() - attempt.startTime;
+            if (elapsed > this.config.timeoutMs) {
+                this.logger.debug('Retry timeout exceeded', { key, elapsed, timeout: this.config.timeoutMs });
+                return false;
+            }
+        }
+        return attempt.attemptCount < this.config.maxRetries;
+    }
+    /**
+     * Get delay for next retry attempt based on strategy
+     */
+    getRetryDelay(sessionID, messageID) {
+        const key = this.getKey(sessionID, messageID);
+        const attempt = this.retryAttempts.get(key) || {
+            attemptCount: 0,
+            startTime: Date.now(),
+            delays: [],
+            lastAttemptTime: 0,
+            modelIDs: [],
+        };
+        let delay;
+        switch (this.config.strategy) {
+            case "exponential":
+                delay = this.calculateExponentialDelay(attempt.attemptCount);
+                break;
+            case "linear":
+                delay = this.calculateLinearDelay(attempt.attemptCount);
+                break;
+            case "immediate":
+            default:
+                delay = 0;
+                break;
+        }
+        // Apply jitter if enabled
+        if (this.config.jitterEnabled && delay > 0) {
+            delay = this.applyJitter(delay);
+        }
+        return delay;
+    }
+    /**
+     * Calculate exponential backoff delay
+     */
+    calculateExponentialDelay(attemptCount) {
+        const exponentialDelay = this.config.baseDelayMs * Math.pow(2, attemptCount);
+        return Math.min(exponentialDelay, this.config.maxDelayMs);
+    }
+    /**
+     * Calculate linear backoff delay
+     */
+    calculateLinearDelay(attemptCount) {
+        const linearDelay = this.config.baseDelayMs * (attemptCount + 1);
+        return Math.min(linearDelay, this.config.maxDelayMs);
+    }
+    /**
+     * Apply jitter to delay
+     */
+    applyJitter(delay) {
+        const jitterAmount = delay * this.config.jitterFactor;
+        const randomJitter = (Math.random() * 2 - 1) * jitterAmount; // -jitter to +jitter
+        return Math.max(0, delay + randomJitter);
+    }
+    /**
+     * Record a retry attempt
+     */
+    recordRetry(sessionID, messageID, modelID, delay) {
+        const key = this.getKey(sessionID, messageID);
+        const now = Date.now();
+        let attempt = this.retryAttempts.get(key);
+        if (!attempt) {
+            attempt = {
+                attemptCount: 0,
+                startTime: now,
+                delays: [],
+                lastAttemptTime: 0,
+                modelIDs: [],
+            };
+            this.retryAttempts.set(key, attempt);
+        }
+        attempt.attemptCount++;
+        attempt.delays.push(delay);
+        attempt.lastAttemptTime = now;
+        attempt.modelIDs.push(modelID);
+        // Update stats
+        this.updateStats(sessionID, modelID, delay, now);
+        this.logger.debug('Retry attempt recorded', {
+            key,
+            attemptCount: attempt.attemptCount,
+            delay,
+            modelID,
+        });
+    }
+    /**
+     * Update retry statistics
+     */
+    updateStats(sessionID, modelID, delay, now) {
+        let stats = this.retryStats.get(sessionID);
+        if (!stats) {
+            stats = {
+                totalRetries: 0,
+                successful: 0,
+                failed: 0,
+                averageDelay: 0,
+                byModel: new Map(),
+                startTime: now,
+                lastAttemptTime: now,
+            };
+            this.retryStats.set(sessionID, stats);
+        }
+        stats.totalRetries++;
+        stats.lastAttemptTime = now;
+        // Update average delay
+        const totalDelay = stats.averageDelay * (stats.totalRetries - 1);
+        stats.averageDelay = (totalDelay + delay) / stats.totalRetries;
+        // Update model-specific stats
+        let modelStats = stats.byModel.get(modelID);
+        if (!modelStats) {
+            modelStats = { attempts: 0, successes: 0 };
+            stats.byModel.set(modelID, modelStats);
+        }
+        modelStats.attempts++;
+    }
+    /**
+     * Record a successful retry
+     */
+    recordSuccess(sessionID, modelID) {
+        const stats = this.retryStats.get(sessionID);
+        if (stats) {
+            stats.successful++;
+            const modelStats = stats.byModel.get(modelID);
+            if (modelStats) {
+                modelStats.successes++;
+            }
+        }
+    }
+    /**
+     * Record a failed retry
+     */
+    recordFailure(sessionID) {
+        const stats = this.retryStats.get(sessionID);
+        if (stats) {
+            stats.failed++;
+        }
+    }
+    /**
+     * Get retry statistics for a session
+     */
+    getRetryStats(sessionID) {
+        return this.retryStats.get(sessionID) || null;
+    }
+    /**
+     * Get retry attempt information
+     */
+    getRetryAttempt(sessionID, messageID) {
+        const key = this.getKey(sessionID, messageID);
+        return this.retryAttempts.get(key) || null;
+    }
+    /**
+     * Reset retry state for a specific session/message
+     */
+    reset(sessionID, messageID) {
+        if (messageID) {
+            const key = this.getKey(sessionID, messageID);
+            this.retryAttempts.delete(key);
+        }
+        else {
+            // Reset all entries for this session
+            for (const [key] of this.retryAttempts.entries()) {
+                if (key.startsWith(sessionID + ':')) {
+                    this.retryAttempts.delete(key);
+                }
+            }
+            this.retryStats.delete(sessionID);
+        }
+        this.logger.debug('Retry state reset', { sessionID, messageID });
+    }
+    /**
+     * Clean up stale retry entries
+     */
+    cleanupStaleEntries(maxAge = 3600000) {
+        const now = Date.now();
+        let cleanedCount = 0;
+        for (const [key, attempt] of this.retryAttempts.entries()) {
+            if (now - attempt.lastAttemptTime > maxAge) {
+                this.retryAttempts.delete(key);
+                cleanedCount++;
+            }
+        }
+        for (const [sessionID, stats] of this.retryStats.entries()) {
+            if (now - stats.lastAttemptTime > maxAge) {
+                this.retryStats.delete(sessionID);
+                cleanedCount++;
+            }
+        }
+        if (cleanedCount > 0) {
+            this.logger.debug('Cleaned up stale retry entries', { count: cleanedCount });
+        }
+    }
+    /**
+     * Get current retry configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update retry configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        this.validateConfig();
+        this.logger.debug('Retry configuration updated', { config: this.config });
+    }
+    /**
+     * Clean up all resources
+     */
+    destroy() {
+        this.retryAttempts.clear();
+        this.retryStats.clear();
+    }
+}

package/dist/src/types/index.d.ts

@@ -17,6 +17,22 @@ export interface FallbackModel {
  * - "retry-last": Try the last model once, then reset to first on next prompt
  */
 export type FallbackMode = "cycle" | "stop" | "retry-last";
+/**
+ * Retry strategy type
+ */
+export type RetryStrategy = "immediate" | "exponential" | "linear" | "custom";
+/**
+ * Retry policy configuration
+ */
+export interface RetryPolicy {
+    maxRetries: number;
+    strategy: RetryStrategy;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterEnabled: boolean;
+    jitterFactor: number;
+    timeoutMs?: number;
+}
 /**
  * Metrics output configuration
  */
@@ -43,6 +59,7 @@ export interface PluginConfig {
     fallbackMode: FallbackMode;
     maxSubagentDepth?: number;
     enableSubagentFallback?: boolean;
+    retryPolicy?: RetryPolicy;
     log?: LogConfig;
     metrics?: MetricsConfig;
 }
@@ -50,6 +67,31 @@ export interface PluginConfig {
  * Fallback state for tracking progress
  */
 export type FallbackState = "none" | "in_progress" | "completed";
+/**
+ * Retry attempt information
+ */
+export interface RetryAttempt {
+    attemptCount: number;
+    startTime: number;
+    delays: number[];
+    lastAttemptTime: number;
+    modelIDs: string[];
+}
+/**
+ * Retry statistics for tracking retry behavior
+ */
+export interface RetryStats {
+    totalRetries: number;
+    successful: number;
+    failed: number;
+    averageDelay: number;
+    byModel: Map<string, {
+        attempts: number;
+        successes: number;
+    }>;
+    startTime: number;
+    lastAttemptTime: number;
+}
 /**
  * Subagent session information
  */
@@ -141,6 +183,19 @@ export interface ModelPerformanceMetrics {
     failures: number;
     averageResponseTime?: number;
 }
+/**
+ * Retry metrics
+ */
+export interface RetryMetrics {
+    total: number;
+    successful: number;
+    failed: number;
+    averageDelay: number;
+    byModel: Map<string, {
+        attempts: number;
+        successes: number;
+    }>;
+}
 /**
  * Complete metrics data
  */
@@ -153,6 +208,7 @@ export interface MetricsData {
         averageDuration: number;
         byTargetModel: Map<string, FallbackTargetMetrics>;
     };
+    retries: RetryMetrics;
     modelPerformance: Map<string, ModelPerformanceMetrics>;
     startedAt: number;
     generatedAt: number;
@@ -180,6 +236,29 @@ export type MessagePart = TextPart | FilePart;
  * SDK-compatible message part input
  */
 export type SDKMessagePartInput = TextPartInput | FilePartInput;
+/**
+ * Toast variant type
+ */
+export type ToastVariant = "info" | "success" | "warning" | "error";
+/**
+ * Toast body content
+ */
+export interface ToastBody {
+    title: string;
+    message: string;
+    variant: ToastVariant;
+    duration?: number;
+}
+/**
+ * Toast message structure
+ */
+export interface ToastMessage {
+    body?: ToastBody;
+    title?: string;
+    message?: string;
+    variant?: ToastVariant;
+    duration?: number;
+}
 /**
  * OpenCode client interface
  */
@@ -217,7 +296,7 @@ export type OpenCodeClient = {
         }) => Promise<unknown>;
     };
     tui?: {
-        showToast: (toast: any) => Promise<any>;
+        showToast: (toast: ToastMessage) => Promise<unknown>;
     };
 };
 /**
@@ -231,10 +310,18 @@ export type PluginContext = {
  * Default fallback models
  */
 export declare const DEFAULT_FALLBACK_MODELS: FallbackModel[];
+/**
+ * Default retry policy
+ */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
 /**
  * Valid fallback modes
  */
 export declare const VALID_FALLBACK_MODES: FallbackMode[];
+/**
+ * Valid retry strategies
+ */
+export declare const VALID_RETRY_STRATEGIES: RetryStrategy[];
 /**
  * Valid reset intervals
  */

package/dist/src/types/index.js

@@ -12,10 +12,25 @@ export const DEFAULT_FALLBACK_MODELS = [
     { providerID: "google", modelID: "gemini-2.5-pro" },
     { providerID: "google", modelID: "gemini-2.5-flash" },
 ];
+/**
+ * Default retry policy
+ */
+export const DEFAULT_RETRY_POLICY = {
+    maxRetries: 3,
+    strategy: "immediate",
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    jitterEnabled: false,
+    jitterFactor: 0.1,
+};
 /**
  * Valid fallback modes
  */
 export const VALID_FALLBACK_MODES = ["cycle", "stop", "retry-last"];
+/**
+ * Valid retry strategies
+ */
+export const VALID_RETRY_STRATEGIES = ["immediate", "exponential", "linear", "custom"];
 /**
  * Valid reset intervals
  */

package/dist/src/utils/config.d.ts

@@ -9,7 +9,7 @@ export declare const DEFAULT_CONFIG: PluginConfig;
 /**
  * Validate configuration values
  */
-export declare function validateConfig(config: any): PluginConfig;
+export declare function validateConfig(config: Partial<PluginConfig>): PluginConfig;
 /**
  * Load and validate config from file paths
  */

package/dist/src/utils/config.js

@@ -3,7 +3,7 @@
  */
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
-import { DEFAULT_FALLBACK_MODELS, VALID_FALLBACK_MODES, VALID_RESET_INTERVALS, } from '../types/index.js';
+import { DEFAULT_FALLBACK_MODELS, VALID_FALLBACK_MODES, VALID_RESET_INTERVALS, DEFAULT_RETRY_POLICY, VALID_RETRY_STRATEGIES, } from '../types/index.js';
 /**
  * Default plugin configuration
  */
@@ -12,6 +12,7 @@ export const DEFAULT_CONFIG = {
     cooldownMs: 60 * 1000,
     enabled: true,
     fallbackMode: "cycle",
+    retryPolicy: DEFAULT_RETRY_POLICY,
     log: {
         level: "warn",
         format: "simple",
@@ -32,11 +33,17 @@ export const DEFAULT_CONFIG = {
 export function validateConfig(config) {
     const mode = config.fallbackMode;
     const resetInterval = config.metrics?.resetInterval;
+    const strategy = config.retryPolicy?.strategy;
     return {
         ...DEFAULT_CONFIG,
         ...config,
         fallbackModels: config.fallbackModels || DEFAULT_CONFIG.fallbackModels,
-        fallbackMode: VALID_FALLBACK_MODES.includes(mode) ? mode : DEFAULT_CONFIG.fallbackMode,
+        fallbackMode: mode && VALID_FALLBACK_MODES.includes(mode) ? mode : DEFAULT_CONFIG.fallbackMode,
+        retryPolicy: config.retryPolicy ? {
+            ...DEFAULT_CONFIG.retryPolicy,
+            ...config.retryPolicy,
+            strategy: strategy && VALID_RETRY_STRATEGIES.includes(strategy) ? strategy : DEFAULT_CONFIG.retryPolicy.strategy,
+        } : DEFAULT_CONFIG.retryPolicy,
         log: config.log ? { ...DEFAULT_CONFIG.log, ...config.log } : DEFAULT_CONFIG.log,
         metrics: config.metrics ? {
             ...DEFAULT_CONFIG.metrics,
@@ -45,7 +52,7 @@ export function validateConfig(config) {
                 ...DEFAULT_CONFIG.metrics.output,
                 ...config.metrics.output,
             } : DEFAULT_CONFIG.metrics.output,
-            resetInterval: VALID_RESET_INTERVALS.includes(resetInterval) ? resetInterval : DEFAULT_CONFIG.metrics.resetInterval,
+            resetInterval: resetInterval && VALID_RESET_INTERVALS.includes(resetInterval) ? resetInterval : DEFAULT_CONFIG.metrics.resetInterval,
         } : DEFAULT_CONFIG.metrics,
     };
 }

package/dist/src/utils/helpers.d.ts

@@ -1,7 +1,7 @@
 /**
  * General utility functions
  */
-import type { MessagePart, SDKMessagePartInput } from '../types/index.js';
+import type { MessagePart, SDKMessagePartInput, ToastMessage, OpenCodeClient } from '../types/index.js';
 export declare const DEDUP_WINDOW_MS = 5000;
 export declare const STATE_TIMEOUT_MS = 30000;
 /**
@@ -23,7 +23,7 @@ export declare function convertPartsToSDKFormat(parts: MessagePart[]): SDKMessag
 /**
  * Extract toast message properties with fallback values
  */
-export declare function getToastMessage(toast: any): {
+export declare function getToastMessage(toast: ToastMessage): {
     title: string;
     message: string;
     variant: string;
@@ -31,4 +31,4 @@ export declare function getToastMessage(toast: any): {
 /**
  * Safely show toast, falling back to console logging if TUI is missing or fails
  */
-export declare const safeShowToast: (client: any, toast: any) => Promise<void>;
+export declare const safeShowToast: (client: OpenCodeClient, toast: ToastMessage) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azumag/opencode-rate-limit-fallback",
-  "version": "1.24.0",
+  "version": "1.27.0",
   "description": "OpenCode plugin that automatically switches to fallback models when rate limited",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",