@azumag/opencode-rate-limit-fallback 1.40.0 → 1.49.0

package/README.md

@@ -51,10 +51,15 @@ Restart OpenCode to load the plugin.
 
 Create a configuration file at one of these locations:
 
-- `~/.opencode/rate-limit-fallback.json` (recommended)
-- `~/.config/opencode/rate-limit-fallback.json`
-- `<project>/.opencode/rate-limit-fallback.json`
-- `<project>/rate-limit-fallback.json`
+**Config file search order (highest to lowest priority):**
+1. `<worktree>/.opencode/rate-limit-fallback.json`
+2. `<worktree>/rate-limit-fallback.json`
+3. `<project>/.opencode/rate-limit-fallback.json`
+4. `<project>/rate-limit-fallback.json`
+5. `~/.opencode/rate-limit-fallback.json` (recommended for most users)
+6. `~/.config/opencode/rate-limit-fallback.json`
+
+> **Note**: Project-local and worktree configs (1-4) take precedence over global configs (5-6).
 
 ### Example Configuration
 
@@ -99,16 +104,39 @@ Create a configuration file at one of these locations:
 
 ### Configuration Options
 
- | Option | Type | Default | Description |
- |--------|------|---------|-------------|
- | `enabled` | boolean | `true` | Enable/disable the plugin |
- | `cooldownMs` | number | `60000` | Cooldown period (ms) before retrying a rate-limited model |
- | `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) |
+  | Option | Type | Default | Description |
+  |--------|------|---------|-------------|
+  | `enabled` | boolean | `true` | Enable/disable the plugin |
+  | `cooldownMs` | number | `60000` | Cooldown period (ms) before retrying a rate-limited model |
+  | `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) |
+
+### Git Worktree Support
+
+When using git worktrees, the plugin searches for config files in the worktree directory first, before the project directory. This allows you to have different fallback configurations for different worktrees.
+
+**Example structure:**
+```
+my-repo/
+  .git/
+  .opencode/rate-limit-fallback.json  (project-level config)
+  my-worktree/  (worktree)
+    .opencode/rate-limit-fallback.json  (worktree-specific, higher priority)
+```
+
+**Config file search order with worktrees (highest to lowest priority):**
+1. `<worktree>/.opencode/rate-limit-fallback.json`
+2. `<worktree>/rate-limit-fallback.json`
+3. `<project>/.opencode/rate-limit-fallback.json`
+4. `<project>/rate-limit-fallback.json`
+5. `~/.opencode/rate-limit-fallback.json`
+6. `~/.config/opencode/rate-limit-fallback.json`
+
+> **Note**: If you're using git worktrees and want different configurations per worktree, create config files in the worktree directories (locations 1-2). Otherwise, a single project-level or global config is sufficient.
 
 ### Fallback Modes
 
@@ -221,13 +249,119 @@ The circuit breaker maintains three states for each model:
 | Production | 5 | 60000 | 1 |
 | High Availability | 10 | 30000 | 2 |
 
- ### Default Fallback Models
+### ⚠️ Important: Configuration Required
+
+**As of v1.43.0, this plugin requires explicit configuration.**
+
+The default fallback models array is empty, meaning no fallback behavior will occur until you create a configuration file.
+
+**You must create a config file at one of these locations:**
+
+**Config file search order (highest to lowest priority):**
+1. `<worktree>/.opencode/rate-limit-fallback.json`
+2. `<worktree>/rate-limit-fallback.json`
+3. `<project>/.opencode/rate-limit-fallback.json`
+4. `<project>/rate-limit-fallback.json`
+5. `~/.opencode/rate-limit-fallback.json` (recommended for most users)
+6. `~/.config/opencode/rate-limit-fallback.json`
+
+> **Note**: Project-local and worktree configs (1-4) take precedence over global configs (5-6).
+
+**If no config file is found, the plugin will:**
+- Log a warning message
+- Not perform any fallback operations
+- Continue functioning normally with rate-limited models
+
+**Minimum working configuration:**
+```json
+{
+  "fallbackModels": [
+    { "providerID": "anthropic", "modelID": "claude-3-5-sonnet-20250514" }
+  ]
+}
+```
+
+## Migrating from v1.42.x or earlier
+
+### Breaking Change: Empty Default Models
+
+**What changed?**
+- v1.43.0 removed the default fallback models
+- You must now explicitly configure your fallback models
+- The plugin will not work without a configuration file
+
+**Why was this changed?**
+- To prevent unintended model usage (e.g., Gemini when not wanted)
+- To make configuration errors obvious immediately
+- To give users explicit control over which models to use
+
+### How to Migrate
+
+1. **Create a config file** at one of the locations listed above
+2. **Add your desired fallback models** to the `fallbackModels` array
+3. **Restart OpenCode** to load the new configuration
+
+### Example Migration
+
+**Before v1.43.0** (no config needed, used defaults):
+```
+Plugin automatically used Claude and Gemini models as fallbacks
+```
+
+**After v1.43.0** (must create config):
+```json
+{
+  "fallbackModels": [
+    { "providerID": "anthropic", "modelID": "claude-3-5-sonnet-20250514" },
+    { "providerID": "google", "modelID": "gemini-2.5-pro" }
+  ],
+  "enabled": true
+}
+```
+
+## Troubleshooting
+
+### "No fallback models configured" warning
+
+**Problem**: You see a warning about no fallback models configured.
+
+**Solution**: Create a config file with your desired fallback models. See the Configuration section above for details.
+
+### Plugin isn't falling back when rate limited
+
+**Problem**: Rate limits occur but no fallback happens.
+
+**Solutions**:
+1. Check that a config file exists and is valid
+2. Verify that `fallbackModels` is not empty in your config
+3. Check that `enabled: true` is set in your config
+4. Review logs for error messages
+
+### "Config file not found" warning
+
+**Problem**: You see warnings about config file not being found.
+
+**Solution**: Create a config file at one of the recommended locations:
+
+**Config file search order (highest to lowest priority):**
+1. `<worktree>/.opencode/rate-limit-fallback.json`
+2. `<worktree>/rate-limit-fallback.json`
+3. `<project>/.opencode/rate-limit-fallback.json`
+4. `<project>/rate-limit-fallback.json`
+5. `~/.opencode/rate-limit-fallback.json` (recommended for most users)
+6. `~/.config/opencode/rate-limit-fallback.json`
+
+> **Note**: Project-local and worktree configs (1-4) take precedence over global configs (5-6).
+
+### All models exhausted quickly
 
