@azumag/opencode-rate-limit-fallback 1.50.0 → 1.57.0

package/README.md

@@ -18,10 +18,12 @@ OpenCode plugin that automatically switches to fallback models when rate limited
   - 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
- - **Circuit breaker pattern** to prevent cascading failures from consistently failing models
- - **Metrics collection** to track rate limits, fallbacks, and model performance
+  - Subagent session support with automatic fallback propagation to parent sessions
+  - Configurable maximum subagent nesting depth
+  - **Circuit breaker pattern** to prevent cascading failures from consistently failing models
+  - **Metrics collection** to track rate limits, fallbacks, and model performance
+   - **Configuration hot reload** - Reload configuration changes without restarting OpenCode
+   - **Dynamic fallback model prioritization** - Automatically reorders models based on success rate, response time, and usage frequency
 
 ## Installation
 
@@ -98,6 +100,12 @@ Create a configuration file at one of these locations:
     "recoveryTimeoutMs": 60000,
     "halfOpenMaxCalls": 1,
     "successThreshold": 2
+  },
+  "configReload": {
+    "enabled": true,
+    "watchFile": true,
+    "debounceMs": 1000,
+    "notifyOnReload": true
   }
 }
 ```
@@ -111,9 +119,99 @@ Create a configuration file at one of these locations:
   | `fallbackMode` | string | `"cycle"` | Behavior when all models are exhausted (see below) |
   | `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) |
-  | `circuitBreaker` | object | See below | Circuit breaker configuration (see below) |
+   | `enableSubagentFallback` | boolean | `true` | Enable/disable fallback for subagent sessions |
+   | `retryPolicy` | object | See below | Retry policy configuration (see below) |
+   | `circuitBreaker` | object | See below | Circuit breaker configuration (see below) |
+   | `configReload` | object | See below | Configuration hot reload settings (see below) |
+   | `dynamicPrioritization` | object | See below | Dynamic prioritization settings (see below) |
+
+### Dynamic Prioritization
+
+The dynamic prioritization feature automatically reorders your fallback models based on their performance metrics, helping you use the most reliable and fastest models first.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable dynamic prioritization |
+| `updateInterval` | number | `10` | Number of requests between score updates (performance optimization) |
+| `successRateWeight` | number | `0.6` | Weight for success rate (0-1) |
+| `responseTimeWeight` | number | `0.3` | Weight for response time (0-1) |
+| `recentUsageWeight` | number | `0.1` | Weight for recent usage frequency (0-1) |
+| `minSamples` | number | `3` | Minimum samples before using dynamic ordering |
+| `maxHistorySize` | number | `100` | Maximum history size for usage tracking |
+
+#### How It Works
+
+Dynamic prioritization calculates a score for each model based on three factors:
+
+1. **Success Rate** (default weight: 0.6)
+   - Based on health score from HealthTracker
+   - Higher success rate = higher score
+
+2. **Response Time** (default weight: 0.3)
+   - Faster response times get higher scores
+   - Thresholds: <500ms (excellent), >5000ms (poor)
+
+3. **Recent Usage** (default weight: 0.1)
+   - Recently used models get a small boost
+   - Decays over 24 hours
+
+The final score is calculated as:
+```
+score = (healthScore / 100 * successRateWeight) +
+        (normalizedResponseTime * responseTimeWeight) +
+        (normalizedRecentUsage * recentUsageWeight)
+```
+
+#### Learning Phase
+
+- Uses static ordering until `minSamples` models have sufficient data
+- Default: 3 models need at least 3 requests each
+- Ensures reliable data before reordering
+
+#### Configuration Examples
+
+**Enable with defaults:**
+```json
+{
+  "dynamicPrioritization": {
+    "enabled": true
+  }
+}
+```
+
+**Full configuration:**
+```json
+{
+  "dynamicPrioritization": {
+    "enabled": true,
+    "updateInterval": 10,
+    "successRateWeight": 0.6,
+    "responseTimeWeight": 0.3,
+    "recentUsageWeight": 0.1,
+    "minSamples": 3,
+    "maxHistorySize": 100
+  }
+}
+```
+
+**Prioritize speed over reliability:**
+```json
+{
+  "dynamicPrioritization": {
+    "enabled": true,
+    "successRateWeight": 0.4,
+    "responseTimeWeight": 0.5,
+    "recentUsageWeight": 0.1
+  }
+}
+```
+
+#### Important Notes
+
+- **Disabled by default**: Set `enabled: true` to activate
+- **Requires health tracking**: Uses HealthTracker data for success rates
+- **Weights must sum to ~1.0**: Ensure optimal scoring behavior
+- **Hot reload supported**: Can be enabled/disabled without restarting OpenCode
 
 ### Git Worktree Support
 
