@azumag/opencode-rate-limit-fallback 1.0.3 → 1.0.6

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,21 @@
+name: npm publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm install
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -6,9 +6,11 @@ OpenCode plugin that automatically switches to fallback models when rate limited
 
 ## Features
 
-- Detects rate limit errors (429, "usage limit", "quota exceeded", etc.)
+- Detects rate limit errors (429, "usage limit", "quota exceeded", "high concurrency", etc.)
 - 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`
+- Session model tracking for sequential fallback across multiple rate limits
 - Cooldown period to prevent immediate retry on rate-limited models
 - Toast notifications for user feedback
 
@@ -51,6 +53,7 @@ Create a configuration file at one of these locations:
 {
   "enabled": true,
   "cooldownMs": 60000,
+  "fallbackMode": "cycle",
   "fallbackModels": [
     { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" },
     { "providerID": "google", "modelID": "gemini-2.5-pro" },
@@ -65,8 +68,17 @@ 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) |
 | `fallbackModels` | array | See below | List of fallback models in priority order |
 
+### Fallback Modes
+
+| Mode | Description |
+|------|-------------|
+| `"cycle"` | Reset and retry from the first model when all models are exhausted (default) |
+| `"stop"` | Stop and show error when all models are exhausted |
+| `"retry-last"` | Try the last model once more, then reset to first on next prompt |
+
 ### Default Fallback Models
 
 If no configuration is provided, the following models are used:

package/index.ts

@@ -7,10 +7,19 @@ interface FallbackModel {
   modelID: string;
 }
 
+/**
+ * Fallback mode when all models are exhausted:
+ * - "cycle": Reset and retry from the first model (default)
+ * - "stop": Stop and show error message
+ * - "retry-last": Try the last model once, then reset to first on next prompt
+ */
+type FallbackMode = "cycle" | "stop" | "retry-last";
+
 interface PluginConfig {
   fallbackModels: FallbackModel[];
   cooldownMs: number;
   enabled: boolean;
+  fallbackMode: FallbackMode;
 }
 
 const DEFAULT_FALLBACK_MODELS: FallbackModel[] = [
@@ -23,6 +32,7 @@ const DEFAULT_CONFIG: PluginConfig = {
   fallbackModels: DEFAULT_FALLBACK_MODELS,
   cooldownMs: 60 * 1000,
   enabled: true,
+  fallbackMode: "cycle",
 };
 
 function loadConfig(directory: string): PluginConfig {
@@ -39,10 +49,13 @@ function loadConfig(directory: string): PluginConfig {
       try {
         const content = readFileSync(configPath, "utf-8");
         const userConfig = JSON.parse(content);
+        const mode = userConfig.fallbackMode;
+        const validModes: FallbackMode[] = ["cycle", "stop", "retry-last"];
         return {
           ...DEFAULT_CONFIG,
           ...userConfig,
           fallbackModels: userConfig.fallbackModels || DEFAULT_CONFIG.fallbackModels,
+          fallbackMode: validModes.includes(mode) ? mode : DEFAULT_CONFIG.fallbackMode,
         };
       } catch (error) {
         // Config load failed, continue to next path
@@ -102,6 +115,38 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
   const currentSessionModel = new Map<string, { providerID: string; modelID: string }>();
   const fallbackInProgress = new Map<string, number>(); // sessionID -> timestamp
 
+  async function logOrToast(message: string, variant: "info" | "success" | "warning" | "error" = "info") {
+    try {
+      await client.tui.showToast({
+        body: { message, variant },
+      });
+    } catch {
+      await client.app.log({
+        body: {
+          service: "rate-limit-fallback",
+          level: variant,
+          message,
+        },
+      });
+    }
+  }
+
+  async function toast(title: string, message: string, variant: "info" | "success" | "warning" | "error" = "info") {
+    try {
+      await client.tui.showToast({
+        body: { title, message, variant },
+      });
+    } catch {
+      await client.app.log({
+        body: {
+          service: "rate-limit-fallback",
+          level: variant,
+          message: `${title}: ${message}`,
+        },
+      });
+    }
+  }
+
   function isModelRateLimited(providerID: string, modelID: string): boolean {
     const key = getModelKey(providerID, modelID);
     const limitedAt = rateLimitedModels.get(key);
@@ -121,8 +166,21 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
   function findNextAvailableModel(currentProviderID: string, currentModelID: string, attemptedModels: Set<string>): FallbackModel | null {
     const currentKey = getModelKey(currentProviderID, currentModelID);
     let startIndex = config.fallbackModels.findIndex(m => getModelKey(m.providerID, m.modelID) === currentKey);
-    if (startIndex === -1) startIndex = -1;
 
+    // If current model is not in the fallback list, search from the beginning
+    if (startIndex === -1) {
+      // Only search through all models once (first loop handles this)
+      for (let i = 0; i < config.fallbackModels.length; i++) {
+        const model = config.fallbackModels[i];
+        const key = getModelKey(model.providerID, model.modelID);
+        if (!attemptedModels.has(key) && !isModelRateLimited(model.providerID, model.modelID)) {
+          return model;
+        }
+      }
+      return null;
+    }
+
+    // Search for the next model after current position
     for (let i = startIndex + 1; i < config.fallbackModels.length; i++) {
       const model = config.fallbackModels[i];
       const key = getModelKey(model.providerID, model.modelID);
@@ -131,6 +189,7 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
       }
     }
 
+    // Search from the beginning to current position (wrap around)
     for (let i = 0; i <= startIndex && i < config.fallbackModels.length; i++) {
       const model = config.fallbackModels[i];
       const key = getModelKey(model.providerID, model.modelID);
@@ -162,14 +221,7 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
 
       await client.session.abort({ path: { id: sessionID } });
 
-      await client.tui.showToast({
-        body: {
-          title: "Rate Limit Detected",
-          message: `Switching from ${currentModelID || 'current model'}...`,
-          variant: "warning",
-          duration: 3000,
-        },
-      });
+      await toast("Rate Limit Detected", `Switching from ${currentModelID || 'current model'}...`, "warning");
 
       const messagesResult = await client.session.messages({ path: { id: sessionID } });
       if (!messagesResult.data) return;
@@ -193,26 +245,49 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
 
       let nextModel = findNextAvailableModel(currentProviderID || "", currentModelID || "", state.attemptedModels);
 
-      // If no model found and we've attempted models, reset and try again from the beginning
+      // Handle when no model is found based on fallbackMode
       if (!nextModel && state.attemptedModels.size > 0) {
-        state.attemptedModels.clear();
-        // Keep the current model marked as attempted to avoid immediate retry
-        if (currentProviderID && currentModelID) {
-          state.attemptedModels.add(getModelKey(currentProviderID, currentModelID));
+        if (config.fallbackMode === "cycle") {
+          // Reset and retry from the first model
+          state.attemptedModels.clear();
+          if (currentProviderID && currentModelID) {
+            state.attemptedModels.add(getModelKey(currentProviderID, currentModelID));
+          }
+          nextModel = findNextAvailableModel("", "", state.attemptedModels);
+        } else if (config.fallbackMode === "retry-last") {
+          // Try the last model in the list once, then reset on next prompt
+          const lastModel = config.fallbackModels[config.fallbackModels.length - 1];
+            if (lastModel) {
+              const lastKey = getModelKey(lastModel.providerID, lastModel.modelID);
+              const isLastModelCurrent = currentProviderID === lastModel.providerID && currentModelID === lastModel.modelID;
+
+              if (!isLastModelCurrent && !isModelRateLimited(lastModel.providerID, lastModel.modelID)) {
+                // Use the last model for one more try
+                nextModel = lastModel;
+                await toast("Last Resort", `Trying ${lastModel.modelID} one more time...`, "warning");
+              } else {
+              // Last model also failed, reset for next prompt
+              state.attemptedModels.clear();
+              if (currentProviderID && currentModelID) {
+                state.attemptedModels.add(getModelKey(currentProviderID, currentModelID));
+              }
+              nextModel = findNextAvailableModel("", "", state.attemptedModels);
+            }
+          }
         }
-        nextModel = findNextAvailableModel("", "", state.attemptedModels);
+        // "stop" mode: nextModel remains null, will show error below
       }
 
       if (!nextModel) {
-        await client.tui.showToast({
-          body: {
-            title: "No Fallback Available",
-            message: "All models are rate limited",
-            variant: "error",
-            duration: 5000,
-          },
-        });
+        await toast(
+          "No Fallback Available",
+          config.fallbackMode === "stop"
+            ? "All fallback models exhausted"
+            : "All models are rate limited",
+          "error"
+        );
         retryState.delete(stateKey);
+        fallbackInProgress.delete(sessionID);
         return;
       }
 
@@ -230,14 +305,7 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
 
       if (parts.length === 0) return;
 
-      await client.tui.showToast({
-        body: {
-          title: "Retrying",
-          message: `Using ${nextModel.providerID}/${nextModel.modelID}`,
-          variant: "info",
-          duration: 3000,
-        },
-      });
+      await toast("Retrying", `Using ${nextModel.providerID}/${nextModel.modelID}`, "info");
 
       // Track the new model for this session
       currentSessionModel.set(sessionID, { providerID: nextModel.providerID, modelID: nextModel.modelID });
@@ -250,14 +318,7 @@ export const RateLimitFallback: Plugin = async ({ client, directory }) => {
         },
       });
 
-      await client.tui.showToast({
-        body: {
-          title: "Fallback Successful",
-          message: `Now using ${nextModel.modelID}`,
-          variant: "success",
-          duration: 3000,
-        },
-      });
+      await toast("Fallback Successful", `Now using ${nextModel.modelID}`, "success");
 
       retryState.delete(stateKey);
       // Clear fallback flag to allow next fallback if needed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azumag/opencode-rate-limit-fallback",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "OpenCode plugin that automatically switches to fallback models when rate limited",
   "main": "index.ts",
   "type": "module",

package/rate-limit-fallback.example.json

@@ -1,6 +1,7 @@
 {
   "enabled": true,
   "cooldownMs": 60000,
+  "fallbackMode": "cycle",
   "fallbackModels": [
     { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" },
     { "providerID": "google", "modelID": "gemini-2.5-pro" },

package/.claude/settings.local.json

@@ -1,18 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm publish:*)",
-      "Bash(npm whoami:*)",
-      "Bash(npm config:*)",
-      "WebSearch",
-      "WebFetch(domain:github.blog)",
-      "Bash(npm login:*)",
-      "Bash(npm token create:*)",
-      "Bash(npm view:*)",
-      "Bash(git add:*)",
-      "Bash(git commit -m \"$\\(cat <<''EOF''\nPublish as scoped package @azumag/opencode-rate-limit-fallback\n\n- Rename package to @azumag/opencode-rate-limit-fallback\n- Add npm installation instructions to README\n- Add npm version badge\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
-      "Bash(git push:*)",
-      "Bash(git commit:*)"
-    ]
-  }
-}