-If no configuration is provided, the following models are used:
+**Problem**: Fallback models are exhausted in a short time.
 
-1. `anthropic/claude-3-5-sonnet-20250514`
-2. `google/gemini-2.5-pro`
-3. `google/gemini-2.5-flash`
+**Solutions**:
+1. Add more fallback models to your config
+2. Increase `cooldownMs` to allow models to recover
+3. Consider using `fallbackMode: "cycle"` to reset automatically
+4. Check your API rate limits
 
 ## How It Works
 

package/dist/index.js

@@ -13,6 +13,36 @@ import { ConfigValidator } from "./src/config/Validator.js";
 import { ErrorPatternRegistry } from "./src/errors/PatternRegistry.js";
 import { HealthTracker } from "./src/health/HealthTracker.js";
 import { DiagnosticReporter } from "./src/diagnostics/Reporter.js";
+import { ConfigWatcher } from "./src/config/Watcher.js";
+import { ConfigReloader } from "./src/main/ConfigReloader.js";
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Get the difference between two objects (returns keys with different values)
+ */
+function getObjectDiff(obj1, obj2) {
+    const diffs = [];
+    const allKeys = new Set([...Object.keys(obj1), ...Object.keys(obj2)]);
+    for (const key of allKeys) {
+        const val1 = obj1[key];
+        const val2 = obj2[key];
+        if (typeof val1 !== typeof val2) {
+            diffs.push(`${key}: ${val1} → ${val2}`);
+            continue;
+        }
+        if (val1 === undefined && val2 !== undefined) {
+            diffs.push(`${key}: undefined → ${JSON.stringify(val2)}`);
+        }
+        else if (val1 !== undefined && val2 === undefined) {
+            diffs.push(`${key}: ${JSON.stringify(val1)} → undefined`);
+        }
+        else if (val1 !== val2) {
+            diffs.push(`${key}: ${JSON.stringify(val1)} → ${JSON.stringify(val2)}`);
+        }
+    }
+    return diffs;
+}
 // ============================================================================
 // Event Type Guards
 // ============================================================================