@@ -249,6 +347,75 @@ The circuit breaker maintains three states for each model:
 | Production | 5 | 60000 | 1 |
 | High Availability | 10 | 30000 | 2 |
 
+### Configuration Hot Reload
+
+The plugin supports automatic configuration reloading without requiring you to restart OpenCode. When you edit your configuration file, the plugin detects the changes and applies them seamlessly.
+
+#### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `configReload.enabled` | boolean | `false` | Enable/disable configuration hot reload |
+| `configReload.watchFile` | boolean | `true` | Watch config file for changes |
+| `configReload.debounceMs` | number | `1000` | Debounce delay (ms) to handle multiple file writes |
+| `configReload.notifyOnReload` | boolean | `true` | Show toast notifications on reload |
+
+#### How It Works
+
+1. **File Watching**: When enabled, the plugin watches your configuration file for changes
+2. **Debouncing**: Multiple file writes (e.g., from editors) are debounced to prevent unnecessary reloads
+3. **Validation**: New configuration is validated before applying it
+4. **Graceful Application**: If valid, the new configuration is applied without interrupting active sessions
+5. **Toast Notifications**: You receive toast notifications for successful or failed reloads
+
+#### Behavior
+
+**What gets reloaded:**
+- Fallback model list
+- Cooldown periods
+- Fallback mode
+- Retry policies
+- Circuit breaker settings
+- Metrics configuration
+- Log configuration
+- Health tracking settings
+
+**What doesn't change:**
+- Active session states
+- Rate-limited model tracking
+- Health tracking data
+- Metrics history
+
+#### Configuration Examples
+
+**Enable hot reload:**
+```json
+{
+  "configReload": {
+    "enabled": true
+  }
+}
+```
+
+**Full configuration:**
+```json
+{
+  "configReload": {
+    "enabled": true,
+    "watchFile": true,
+    "debounceMs": 1000,
+    "notifyOnReload": true
+  }
+}
+```
+
+#### Important Notes
+
+- **Disabled by default**: Set `configReload.enabled: true` to activate this feature
+- **Valid configs only**: Invalid configurations are rejected, and old config is preserved
+- **No restart needed**: You can experiment with different configurations without restarting OpenCode
+- **Session preservation**: Active sessions continue working during reload
+
 ### ⚠️ Important: Configuration Required
 
 **As of v1.43.0, this plugin requires explicit configuration.**
@@ -395,11 +562,12 @@ When OpenCode uses subagents (e.g., for complex tasks requiring specialized agen
 ## Metrics
 
  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)
- - **Circuit breaker statistics** (state transitions, open/closed counts)
+  - 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)
+  - **Circuit breaker statistics** (state transitions, open/closed counts)
+  - **Dynamic prioritization statistics** (enabled status, reorder count, models with scores)
 
 ### Metrics Configuration
 
@@ -480,19 +648,25 @@ Model Performance:
      Avg Response: 0.85s
      Success Rate: 90.0%
 
