@azumag/opencode-rate-limit-fallback 1.39.0 → 1.43.0

package/dist/index.js

@@ -14,6 +14,34 @@ import { ErrorPatternRegistry } from "./src/errors/PatternRegistry.js";
 import { HealthTracker } from "./src/health/HealthTracker.js";
 import { DiagnosticReporter } from "./src/diagnostics/Reporter.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 +85,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,7 +172,6 @@ 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

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

@@ -19,6 +19,7 @@ export declare class FallbackHandler {
     private retryState;
     private fallbackInProgress;
     private fallbackMessages;
+    private sessionLock;
     private metricsManager;
     private subagentTracker;
     private retryManager;
@@ -45,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>;
     /**

package/dist/src/fallback/FallbackHandler.js

@@ -19,6 +19,7 @@ export class FallbackHandler {
     retryState;
     fallbackInProgress;
     fallbackMessages;
+    sessionLock;
     // Metrics manager reference
     metricsManager;
     // Subagent tracker reference
@@ -46,6 +47,7 @@ export class FallbackHandler {
         this.retryState = new Map();
         this.fallbackInProgress = new Map();
         this.fallbackMessages = new Map();
+        this.sessionLock = new Set();
         // Initialize retry manager
         this.retryManager = new RetryManager(config.retryPolicy || {}, logger);
     }
@@ -93,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
@@ -127,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",
@@ -147,10 +154,16 @@ export class FallbackHandler {
      * Handle the rate limit fallback process
      */
     async handleRateLimitFallback(sessionID, currentProviderID, currentModelID) {
+        // Resolve target session before acquiring lock
+        const rootSessionID = this.subagentTracker.getRootSession(sessionID);
+        const targetSessionID = rootSessionID || sessionID;
+        // Session-level lock: prevent concurrent fallback processing
+        if (this.sessionLock.has(targetSessionID)) {
+            this.logger.debug(`Fallback already in progress for session ${targetSessionID}, skipping`);
+            return;
+        }
+        this.sessionLock.add(targetSessionID);
         try {
-            // Get root session and hierarchy using subagent tracker
-            const rootSessionID = this.subagentTracker.getRootSession(sessionID);
-            const targetSessionID = rootSessionID || sessionID;
             const hierarchy = this.subagentTracker.getHierarchy(sessionID);
             // If no model info provided, try to get from tracked session model
             if (!currentProviderID || !currentModelID) {
@@ -168,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",
@@ -309,10 +320,11 @@ export class FallbackHandler {
                 name: errorName,
             });
             // Record retry failure on error
-            const rootSessionID = this.subagentTracker.getRootSession(sessionID);
-            const targetSessionID = rootSessionID || sessionID;
             this.retryManager.recordFailure(targetSessionID);
         }
+        finally {
+            this.sessionLock.delete(targetSessionID);
+        }
     }
     /**
      * Handle message updated events for metrics recording
@@ -419,6 +431,7 @@ export class FallbackHandler {
         this.retryState.clear();
         this.fallbackInProgress.clear();
         this.fallbackMessages.clear();
+        this.sessionLock.clear();
         this.retryManager.destroy();
         // Destroy circuit breaker
         if (this.circuitBreaker) {

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

@@ -413,6 +413,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 +439,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

@@ -59,7 +59,7 @@ export function validateConfig(config) {
 /**
  * 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 +77,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.39.0",
+  "version": "1.43.0",
   "description": "OpenCode plugin that automatically switches to fallback models when rate limited",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",