@@ -57,22 +87,58 @@ function isSubagentSessionCreatedEvent(event) {
 // Main Plugin Export
 // ============================================================================
 export const RateLimitFallback = async ({ client, directory, worktree }) => {
-    const { config, source: configSource } = loadConfig(directory, worktree);
-    // Detect headless mode (no TUI)
+    // Detect headless mode (no TUI) before loading config for logging
     const isHeadless = !client.tui;
+    // We need a temporary logger to log config loading process
+    // Use a minimal config initially
+    const tempLogConfig = {
+        level: isHeadless ? 'info' : 'warn',
+        format: 'simple',
+        enableTimestamp: true,
+    };
+    const tempLogger = createLogger(tempLogConfig, "RateLimitFallback");
+    // Log headless mode detection
+    if (isHeadless) {
+        tempLogger.info("Running in headless mode (no TUI detected)");
+    }
+    const configLoadResult = loadConfig(directory, worktree, tempLogger);
+    const { config, source: configSource } = configLoadResult;
     // Auto-adjust log level for headless mode to ensure visibility
     const logConfig = {
         ...config.log,
         level: isHeadless ? 'info' : (config.log?.level ?? 'warn'),
     };
-    // Create logger instance
+    // Create final logger instance with loaded config
     const logger = createLogger(logConfig, "RateLimitFallback");
     if (configSource) {
-        logger.info(`Config loaded from ${configSource}`);
+        logger.info(`Config loaded from: ${configSource}`);
     }
     else {
         logger.info("No config file found, using defaults");
     }
+    // Log verbose mode status
+    if (config.verbose) {
+        logger.info("Verbose mode enabled - showing diagnostic information");
+    }
+    // Log config merge diff in verbose mode
+    if (config.verbose && configSource) {
+        if (configLoadResult.rawUserConfig &&
+            typeof configLoadResult.rawUserConfig === 'object' &&
+            configLoadResult.rawUserConfig !== null &&
+            !Array.isArray(configLoadResult.rawUserConfig) &&
+            Object.keys(configLoadResult.rawUserConfig).length > 0) {
+            logger.info("Configuration merge details:");
+            const diffs = getObjectDiff(configLoadResult.rawUserConfig, config);
+            if (diffs.length > 0) {
+                for (const diff of diffs) {
+                    logger.info(`  ${diff}`);
+                }
+            }
+            else {
+                logger.info("  No changes from defaults");
+            }
+        }
+    }
     // Initialize configuration validator
     const validator = new ConfigValidator(logger);
     const validation = configSource
@@ -108,13 +174,32 @@ export const RateLimitFallback = async ({ client, directory, worktree }) => {
     errorPatternRegistry, logger);
     // Log startup diagnostics if verbose mode
     if (config.verbose) {
-        logger.debug("Verbose mode enabled - showing diagnostic information");
         diagnostics.logCurrentConfig();
     }
     // Initialize components
     const subagentTracker = new SubagentTracker(config);
     const metricsManager = new MetricsManager(config.metrics ?? { enabled: false, output: { console: true, format: "pretty" }, resetInterval: "daily" }, logger);
     const fallbackHandler = new FallbackHandler(config, client, logger, metricsManager, subagentTracker, healthTracker);
+    // Initialize config reloader if hot reload is enabled
+    let configWatcher;
+    if (config.configReload?.enabled) {
+        const componentRefs = {
+            fallbackHandler,
+            metricsManager,
+        };
+        const configReloader = new ConfigReloader(config, configSource, logger, validator, client, componentRefs, directory, worktree, config.configReload?.notifyOnReload ?? true);
+        configWatcher = new ConfigWatcher(configSource || '', logger, async () => { await configReloader.reloadConfig(); }, {
+            enabled: config.configReload.enabled,
+            watchFile: config.configReload.watchFile,
+            debounceMs: config.configReload.debounceMs,
+        });
+        configWatcher.start();
+        logger.info('Config hot reload enabled', {
+            configPath: configSource || 'none',
+            debounceMs: config.configReload.debounceMs,
+            notifyOnReload: config.configReload.notifyOnReload,
+        });
+    }
     // Cleanup stale entries periodically
     const cleanupInterval = setInterval(() => {
         subagentTracker.cleanupStaleEntries();
@@ -181,6 +266,9 @@ export const RateLimitFallback = async ({ client, directory, worktree }) => {
             if (healthTracker) {
                 healthTracker.destroy();
             }
+            if (configWatcher) {
+                configWatcher.stop();
+            }
         },
     };
 };

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

@@ -0,0 +1,45 @@
+/**
+ * Configuration file watcher for hot reload functionality
+ */
+import type { Logger } from '../../logger.js';
+/**
+ * Options for config watching
+ */
+export interface ConfigWatchOptions {
+    enabled: boolean;
+    watchFile: boolean;
+    debounceMs: number;
+}
+/**
+ * ConfigWatcher class - watches config file for changes
+ */
+export declare class ConfigWatcher {
+    private watcher?;
+    private debounceTimer?;
+    private configPath;
+    private logger;
+    private onReload;
+    private options;
+    private isReloading;
+    constructor(configPath: string, logger: Logger, onReload: () => Promise<void>, options: ConfigWatchOptions);
+    /**
+     * Start watching the config file
+     */
+    start(): void;
+    /**
+     * Stop watching the config file
+     */
+    stop(): void;
+    /**
+     * Handle config file change event
+     */
+    private handleConfigChange;
+    /**
+     * Check if watcher is currently active
+     */
+    isActive(): boolean;
+    /**
+     * Check if a reload is currently in progress
+     */
+    isReloadingInProgress(): boolean;
+}

package/dist/src/config/Watcher.js

@@ -0,0 +1,109 @@
+/**
+ * Configuration file watcher for hot reload functionality
+ */
+import { watch } from 'fs';
+/**
+ * ConfigWatcher class - watches config file for changes
+ */
+export class ConfigWatcher {
+    watcher;
+    debounceTimer;
+    configPath;
+    logger;
+    onReload;
+    options;
+    isReloading;
+    constructor(configPath, logger, onReload, options) {
+        this.configPath = configPath;
+        this.logger = logger;
+        this.onReload = onReload;
+        this.options = options;
+        this.isReloading = false;
+    }
+    /**
+     * Start watching the config file
+     */
+    start() {
+        if (!this.options.enabled || !this.options.watchFile) {
+            this.logger.info('Config hot reload is disabled');
+            return;
+        }
+        if (!this.configPath) {
+            this.logger.warn('No config file path provided, cannot watch for changes');
+            return;
+        }
+        try {
+            this.watcher = watch(this.configPath, (eventType, filename) => {
+                this.logger.debug(`Config file event: ${eventType} ${filename || ''}`);
+                // Debounce the reload
+                if (this.debounceTimer) {
+                    clearTimeout(this.debounceTimer);
+                }
+                this.debounceTimer = setTimeout(() => {
+                    this.handleConfigChange();
+                }, this.options.debounceMs);
+            });
+            this.logger.info(`Watching config file for changes: ${this.configPath}`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Failed to watch config file: ${errorMessage}`);
+            this.logger.warn('Hot reload will not be available');
+        }
+    }
+    /**
+     * Stop watching the config file
+     */
+    stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+        if (this.watcher) {
+            try {
+                this.watcher.close();
+                this.watcher = undefined;
+                this.logger.info('Stopped watching config file');
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                this.logger.warn(`Failed to stop watching config file: ${errorMessage}`);
+                this.watcher = undefined;
+            }
+        }
+    }
+    /**
+     * Handle config file change event
+     */
+    async handleConfigChange() {
+        if (this.isReloading) {
+            this.logger.warn('Config changed while reload in progress, changes will be picked up after current reload completes');
+            return;
+        }
+        this.isReloading = true;
+        try {
+            this.logger.info('Config file changed, reloading...');
+            await this.onReload();
+            this.logger.info('Config reload completed successfully');
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Config reload failed', { error: errorMessage });
+        }
+        finally {
+            this.isReloading = false;
+        }
+    }
+    /**
+     * Check if watcher is currently active
+     */
+    isActive() {
+        return this.watcher !== undefined;
+    }
+    /**
+     * Check if a reload is currently in progress
+     */
+    isReloadingInProgress() {
+        return this.isReloading;
+    }
+}

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

@@ -69,3 +69,12 @@ export declare const DEFAULT_METRICS_CONFIG: {
     };
     readonly resetInterval: "daily";
 };
+/**
+ * Default config reload configuration
+ */
+export declare const DEFAULT_CONFIG_RELOAD_CONFIG: {
+    readonly enabled: false;
+    readonly watchFile: true;
+    readonly debounceMs: 1000;
+    readonly notifyOnReload: true;
+};

package/dist/src/config/defaults.js

@@ -89,3 +89,15 @@ export const DEFAULT_METRICS_CONFIG = {
     },
     resetInterval: "daily",
 };
+// ============================================================================
+// Config Reload Defaults
+// ============================================================================
+/**
+ * Default config reload configuration
+ */
+export const DEFAULT_CONFIG_RELOAD_CONFIG = {
+    enabled: false,
+    watchFile: true,
+    debounceMs: 1000,
+    notifyOnReload: true,
+};

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

@@ -46,7 +46,9 @@ export declare class FallbackHandler {
      */
     private abortSession;
     /**
-     * Retry the prompt with a different model
+     * Queue the prompt asynchronously (non-blocking), then abort the retry loop.
+     * promptAsync FIRST queues pending work so the server doesn't dispose on idle.
+     * abort SECOND cancels the retry loop; the server sees the queued prompt and processes it.
      */
     retryWithModel(targetSessionID: string, model: FallbackModel, parts: MessagePart[], hierarchy: SessionHierarchy | null): Promise<void>;
     /**
@@ -69,4 +71,8 @@ export declare class FallbackHandler {
      * Clean up all resources
      */
     destroy(): void;
+    /**
+     * Update configuration (for hot reload)
+     */
+    updateConfig(newConfig: PluginConfig): void;
 }

package/dist/src/fallback/FallbackHandler.js

@@ -95,7 +95,9 @@ export class FallbackHandler {
         }
     }
     /**
-     * Retry the prompt with a different model
+     * Queue the prompt asynchronously (non-blocking), then abort the retry loop.
+     * promptAsync FIRST queues pending work so the server doesn't dispose on idle.
+     * abort SECOND cancels the retry loop; the server sees the queued prompt and processes it.
      */
     async retryWithModel(targetSessionID, model, parts, hierarchy) {
         // Track the new model for this session
@@ -129,13 +131,16 @@ export class FallbackHandler {
         }
         // Convert internal MessagePart to SDK-compatible format
         const sdkParts = convertPartsToSDKFormat(parts);
-        await this.client.session.prompt({
+        // 1. promptAsync: queue the new prompt (returns immediately, non-blocking)
+        await this.client.session.promptAsync({
             path: { id: targetSessionID },
             body: {
                 parts: sdkParts,
                 model: { providerID: model.providerID, modelID: model.modelID },
             },
         });
+        // 2. abort: cancel the retry loop; server sees queued prompt and processes it
+        await this.abortSession(targetSessionID);
         await safeShowToast(this.client, {
             body: {
                 title: "Fallback Successful",
@@ -176,8 +181,6 @@ export class FallbackHandler {
             if (this.healthTracker && currentProviderID && currentModelID) {
                 this.healthTracker.recordFailure(currentProviderID, currentModelID);
             }
-            // Abort current session with error handling
-            await this.abortSession(targetSessionID);
             await safeShowToast(this.client, {
                 body: {
                     title: "Rate Limit Detected",
@@ -435,4 +438,32 @@ export class FallbackHandler {
             this.circuitBreaker.destroy();
         }
     }
+    /**
+     * Update configuration (for hot reload)
+     */
+    updateConfig(newConfig) {
+        this.config = newConfig;
+        // Update model selector
+        this.modelSelector.updateConfig(newConfig);
+        // Update retry manager
+        this.retryManager.updateConfig(newConfig.retryPolicy || {});
+        // Recreate circuit breaker if configuration changed significantly
+        const oldCircuitBreakerEnabled = this.circuitBreaker !== undefined;
+        if (newConfig.circuitBreaker?.enabled !== oldCircuitBreakerEnabled) {
+            // Destroy existing circuit breaker
+            if (this.circuitBreaker) {
+                this.circuitBreaker.destroy();
+            }
+            // Create new circuit breaker if enabled
+            if (newConfig.circuitBreaker?.enabled) {
+                this.circuitBreaker = new CircuitBreaker(newConfig.circuitBreaker, this.logger, this.metricsManager, this.client);
+                this.modelSelector.setCircuitBreaker(this.circuitBreaker);
+            }
+            else {
+                this.circuitBreaker = undefined;
+                this.modelSelector.setCircuitBreaker(undefined);
+            }
+        }
+        this.logger.debug('FallbackHandler configuration updated');
+    }
 }

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

@@ -42,4 +42,12 @@ export declare class ModelSelector {
      * Clean up stale rate-limited models
      */
     cleanupStaleEntries(): void;
+    /**
+     * Update configuration (for hot reload)
+     */
+    updateConfig(newConfig: PluginConfig): void;
+    /**
+     * Set circuit breaker (for hot reload)
+     */
+    setCircuitBreaker(circuitBreaker: CircuitBreaker | undefined): void;
 }

package/dist/src/fallback/ModelSelector.js

@@ -160,4 +160,16 @@ export class ModelSelector {
             }
         }
     }
+    /**
+     * Update configuration (for hot reload)
+     */
+    updateConfig(newConfig) {
+        this.config = newConfig;
+    }
+    /**
+     * Set circuit breaker (for hot reload)
+     */
+    setCircuitBreaker(circuitBreaker) {
+        this.circuitBreaker = circuitBreaker;
+    }
 }

package/dist/src/main/ConfigReloader.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration reloader for hot reload functionality
+ */
+import type { Logger } from '../../logger.js';
+import type { PluginConfig, OpenCodeClient, ReloadResult, ReloadMetrics } from '../types/index.js';
+import { ConfigValidator } from '../config/Validator.js';
+/**
+ * Component references for updating on reload
+ */
+export interface ComponentRefs {
+    fallbackHandler: {
+        updateConfig: (newConfig: PluginConfig) => void;
+    };
+    metricsManager?: {
+        updateConfig: (newConfig: PluginConfig) => void;
+    };
+}
+/**
+ * ConfigReloader class - handles configuration reload logic
+ */
+export declare class ConfigReloader {
+    private config;
+    private configPath;
+    private logger;
+    private validator;
+    private client;
+    private components;
+    private directory;
+    private worktree?;
+    private notifyOnReload;
+    private reloadMetrics;
+    constructor(config: PluginConfig, configPath: string | null, logger: Logger, validator: ConfigValidator, client: OpenCodeClient, components: ComponentRefs, directory: string, worktree?: string, notifyOnReload?: boolean);
+    /**
+     * Reload configuration from file
+     */
+    reloadConfig(): Promise<ReloadResult>;
+    /**
+     * Apply configuration changes to components
+     */
+    private applyConfigChanges;
+    /**
+     * Get list of changed configuration settings
+     */
+    private getChangedSettings;
+    /**
+     * Get current configuration
+     */
+    getCurrentConfig(): PluginConfig;
+    /**
+     * Get reload metrics
+     */
+    getReloadMetrics(): ReloadMetrics;
+    /**
+     * Show success toast notification
+     */
+    private showSuccessToast;
+    /**
+     * Show error toast notification
+     */
+    private showErrorToast;
+}

package/dist/src/main/ConfigReloader.js

@@ -0,0 +1,202 @@
+/**
+ * Configuration reloader for hot reload functionality
+ */
+import { loadConfig } from '../utils/config.js';
+import { safeShowToast } from '../utils/helpers.js';
+/**
+ * ConfigReloader class - handles configuration reload logic
+ */
+export class ConfigReloader {
+    config;
+    configPath;
+    logger;
+    validator;
+    client;
+    components;
+    directory;
+    worktree;
+    notifyOnReload;
+    reloadMetrics;
+    constructor(config, configPath, logger, validator, client, components, directory, worktree, notifyOnReload = true) {
+        this.config = config;
+        this.configPath = configPath;
+        this.logger = logger;
+        this.validator = validator;
+        this.client = client;
+        this.components = components;
+        this.directory = directory;
+        this.worktree = worktree;
+        this.notifyOnReload = notifyOnReload;
+        this.reloadMetrics = {
+            totalReloads: 0,
+            successfulReloads: 0,
+            failedReloads: 0,
+        };
+    }
+    /**
+     * Reload configuration from file
+     */
+    async reloadConfig() {
+        const result = {
+            success: false,
+            timestamp: Date.now(),
+        };
+        // Track reload metrics
+        this.reloadMetrics.totalReloads++;
+        this.reloadMetrics.lastReloadTime = result.timestamp;
+        if (!this.configPath) {
+            result.error = 'No config file path available';
+            this.reloadMetrics.failedReloads++;
+            this.reloadMetrics.lastReloadSuccess = false;
+            return result;
+        }
+        try {
+            // Load new config
+            this.logger.debug(`Loading config from: ${this.configPath}`);
+            const loadResult = loadConfig(this.directory, this.worktree, this.logger);
+            const newConfig = loadResult.config;
+            const source = loadResult.source;
+            // Validate new config
+            const validation = source
+                ? this.validator.validateFile(source, newConfig.configValidation)
+                : this.validator.validate(newConfig, newConfig.configValidation);
+            if (!validation.isValid && newConfig.configValidation?.strict) {
+                result.error = `Validation failed: ${validation.errors.map(e => `${e.path}: ${e.message}`).join(', ')}`;
+                this.logger.error('Config validation failed in strict mode');
+                this.logger.error(`Errors: ${result.error}`);
+                this.showErrorToast('Config Reload Failed', result.error);
+                this.reloadMetrics.failedReloads++;
+                this.reloadMetrics.lastReloadSuccess = false;
+                return result;
+            }
+            if (validation.errors.length > 0) {
+                this.logger.warn(`Config validation found ${validation.errors.length} error(s)`);
+                for (const error of validation.errors) {
+                    this.logger.warn(`  ${error.path}: ${error.message}`);
+                }
+            }
+            // Apply the new configuration
+            this.applyConfigChanges(newConfig);
+            result.success = true;
+            this.reloadMetrics.successfulReloads++;
+            this.reloadMetrics.lastReloadSuccess = true;
+            this.logger.info('Configuration reloaded successfully');
+            this.logger.debug(`Reload metrics: ${this.reloadMetrics.successfulReloads}/${this.reloadMetrics.totalReloads} successful`);
+            if (this.notifyOnReload) {
+                this.showSuccessToast('Configuration Reloaded', 'Settings have been applied');
+            }
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.error = `Failed to reload config: ${errorMessage}`;
+            this.logger.error(result.error);
+            this.showErrorToast('Config Reload Failed', errorMessage);
+            this.reloadMetrics.failedReloads++;
+            this.reloadMetrics.lastReloadSuccess = false;
+            return result;
+        }
+    }
+    /**
+     * Apply configuration changes to components
+     */
+    applyConfigChanges(newConfig) {
+        const oldConfig = this.config;
+        // Update internal config reference
+        this.config = newConfig;
+        // Update components with new config
+        this.components.fallbackHandler.updateConfig(newConfig);
+        if (this.components.metricsManager) {
+            this.components.metricsManager.updateConfig(newConfig);
+        }
+        // Log configuration changes
+        const changedSettings = this.getChangedSettings(oldConfig, newConfig);
+        if (changedSettings.length > 0) {
+            this.logger.info('Configuration changes applied:');
+            for (const change of changedSettings) {
+                this.logger.info(`  ${change}`);
+            }
+        }
+    }
+    /**
+     * Get list of changed configuration settings
+     */
+    getChangedSettings(oldConfig, newConfig) {
+        const changes = [];
+        // Check fallbackModels
+        if (JSON.stringify(oldConfig.fallbackModels) !== JSON.stringify(newConfig.fallbackModels)) {
+            changes.push(`fallbackModels: ${oldConfig.fallbackModels.length} → ${newConfig.fallbackModels.length} models`);
+        }
+        // Check cooldownMs
+        if (oldConfig.cooldownMs !== newConfig.cooldownMs) {
+            changes.push(`cooldownMs: ${oldConfig.cooldownMs}ms → ${newConfig.cooldownMs}ms`);
+        }
+        // Check fallbackMode
+        if (oldConfig.fallbackMode !== newConfig.fallbackMode) {
+            changes.push(`fallbackMode: ${oldConfig.fallbackMode} → ${newConfig.fallbackMode}`);
+        }
+        // Check retryPolicy
+        if (JSON.stringify(oldConfig.retryPolicy) !== JSON.stringify(newConfig.retryPolicy)) {
+            changes.push('retryPolicy: updated');
+        }
+        // Check circuitBreaker
+        if (JSON.stringify(oldConfig.circuitBreaker) !== JSON.stringify(newConfig.circuitBreaker)) {
+            changes.push('circuitBreaker: updated');
+        }
+        // Check metrics
+        if (JSON.stringify(oldConfig.metrics) !== JSON.stringify(newConfig.metrics)) {
+            changes.push('metrics: updated');
+        }
+        // Check log
+        if (JSON.stringify(oldConfig.log) !== JSON.stringify(newConfig.log)) {
+            changes.push('log: updated');
+        }
+        // Check enableHealthBasedSelection
+        if (oldConfig.enableHealthBasedSelection !== newConfig.enableHealthBasedSelection) {
+            changes.push(`enableHealthBasedSelection: ${oldConfig.enableHealthBasedSelection} → ${newConfig.enableHealthBasedSelection}`);
+        }
+        // Check verbose
+        if (oldConfig.verbose !== newConfig.verbose) {
+            changes.push(`verbose: ${oldConfig.verbose} → ${newConfig.verbose}`);
+        }
+        return changes;
+    }
+    /**
+     * Get current configuration
+     */
+    getCurrentConfig() {
+        return this.config;
+    }
+    /**
+     * Get reload metrics
+     */
+    getReloadMetrics() {
+        return { ...this.reloadMetrics };
+    }
+    /**
+     * Show success toast notification
+     */
+    showSuccessToast(title, message) {
+        safeShowToast(this.client, {
+            body: {
+                title,
+                message,
+                variant: 'success',
+                duration: 3000,
+            },
+        });
+    }
+    /**
+     * Show error toast notification
+     */
+    showErrorToast(title, message) {
+        safeShowToast(this.client, {
+            body: {
+                title,
+                message,
+                variant: 'error',
+                duration: 5000,
+            },
+        });
+    }
+}

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

@@ -2,7 +2,7 @@
  * Metrics Manager - Handles metrics collection, aggregation, and reporting
  */
 import type { Logger } from '../../logger.js';
-import type { MetricsConfig, MetricsData, RateLimitMetrics, FallbackTargetMetrics, ModelPerformanceMetrics, CircuitBreakerStateType } from '../types/index.js';
+import type { MetricsConfig, MetricsData, RateLimitMetrics, FallbackTargetMetrics, ModelPerformanceMetrics, CircuitBreakerStateType, PluginConfig } from '../types/index.js';
 /**
  * Metrics Manager class for collecting and reporting metrics
  */
@@ -98,5 +98,9 @@ export declare class MetricsManager {
      * Clean up resources
      */
     destroy(): void;
+    /**
+     * Update configuration (for hot reload)
+     */
+    updateConfig(newConfig: PluginConfig): void;
 }
 export type { MetricsConfig, MetricsData, RateLimitMetrics, FallbackTargetMetrics, ModelPerformanceMetrics };

package/dist/src/metrics/MetricsManager.js

@@ -613,4 +613,31 @@ export class MetricsManager {
             this.resetTimer = null;
         }
     }
+    /**
+     * Update configuration (for hot reload)
+     */
+    updateConfig(newConfig) {
+        const oldEnabled = this.config.enabled;
+        const oldResetInterval = this.config.resetInterval;
+        this.config = newConfig.metrics || { enabled: false, output: { console: true, format: "pretty" }, resetInterval: "daily" };
+        // Restart reset timer if reset interval changed
+        if (oldResetInterval !== this.config.resetInterval && this.config.enabled) {
+            this.startResetTimer();
+        }
+        // Enable/disable reset timer based on config.enabled change
+        if (oldEnabled !== this.config.enabled) {
+            if (this.config.enabled) {
+                this.startResetTimer();
+            }
+            else if (this.resetTimer) {
+                clearInterval(this.resetTimer);
+                this.resetTimer = null;
+            }
+        }
+        this.logger.debug('MetricsManager configuration updated', {
+            enabled: this.config.enabled,
+            resetInterval: this.config.resetInterval,
+            output: this.config.output,
+        });
+    }
 }

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

@@ -146,6 +146,33 @@ export interface ErrorPatternsConfig {
     custom?: ErrorPattern[];
     enableLearning?: boolean;
 }
+/**
+ * Configuration hot reload settings
+ */
+export interface ConfigReloadConfig {
+    enabled: boolean;
+    watchFile: boolean;
+    debounceMs: number;
+    notifyOnReload: boolean;
+}
+/**
+ * Result of a configuration reload operation
+ */
+export interface ReloadResult {
+    success: boolean;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Metrics for configuration reload operations
+ */
+export interface ReloadMetrics {
+    totalReloads: number;
+    successfulReloads: number;
+    failedReloads: number;
+    lastReloadTime?: number;
+    lastReloadSuccess?: boolean;
+}
 /**
  * Plugin configuration
  */
@@ -165,6 +192,7 @@ export interface PluginConfig {
     healthPersistence?: HealthPersistenceConfig;
     verbose?: boolean;
     errorPatterns?: ErrorPatternsConfig;
+    configReload?: ConfigReloadConfig;
 }
 /**
  * Fallback state for tracking progress
@@ -413,6 +441,18 @@ export type OpenCodeClient = {
                 };
             };
         }) => Promise<unknown>;
+        promptAsync: (args: {
+            path: {
+                id: string;
+            };
+            body: {
+                parts: SDKMessagePartInput[];
+                model: {
+                    providerID: string;
+                    modelID: string;
+                };
+            };
+        }) => Promise<unknown>;
     };
     tui?: {
         showToast: (toast: ToastMessage) => Promise<unknown>;
@@ -427,6 +467,17 @@ export type PluginContext = {
 };
 /**
  * Default fallback models
+ *
+ * NOTE: This is intentionally empty to force users to explicitly configure
+ * their fallback models. This prevents unintended model usage (e.g., gemini
+ * when not wanted) and makes configuration errors obvious immediately.
+ *
+ * Users must create a config file in one of these locations:
+ * - <worktree>/.opencode/rate-limit-fallback.json
+ * - <directory>/.opencode/rate-limit-fallback.json
+ * - <directory>/rate-limit-fallback.json
+ * - ~/.opencode/rate-limit-fallback.json
+ * - $XDG_CONFIG_HOME/opencode/rate-limit-fallback.json
  */
 export declare const DEFAULT_FALLBACK_MODELS: FallbackModel[];
 /**

package/dist/src/types/index.js

@@ -6,12 +6,19 @@
 // ============================================================================
 /**
  * Default fallback models
+ *
+ * NOTE: This is intentionally empty to force users to explicitly configure
+ * their fallback models. This prevents unintended model usage (e.g., gemini
+ * when not wanted) and makes configuration errors obvious immediately.
+ *
+ * Users must create a config file in one of these locations:
+ * - <worktree>/.opencode/rate-limit-fallback.json
+ * - <directory>/.opencode/rate-limit-fallback.json
+ * - <directory>/rate-limit-fallback.json
+ * - ~/.opencode/rate-limit-fallback.json
+ * - $XDG_CONFIG_HOME/opencode/rate-limit-fallback.json
  */
-export const DEFAULT_FALLBACK_MODELS = [
-    { providerID: "anthropic", modelID: "claude-3-5-sonnet-20250514" },
-    { providerID: "google", modelID: "gemini-2.5-pro" },
-    { providerID: "google", modelID: "gemini-2.5-flash" },
-];
+export const DEFAULT_FALLBACK_MODELS = [];
 /**
  * Default retry policy
  */

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

@@ -2,6 +2,7 @@
  * Configuration loading and validation
  */
 import type { PluginConfig } from '../types/index.js';
+import type { Logger } from '../../logger.js';
 /**
  * Default plugin configuration
  */
@@ -12,6 +13,7 @@ export declare const DEFAULT_CONFIG: PluginConfig;
 export interface ConfigLoadResult {
     config: PluginConfig;
     source: string | null;
+    rawUserConfig?: Partial<PluginConfig>;
 }
 /**
  * Validate configuration values
@@ -20,4 +22,4 @@ export declare function validateConfig(config: Partial<PluginConfig>): PluginCon
 /**
  * Load and validate config from file paths
  */
-export declare function loadConfig(directory: string, worktree?: string): ConfigLoadResult;
+export declare function loadConfig(directory: string, worktree?: string, logger?: Logger): ConfigLoadResult;

package/dist/src/utils/config.js

@@ -4,7 +4,7 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { DEFAULT_FALLBACK_MODELS, VALID_FALLBACK_MODES, VALID_RESET_INTERVALS, DEFAULT_RETRY_POLICY, VALID_RETRY_STRATEGIES, DEFAULT_CIRCUIT_BREAKER_CONFIG, } from '../types/index.js';
-import { DEFAULT_HEALTH_TRACKER_CONFIG, DEFAULT_COOLDOWN_MS, DEFAULT_FALLBACK_MODE, DEFAULT_LOG_CONFIG, DEFAULT_METRICS_CONFIG, } from '../config/defaults.js';
+import { DEFAULT_HEALTH_TRACKER_CONFIG, DEFAULT_COOLDOWN_MS, DEFAULT_FALLBACK_MODE, DEFAULT_LOG_CONFIG, DEFAULT_METRICS_CONFIG, DEFAULT_CONFIG_RELOAD_CONFIG, } from '../config/defaults.js';
 /**
  * Default plugin configuration
  */
@@ -18,6 +18,7 @@ export const DEFAULT_CONFIG = {
     healthPersistence: DEFAULT_HEALTH_TRACKER_CONFIG,
     log: DEFAULT_LOG_CONFIG,
     metrics: DEFAULT_METRICS_CONFIG,
+    configReload: DEFAULT_CONFIG_RELOAD_CONFIG,
 };
 /**
  * Validate configuration values
@@ -54,12 +55,16 @@ export function validateConfig(config) {
             } : DEFAULT_CONFIG.metrics.output,
             resetInterval: resetInterval && VALID_RESET_INTERVALS.includes(resetInterval) ? resetInterval : DEFAULT_CONFIG.metrics.resetInterval,
         } : DEFAULT_CONFIG.metrics,
+        configReload: config.configReload ? {
+            ...DEFAULT_CONFIG.configReload,
+            ...config.configReload,
+        } : DEFAULT_CONFIG.configReload,
     };
 }
 /**
  * Load and validate config from file paths
  */
-export function loadConfig(directory, worktree) {
+export function loadConfig(directory, worktree, logger) {
     const homedir = process.env.HOME || "";
     const xdgConfigHome = process.env.XDG_CONFIG_HOME || join(homedir, ".config");
     // Build search paths: worktree first, then directory, then home locations
@@ -77,17 +82,57 @@ export function loadConfig(directory, worktree) {
     }
     configPaths.push(join(homedir, ".opencode", "rate-limit-fallback.json"));
     configPaths.push(join(xdgConfigHome, "opencode", "rate-limit-fallback.json"));
+    // Log search paths for debugging
+    if (logger) {
+        logger.debug(`Searching for config file in ${configPaths.length} locations`);
+        for (const configPath of configPaths) {
+            const exists = existsSync(configPath);
+            logger.debug(`  ${exists ? "✓" : "✗"} ${configPath}`);
+        }
+    }
     for (const configPath of configPaths) {
         if (existsSync(configPath)) {
             try {
                 const content = readFileSync(configPath, "utf-8");
                 const userConfig = JSON.parse(content);
-                return { config: validateConfig(userConfig), source: configPath };
+                if (logger) {
+                    logger.info(`Config loaded from: ${configPath}`);
+                }
+                return {
+                    config: validateConfig(userConfig),
+                    source: configPath,
+                    rawUserConfig: userConfig,
+                };
             }
-            catch {
+            catch (error) {
+                if (logger) {
+                    logger.warn(`Failed to parse config file: ${configPath}`, { error: error instanceof Error ? error.message : String(error) });
+                }
                 // Skip invalid config files silently - caller will log via structured logger
             }
         }
     }
+    if (logger) {
+        // Log that no config file was found
+        logger.info(`No config file found in any of the ${configPaths.length} search paths. Using default configuration.`);
+        // Show a warning if default fallback models is empty (which is now the case)
+        if (DEFAULT_CONFIG.fallbackModels.length === 0) {
+            logger.warn('No fallback models configured. The plugin will not be able to fallback when rate limited.');
+            logger.warn('Please create a config file with your fallback models.');
+            logger.warn('Config file locations (in order of priority):');
+            for (const configPath of configPaths) {
+                logger.warn(`  - ${configPath}`);
+            }
+            logger.warn('Example config:');
+            logger.warn(JSON.stringify({
+                fallbackModels: [
+                    { providerID: "anthropic", modelID: "claude-3-5-sonnet-20250514" },
+                ],
+                cooldownMs: 60000,
+                enabled: true,
+                fallbackMode: "cycle",
+            }, null, 2));
+        }
+    }
     return { config: DEFAULT_CONFIG, source: null };
 }

package/package.json

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