- Circuit Breaker:
- ----------------------------------------
-   anthropic/claude-3-5-sonnet-20250514:
-     State: OPEN
-     Failures: 5
-     Successes: 0
-     State Transitions: 2
-   google/gemini-2.5-pro:
-     State: CLOSED
-     Failures: 2
-     Successes: 8
-     State Transitions: 3
- ```
+  Circuit Breaker:
+  ----------------------------------------
+    anthropic/claude-3-5-sonnet-20250514:
+      State: OPEN
+      Failures: 5
+      Successes: 0
+      State Transitions: 2
+    google/gemini-2.5-pro:
+      State: CLOSED
+      Failures: 2
+      Successes: 8
+      State Transitions: 3
+
+  Dynamic Prioritization:
+  ----------------------------------------
+    Enabled: Yes
+    Reorders: 5
+    Models with dynamic scores: 3
+  ```
 
  **JSON** (machine-readable):
 ```json
@@ -554,12 +728,17 @@ Model Performance:
        "failures": 2,
        "successes": 8,
        "stateTransitions": 3
-     }
-   },
-   "startedAt": 1739148000000,
-   "generatedAt": 1739149800000
- }
- ```
+      }
+    },
+    "dynamicPrioritization": {
+      "enabled": true,
+      "reorders": 5,
+      "modelsWithDynamicScores": 3
+    },
+    "startedAt": 1739148000000,
+    "generatedAt": 1739149800000
+  }
+  ```
 
 **CSV** (spreadsheet-friendly):
 ```
@@ -584,11 +763,15 @@ google/gemini-2.5-pro,7,5,71.4
  model,requests,successes,failures,avg_response_time_ms,success_rate
  google/gemini-2.5-pro,10,9,1,850,90.0
 
- === CIRCUIT_BREAKER ===
- model,current_state,failures,successes,state_transitions
- anthropic/claude-3-5-sonnet-20250514,OPEN,5,0,2
- google/gemini-2.5-pro,CLOSED,2,8,3
- ```
+  === CIRCUIT_BREAKER ===
+  model,current_state,failures,successes,state_transitions
+  anthropic/claude-3-5-sonnet-20250514,OPEN,5,0,2
+  google/gemini-2.5-pro,CLOSED,2,8,3
+
+  === DYNAMIC_PRIORITIZATION ===
+  enabled,reorders,models_with_dynamic_scores
+  Yes,5,3
+  ```
 
 ## License
 

package/dist/src/config/Validator.js

@@ -466,6 +466,100 @@ export class ConfigValidator {
                 }
             }
         }
