@azumag/opencode-rate-limit-fallback 1.67.0 → 1.69.0

package/README.md

@@ -10,6 +10,7 @@ OpenCode plugin that automatically switches to fallback models when rate limited
 - Automatically aborts the current request and retries with a fallback model
 - Configurable fallback model list with priority order
 - Three fallback modes: `cycle`, `stop`, and `retry-last`
+- **Headless mode support** (`opencode run`): disable fallback or abort on rate limit
 - 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**
@@ -117,6 +118,7 @@ Create a configuration file at one of these locations:
   | `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) |
+  | `headlessOnRateLimit` | string | `undefined` | Headless mode behavior on rate limit (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 |
@@ -236,6 +238,26 @@ my-repo/
 
 > **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.
 
+### Headless Mode (`opencode run`)
+
+When running in headless mode (no TUI), model fallback is disabled by default because headless sessions should use their configured model only.
+
+You can control what happens when a rate limit is detected in headless mode using the `headlessOnRateLimit` option:
+
+| Value | Description |
+|-------|-------------|
+| *(not set)* | Default behavior — do nothing, let the server's retry loop handle it |
+| `"ignore"` | Same as default — do nothing |
+| `"abort"` | Abort the session immediately to terminate the prompt |
+
+The `"abort"` option is useful when you want `opencode run` to fail fast on rate limits rather than waiting for the server's retry loop, which may retry indefinitely.
+
+```json
+{
+  "headlessOnRateLimit": "abort"
+}
+```
+
 ### Fallback Modes
 
 | Mode | Description |

package/dist/index.js

@@ -158,6 +158,65 @@ export const RateLimitFallback = async ({ client, directory, worktree }) => {
     if (!config.enabled) {
         return {};
     }
+    // Headless mode — no model fallback, but optionally abort on rate limit
+    if (isHeadless) {
+        if (config.headlessOnRateLimit === "abort") {
+            logger.info("Headless mode — will abort session on rate limit");
+            // Minimal setup: only error pattern detection + abort
+            const errorPatternRegistry = new ErrorPatternRegistry(logger);
+            if (config.errorPatterns?.custom) {
+                errorPatternRegistry.registerMany(config.errorPatterns.custom);
+            }
+            // Track sessions already aborted to avoid duplicate abort calls
+            const abortedSessions = new Set();
+            const abortSession = async (sessionID, source) => {
+                if (abortedSessions.has(sessionID))
+                    return;
+                abortedSessions.add(sessionID);
+                logger.info(`Rate limit detected (${source}) — aborting session ${sessionID}`);
+                try {
+                    await client.session.abort({ path: { id: sessionID } });
+                }
+                catch (err) {
+                    logger.warn(`Failed to abort session ${sessionID}`, {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            };
+            return {
+                event: async ({ event }) => {
+                    if (isSessionErrorEvent(event)) {
+                        const { sessionID, error } = event.properties;
+                        if (sessionID && error && errorPatternRegistry.isRateLimitError(error)) {
+                            await abortSession(sessionID, "session.error");
+                        }
+                    }
+                    if (isMessageUpdatedEvent(event)) {
+                        const info = event.properties.info;
+                        if (info?.error && errorPatternRegistry.isRateLimitError(info.error)) {
+                            await abortSession(info.sessionID, "message.updated");
+                        }
+                    }
+                    if (isSessionStatusEvent(event)) {
+                        const props = event.properties;
+                        const status = props?.status;
+                        if (status?.type === "retry" && status?.message) {
+                            const message = status.message.toLowerCase();
+                            const isRateLimitRetry = message.includes("usage limit") ||
+                                message.includes("rate limit") ||
+                                message.includes("high concurrency") ||
+                                message.includes("reduce concurrency");
+                            if (isRateLimitRetry) {
+                                await abortSession(props.sessionID, "session.status retry");
+                            }
+                        }
+                    }
+                },
+            };
+        }
+        logger.info("Headless mode detected — model fallback disabled");
+        return {};
+    }
     // Initialize error pattern registry
     const errorPatternRegistry = new ErrorPatternRegistry(logger);
     if (config.errorPatterns?.custom) {

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

@@ -17,6 +17,12 @@ export interface FallbackModel {
  * - "retry-last": Try the last model once, then reset to first on next prompt
  */
 export type FallbackMode = "cycle" | "stop" | "retry-last";
+/**
+ * Headless mode behavior on rate limit:
+ * - "ignore": Do nothing, let server handle retries (default)
+ * - "abort": Abort the session to terminate the prompt immediately
+ */
+export type HeadlessOnRateLimit = "ignore" | "abort";
 /**
  * Retry strategy type
  * - "immediate": Retry immediately without delay
@@ -234,6 +240,7 @@ export interface PluginConfig {
     cooldownMs: number;
     enabled: boolean;
     fallbackMode: FallbackMode;
+    headlessOnRateLimit?: HeadlessOnRateLimit;
     maxSubagentDepth?: number;
     enableSubagentFallback?: boolean;
     retryPolicy?: RetryPolicy;
@@ -547,6 +554,10 @@ export declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig;
  * Valid fallback modes
  */
 export declare const VALID_FALLBACK_MODES: FallbackMode[];
+/**
+ * Valid headless on rate limit options
+ */
+export declare const VALID_HEADLESS_ON_RATE_LIMIT: HeadlessOnRateLimit[];
 /**
  * Valid retry strategies
  */

package/dist/src/types/index.js

@@ -46,6 +46,10 @@ export const DEFAULT_CIRCUIT_BREAKER_CONFIG = {
  * Valid fallback modes
  */
 export const VALID_FALLBACK_MODES = ["cycle", "stop", "retry-last"];
+/**
+ * Valid headless on rate limit options
+ */
+export const VALID_HEADLESS_ON_RATE_LIMIT = ["ignore", "abort"];
 /**
  * Valid retry strategies
  */

package/dist/src/utils/config.js

@@ -3,7 +3,7 @@
  */
 import { existsSync, readFileSync } from "fs";
 import { join, resolve, normalize, relative } 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_FALLBACK_MODELS, VALID_FALLBACK_MODES, VALID_HEADLESS_ON_RATE_LIMIT, 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, DEFAULT_CONFIG_RELOAD_CONFIG, DEFAULT_DYNAMIC_PRIORITIZATION_CONFIG, DEFAULT_ERROR_PATTERNS_CONFIG, DEFAULT_PATTERN_LEARNING_CONFIG, } from '../config/defaults.js';
 /**
  * Default plugin configuration
@@ -53,6 +53,7 @@ function validatePathSafety(path, allowedDirs) {
  */
 export function validateConfig(config) {
     const mode = config.fallbackMode;
+    const headlessOnRateLimit = config.headlessOnRateLimit;
     const resetInterval = config.metrics?.resetInterval;
     const strategy = config.retryPolicy?.strategy;
     return {
@@ -60,6 +61,7 @@ export function validateConfig(config) {
         ...config,
         fallbackModels: Array.isArray(config.fallbackModels) ? config.fallbackModels : DEFAULT_CONFIG.fallbackModels,
         fallbackMode: mode && VALID_FALLBACK_MODES.includes(mode) ? mode : DEFAULT_CONFIG.fallbackMode,
+        headlessOnRateLimit: headlessOnRateLimit && VALID_HEADLESS_ON_RATE_LIMIT.includes(headlessOnRateLimit) ? headlessOnRateLimit : undefined,
         retryPolicy: config.retryPolicy ? {
             ...DEFAULT_CONFIG.retryPolicy,
             ...config.retryPolicy,

package/package.json

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