+        // Validate dynamicPrioritization
+        if (config.dynamicPrioritization) {
+            if (typeof config.dynamicPrioritization !== 'object') {
+                errors.push({
+                    path: 'dynamicPrioritization',
+                    message: 'dynamicPrioritization must be an object',
+                    severity: 'error',
+                    value: config.dynamicPrioritization,
+                });
+            }
+            else {
+                if (config.dynamicPrioritization.enabled !== undefined && typeof config.dynamicPrioritization.enabled !== 'boolean') {
+                    errors.push({
+                        path: 'dynamicPrioritization.enabled',
+                        message: 'enabled must be a boolean',
+                        severity: 'error',
+                        value: config.dynamicPrioritization.enabled,
+                    });
+                }
+                if (config.dynamicPrioritization.updateInterval !== undefined) {
+                    if (typeof config.dynamicPrioritization.updateInterval !== 'number' || config.dynamicPrioritization.updateInterval < 1) {
+                        errors.push({
+                            path: 'dynamicPrioritization.updateInterval',
+                            message: 'updateInterval must be a positive number',
+                            severity: 'error',
+                            value: config.dynamicPrioritization.updateInterval,
+                        });
+                    }
+                }
+                if (config.dynamicPrioritization.successRateWeight !== undefined) {
+                    if (typeof config.dynamicPrioritization.successRateWeight !== 'number' || config.dynamicPrioritization.successRateWeight < 0 || config.dynamicPrioritization.successRateWeight > 1) {
+                        errors.push({
+                            path: 'dynamicPrioritization.successRateWeight',
+                            message: 'successRateWeight must be a number between 0 and 1',
+                            severity: 'error',
+                            value: config.dynamicPrioritization.successRateWeight,
+                        });
+                    }
+                }
+                if (config.dynamicPrioritization.responseTimeWeight !== undefined) {
+                    if (typeof config.dynamicPrioritization.responseTimeWeight !== 'number' || config.dynamicPrioritization.responseTimeWeight < 0 || config.dynamicPrioritization.responseTimeWeight > 1) {
+                        errors.push({
+                            path: 'dynamicPrioritization.responseTimeWeight',
+                            message: 'responseTimeWeight must be a number between 0 and 1',
+                            severity: 'error',
+                            value: config.dynamicPrioritization.responseTimeWeight,
+                        });
+                    }
+                }
+                if (config.dynamicPrioritization.recentUsageWeight !== undefined) {
+                    if (typeof config.dynamicPrioritization.recentUsageWeight !== 'number' || config.dynamicPrioritization.recentUsageWeight < 0 || config.dynamicPrioritization.recentUsageWeight > 1) {
+                        errors.push({
+                            path: 'dynamicPrioritization.recentUsageWeight',
+                            message: 'recentUsageWeight must be a number between 0 and 1',
+                            severity: 'error',
+                            value: config.dynamicPrioritization.recentUsageWeight,
+                        });
+                    }
+                }
+                // Validate that weights sum to approximately 1.0
+                const successRateWeight = config.dynamicPrioritization.successRateWeight ?? 0.6;
+                const responseTimeWeight = config.dynamicPrioritization.responseTimeWeight ?? 0.3;
+                const recentUsageWeight = config.dynamicPrioritization.recentUsageWeight ?? 0.1;
+                const totalWeight = successRateWeight + responseTimeWeight + recentUsageWeight;
+                if (Math.abs(totalWeight - 1.0) > 0.1) {
+                    warnings.push({
+                        path: 'dynamicPrioritization',
+                        message: `Weights sum to ${totalWeight.toFixed(2)}, which is significantly different from 1.0. This may affect prioritization behavior.`,
+                        severity: 'warning',
+                        value: { successRateWeight, responseTimeWeight, recentUsageWeight, totalWeight },
+                    });
+                }
+                if (config.dynamicPrioritization.minSamples !== undefined) {
+                    if (typeof config.dynamicPrioritization.minSamples !== 'number' || config.dynamicPrioritization.minSamples < 1) {
+                        errors.push({
+                            path: 'dynamicPrioritization.minSamples',
+                            message: 'minSamples must be a positive number',
+                            severity: 'error',
+                            value: config.dynamicPrioritization.minSamples,
+                        });
+                    }
+                }
+                if (config.dynamicPrioritization.maxHistorySize !== undefined) {
+                    if (typeof config.dynamicPrioritization.maxHistorySize !== 'number' || config.dynamicPrioritization.maxHistorySize < 1) {
+                        errors.push({
+                            path: 'dynamicPrioritization.maxHistorySize',
+                            message: 'maxHistorySize must be a positive number',
+                            severity: 'error',
+                            value: config.dynamicPrioritization.maxHistorySize,
+                        });
+                    }
+                }
+            }
+        }
         // Log warnings if enabled
         if (logWarnings && warnings.length > 0 && this.logger) {
             for (const warning of warnings) {

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

@@ -78,3 +78,25 @@ export declare const DEFAULT_CONFIG_RELOAD_CONFIG: {
     readonly debounceMs: 1000;
     readonly notifyOnReload: true;
 };
+/**
+ * Default dynamic prioritization configuration
+ */
+export declare const DEFAULT_DYNAMIC_PRIORITIZATION_CONFIG: {
+    readonly enabled: false;
+    readonly updateInterval: 10;
+    readonly successRateWeight: 0.6;
+    readonly responseTimeWeight: 0.3;
+    readonly recentUsageWeight: 0.1;
+    readonly minSamples: 3;
+    readonly maxHistorySize: 100;
+};
+/**
+ * Default error pattern learning configuration
+ */
+export declare const DEFAULT_ERROR_PATTERN_LEARNING_CONFIG: {
+    readonly enableLearning: false;
+    readonly autoApproveThreshold: 0.8;
+    readonly maxLearnedPatterns: 20;
+    readonly minErrorFrequency: 3;
+    readonly learningWindowMs: number;
+};

package/dist/src/config/defaults.js

@@ -101,3 +101,31 @@ export const DEFAULT_CONFIG_RELOAD_CONFIG = {
     debounceMs: 1000,
     notifyOnReload: true,
 };
+// ============================================================================
+// Dynamic Prioritization Defaults
+// ============================================================================
+/**
+ * Default dynamic prioritization configuration
+ */
+export const DEFAULT_DYNAMIC_PRIORITIZATION_CONFIG = {
+    enabled: false,
+    updateInterval: 10,
+    successRateWeight: 0.6,
+    responseTimeWeight: 0.3,
+    recentUsageWeight: 0.1,
+    minSamples: 3,
+    maxHistorySize: 100,
+};
+// ============================================================================
+// Error Pattern Learning Defaults
+// ============================================================================
+/**
+ * Default error pattern learning configuration
+ */
+export const DEFAULT_ERROR_PATTERN_LEARNING_CONFIG = {
+    enableLearning: false,
+    autoApproveThreshold: 0.8,
+    maxLearnedPatterns: 20,
+    minErrorFrequency: 3,
+    learningWindowMs: 24 * 60 * 60 * 1000, // 24 hours
+};

package/dist/src/dynamic/DynamicPrioritizer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Dynamic Prioritizer
+ * Dynamically prioritizes fallback models based on performance metrics
+ */
+import type { Logger } from '../../logger.js';
+import type { FallbackModel, DynamicPrioritizationConfig } from '../types/index.js';
+import type { HealthTracker } from '../health/HealthTracker.js';
+import type { MetricsManager } from '../metrics/MetricsManager.js';
+/**
+ * Dynamic Prioritizer class for calculating dynamic model scores
+ */
+export declare class DynamicPrioritizer {
+    private config;
+    private healthTracker;
+    private logger;
+    private metricsManager?;
+    private modelScores;
+    private modelUsageHistory;
+    private requestCount;
+    constructor(config: DynamicPrioritizationConfig, healthTracker: HealthTracker, logger: Logger, metricsManager?: MetricsManager);
+    /**
+     * Record usage of a model for tracking recent activity
+     */
+    recordUsage(providerID: string, modelID: string): void;
+    /**
+     * Calculate dynamic score for a model
+     * Score is 0-1, higher is better
+     */
+    calculateScore(providerID: string, modelID: string): number;
+    /**
+     * Get prioritized models based on dynamic scores
+     * Returns models sorted by score (highest first)
+     */
+    getPrioritizedModels(candidates: FallbackModel[]): FallbackModel[];
+    /**
+     * Check if dynamic ordering should be used
+     * Returns true if dynamic prioritization is enabled and we have enough data for reliable ordering
+     */
+    shouldUseDynamicOrdering(): boolean;
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig: DynamicPrioritizationConfig): void;
+    /**
+     * Get current scores for all tracked models
+     */
+    getAllScores(): Map<string, number>;
+    /**
+     * Check if dynamic prioritization is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get number of models with calculated scores
+     */
+    getModelsWithDynamicScores(): number;
+    /**
+     * Update metrics with current dynamic prioritization state
+     */
+    updateMetrics(): void;
+    /**
+     * Reset all scores and usage history
+     */
+    reset(): void;
+    /**
+     * Normalize response time (inverse - faster is better)
+     * Returns 0-1, higher is better
+     */
+    private normalizeResponseTime;
+    /**
+     * Calculate recent usage score
+     * Returns 0-1, higher for more recent usage
+     */
+    private calculateRecentUsageScore;
+}