@shutovks/opencode-model-fallback 1.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-model-fallback contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @shutovks/opencode-model-fallback
+
+OpenCode plugin that keeps a session alive when the current model fails with rate limits, quota exhaustion, overloads, or temporary provider errors.
+
+It retries the last user message in the same session with the next configured fallback model.
+
+## Install
+
+```bash
+bun add -g @shutovks/opencode-model-fallback
+```
+
+Or use any package manager OpenCode can resolve from your `plugin` config.
+
+## Configure
+
+Add the plugin to `opencode.json` or `.opencode/opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "@shutovks/opencode-model-fallback",
+      {
+        "enabled": true,
+        "fallback_models": [
+          "anthropic/claude-sonnet-4-5",
+          "openai/gpt-5.1-codex",
+          "google/gemini-2.5-pro"
+        ],
+        "unavailable_models": [],
+        "max_attempts": 3,
+        "cooldown_ms": 60000,
+        "notify": true
+      }
+    ]
+  ]
+}
+```
+
+Restart OpenCode after changing config.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Default behavior for new sessions. |
+| `fallback_models` | `[]` | Ordered fallback model list, each as `provider/model`. |
+| `unavailable_models` | `[]` | Exact model IDs to skip in the config hook before the first provider call. Useful when OpenCode fails before emitting `session.error`. |
+| `retry_on_errors` | `[429, 500, 502, 503, 504]` | HTTP status codes that trigger fallback. |
+| `max_attempts` | `3` | Max fallback retries per session. |
+| `cooldown_ms` | `60000` | How long to avoid a failed model. |
+| `notify` | `true` | Show a toast when switching models. |
+
+## Session Control
+
+The plugin registers one tool:
+
+```text
+model_fallback_control(action: "enable" | "disable" | "status" | "reset")
+```
+
+Use it from inside OpenCode to control fallback for the current session:
+
+```text
+Use model_fallback_control to disable fallback in this session.
+```
+
+Actions:
+
+- `enable`: enable fallback for the current session.
+- `disable`: disable fallback for the current session.
+- `status`: return effective state, current model, attempts, and configured fallbacks.
+- `reset`: clear session state and return to the config default.
+
+Session overrides are in memory only. They disappear when the session is deleted or OpenCode restarts.
+
+## What Counts As Retryable
+
+Fallback runs on configured status codes and common transient error text:
+
+- rate limit / too many requests
+- quota exceeded
+- all credentials for model exhausted
+- model unsupported
+- service unavailable / overloaded / temporarily unavailable
+- `429`, `503`, `529` in plain text errors
+
+## Limitations
+
+OpenCode does not let a plugin swap the model inside a failed stream. This plugin starts a new prompt in the same session with the last user message and the fallback model.
+
+It does not restore a half-finished tool-call turn. If the model failed after starting tool calls, the retry is a new model turn from the last user request.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { ModelFallbackPlugin, default } from "./plugin";

package/dist/index.js

@@ -0,0 +1,385 @@
+// @bun
+// src/plugin.ts
+import { tool } from "@opencode-ai/plugin/tool";
+var DEFAULT_CONFIG = {
+  enabled: true,
+  fallbackModels: [],
+  unavailableModels: [],
+  retryOnErrors: [429, 500, 502, 503, 504],
+  maxAttempts: 3,
+  cooldownMs: 60000,
+  notify: true
+};
+var RETRYABLE_PATTERNS = [
+  /rate.?limit/i,
+  /too.?many.?requests/i,
+  /quota.?exceeded/i,
+  /exceeded.*quota/i,
+  /usage\s*quota/i,
+  /all.*credentials.*for.*model/i,
+  /cool(?:ing)?.?down/i,
+  /model.{0,20}?not.{0,10}?supported/i,
+  /model_not_supported/i,
+  /service.?unavailable/i,
+  /overloaded/i,
+  /temporarily.?unavailable/i,
+  /try.?again/i,
+  /(?:^|\s)429(?:\s|$)/,
+  /(?:^|\s)503(?:\s|$)/,
+  /(?:^|\s)529(?:\s|$)/
+];
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringField(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function normalizeOptions(options = {}) {
+  const fallbackModels = Array.isArray(options.fallback_models) ? options.fallback_models : DEFAULT_CONFIG.fallbackModels;
+  const unavailableModels = Array.isArray(options.unavailable_models) ? options.unavailable_models : DEFAULT_CONFIG.unavailableModels;
+  return {
+    enabled: options.enabled ?? DEFAULT_CONFIG.enabled,
+    fallbackModels: fallbackModels.filter((model) => typeof model === "string" && parseModel(model) !== undefined),
+    unavailableModels: unavailableModels.filter((model) => typeof model === "string" && parseModel(model) !== undefined),
+    retryOnErrors: options.retry_on_errors ?? DEFAULT_CONFIG.retryOnErrors,
+    maxAttempts: options.max_attempts ?? DEFAULT_CONFIG.maxAttempts,
+    cooldownMs: options.cooldown_ms ?? DEFAULT_CONFIG.cooldownMs,
+    notify: options.notify ?? DEFAULT_CONFIG.notify
+  };
+}
+function parseModel(model) {
+  const [providerID, ...modelParts] = model.split("/");
+  if (!providerID || modelParts.length === 0)
+    return;
+  return { providerID, modelID: modelParts.join("/") };
+}
+function normalizeModel(model) {
+  if (typeof model === "string")
+    return model;
+  if (!isRecord(model))
+    return;
+  const providerID = stringField(model, "providerID");
+  const modelID = stringField(model, "modelID") ?? stringField(model, "id");
+  return providerID && modelID ? `${providerID}/${modelID}` : undefined;
+}
+function resolveSessionID(properties) {
+  const props = isRecord(properties) ? properties : undefined;
+  const info = isRecord(props?.info) ? props.info : undefined;
+  return stringField(props, "sessionID") ?? stringField(info, "sessionID") ?? stringField(info, "id");
+}
+function resolveEventModel(properties) {
+  const props = isRecord(properties) ? properties : undefined;
+  const info = isRecord(props?.info) ? props.info : undefined;
+  const providerID = stringField(props, "providerID");
+  const modelID = stringField(props, "modelID");
+  return normalizeModel(props?.model) ?? normalizeModel(info?.model) ?? (providerID && modelID ? `${providerID}/${modelID}` : undefined);
+}
+function statusCode(error) {
+  if (!isRecord(error))
+    return;
+  const direct = error.statusCode ?? error.status ?? error.code;
+  if (typeof direct === "number")
+    return direct;
+  if (typeof direct === "string" && /^\d+$/.test(direct))
+    return Number(direct);
+  const data = isRecord(error.data) ? error.data : undefined;
+  const dataStatus = data?.statusCode ?? data?.status ?? data?.code;
+  if (typeof dataStatus === "number")
+    return dataStatus;
+  if (typeof dataStatus === "string" && /^\d+$/.test(dataStatus))
+    return Number(dataStatus);
+  const response = isRecord(error.response) ? error.response : undefined;
+  const responseStatus = response?.status;
+  return typeof responseStatus === "number" ? responseStatus : undefined;
+}
+function errorText(error) {
+  if (typeof error === "string")
+    return error;
+  if (error instanceof Error)
+    return `${error.name} ${error.message}`;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+function isRetryableError(error, retryOnErrors) {
+  const status = statusCode(error);
+  if (status !== undefined && retryOnErrors.includes(status))
+    return true;
+  const text = errorText(error);
+  return RETRYABLE_PATTERNS.some((pattern) => pattern.test(text));
+}
+function extractMessages(response) {
+  if (Array.isArray(response))
+    return response;
+  if (isRecord(response) && Array.isArray(response.data))
+    return response.data;
+  return [];
+}
+function extractParts(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.filter((part) => {
+    return isRecord(part) && typeof part.type === "string";
+  });
+}
+function getLastUserPayload(messagesResponse) {
+  const lastUserMessage = extractMessages(messagesResponse).filter((message) => isRecord(message) && isRecord(message.info) && message.info.role === "user").pop();
+  if (!isRecord(lastUserMessage))
+    return { parts: [] };
+  const info = isRecord(lastUserMessage.info) ? lastUserMessage.info : undefined;
+  const messageParts = extractParts(lastUserMessage.parts);
+  const infoID = stringField(info, "id");
+  const parts = messageParts.length > 0 ? messageParts : extractParts(info?.parts);
+  return {
+    parts,
+    ...infoID ? { messageID: infoID } : {}
+  };
+}
+function getState(states, sessionID, model, agent) {
+  let state = states.get(sessionID);
+  if (!state) {
+    state = {
+      originalModel: model,
+      currentModel: model,
+      agent,
+      attempts: 0,
+      failedUntil: new Map
+    };
+    states.set(sessionID, state);
+    return state;
+  }
+  if (agent)
+    state.agent = agent;
+  if (!state.originalModel && model)
+    state.originalModel = model;
+  if (!state.currentModel && model)
+    state.currentModel = model;
+  return state;
+}
+function isEnabled(config, state) {
+  return state?.enabledOverride ?? config.enabled;
+}
+function nextModel(config, state) {
+  const now = Date.now();
+  return config.fallbackModels.find((model) => {
+    if (model === state.currentModel)
+      return false;
+    return (state.failedUntil.get(model) ?? 0) <= now;
+  });
+}
+function firstFallbackFor(config, model) {
+  return config.fallbackModels.find((fallbackModel) => fallbackModel !== model);
+}
+function fallbackForUnavailable(config, model) {
+  if (!model || !config.unavailableModels.includes(model))
+    return;
+  return firstFallbackFor(config, model);
+}
+function resetState(state) {
+  state.currentModel = state.originalModel;
+  state.attempts = 0;
+  state.failedUntil.clear();
+  state.enabledOverride = undefined;
+  state.pendingModel = undefined;
+  state.awaitingModel = undefined;
+}
+function statusText(config, state) {
+  const enabled = isEnabled(config, state);
+  return JSON.stringify({
+    enabled,
+    defaultEnabled: config.enabled,
+    override: state?.enabledOverride ?? null,
+    currentModel: state?.currentModel ?? null,
+    originalModel: state?.originalModel ?? null,
+    attempts: state?.attempts ?? 0,
+    maxAttempts: config.maxAttempts,
+    fallbackModels: config.fallbackModels,
+    unavailableModels: config.unavailableModels
+  });
+}
+function createModelFallbackPlugin(input, options = {}) {
+  const config = normalizeOptions(options);
+  const states = new Map;
+  const inFlight = new Set;
+  async function showToast(message) {
+    if (!config.notify)
+      return;
+    await input.client.tui?.showToast?.({
+      body: {
+        title: "Model Fallback",
+        message,
+        variant: "warning",
+        duration: 5000
+      }
+    }).catch(() => {
+      return;
+    });
+  }
+  async function retryWithModel(sessionID, state, model) {
+    const parsed = parseModel(model);
+    if (!parsed)
+      return false;
+    const messages = await input.client.session.messages({
+      path: { id: sessionID },
+      query: { directory: input.directory }
+    });
+    const payload = getLastUserPayload(messages);
+    if (payload.parts.length === 0)
+      return false;
+    await input.client.session.promptAsync({
+      path: { id: sessionID },
+      query: { directory: input.directory },
+      body: {
+        model: parsed,
+        parts: payload.parts,
+        ...state.agent ? { agent: state.agent } : {},
+        ...payload.messageID ? { messageID: payload.messageID } : {}
+      }
+    });
+    return true;
+  }
+  return {
+    config: async (opencodeConfig) => {
+      if (!config.enabled)
+        return;
+      const rootFallback = fallbackForUnavailable(config, opencodeConfig.model);
+      if (rootFallback)
+        opencodeConfig.model = rootFallback;
+      for (const agent of Object.values(opencodeConfig.agent ?? {})) {
+        if (!agent)
+          continue;
+        const agentFallback = fallbackForUnavailable(config, agent.model);
+        if (agentFallback)
+          agent.model = agentFallback;
+      }
+    },
+    tool: {
+      model_fallback_control: tool({
+        description: "Enable, disable, inspect, or reset model fallback for the current OpenCode session.",
+        args: {
+          action: tool.schema.string().describe("Session fallback action: enable, disable, status, or reset")
+        },
+        execute: async (args, context) => {
+          const state = getState(states, context.sessionID, undefined, context.agent);
+          if (args.action === "enable") {
+            state.enabledOverride = true;
+            return statusText(config, state);
+          }
+          if (args.action === "disable") {
+            state.enabledOverride = false;
+            return statusText(config, state);
+          }
+          if (args.action === "reset") {
+            resetState(state);
+            return statusText(config, state);
+          }
+          if (args.action !== "status") {
+            return `Unknown action: ${args.action}. Use enable, disable, status, or reset.`;
+          }
+          return statusText(config, state);
+        }
+      })
+    },
+    event: async ({ event }) => {
+      const props = isRecord(event.properties) ? event.properties : {};
+      const sessionID = resolveSessionID(props);
+      if (!sessionID)
+        return;
+      if (event.type === "session.created") {
+        const info = isRecord(props.info) ? props.info : undefined;
+        getState(states, sessionID, resolveEventModel(props), stringField(info, "agent"));
+        return;
+      }
+      if (event.type === "session.deleted") {
+        states.delete(sessionID);
+        inFlight.delete(sessionID);
+        return;
+      }
+      if (event.type !== "session.error")
+        return;
+      if (inFlight.has(sessionID))
+        return;
+      const state = getState(states, sessionID, resolveEventModel(props), stringField(props, "agent"));
+      if (!isEnabled(config, state))
+        return;
+      if (config.fallbackModels.length === 0)
+        return;
+      if (!isRetryableError(props.error, config.retryOnErrors))
+        return;
+      if (state.attempts >= config.maxAttempts)
+        return;
+      const eventModel = resolveEventModel(props);
+      if (state.awaitingModel && eventModel && eventModel !== state.awaitingModel)
+        return;
+      state.awaitingModel = undefined;
+      const failedModel = eventModel ?? state.currentModel;
+      if (failedModel) {
+        state.currentModel = failedModel;
+        state.failedUntil.set(failedModel, Date.now() + config.cooldownMs);
+      }
+      const model = nextModel(config, state);
+      if (!model)
+        return;
+      inFlight.add(sessionID);
+      try {
+        const accepted = await retryWithModel(sessionID, state, model);
+        if (!accepted)
+          return;
+        state.attempts += 1;
+        state.currentModel = model;
+        state.pendingModel = model;
+        state.awaitingModel = model;
+        await showToast(`Switched to ${model}`);
+      } finally {
+        inFlight.delete(sessionID);
+      }
+    },
+    "chat.message": async (chatInput, output) => {
+      const requestedModel = normalizeModel(chatInput.model);
+      const state = states.get(chatInput.sessionID) ?? (requestedModel ? getState(states, chatInput.sessionID, requestedModel, chatInput.agent) : undefined);
+      if (!state || !isEnabled(config, state))
+        return;
+      if (requestedModel === state.pendingModel) {
+        state.pendingModel = undefined;
+        return;
+      }
+      if (requestedModel && config.unavailableModels.includes(requestedModel)) {
+        const fallbackModel = firstFallbackFor(config, requestedModel);
+        const parsed2 = fallbackModel ? parseModel(fallbackModel) : undefined;
+        if (!parsed2)
+          return;
+        state.originalModel = requestedModel;
+        state.currentModel = fallbackModel;
+        state.pendingModel = fallbackModel;
+        output.message.model = parsed2;
+        return;
+      }
+      if (!state.currentModel)
+        return;
+      if (requestedModel && requestedModel !== state.currentModel) {
+        state.originalModel = requestedModel;
+        state.currentModel = requestedModel;
+        state.attempts = 0;
+        state.failedUntil.clear();
+        state.pendingModel = undefined;
+        state.awaitingModel = undefined;
+        return;
+      }
+      if (state.currentModel === state.originalModel)
+        return;
+      const parsed = parseModel(state.currentModel);
+      if (parsed)
+        output.message.model = parsed;
+    }
+  };
+}
+var plugin = async (input, options) => createModelFallbackPlugin(input, options);
+var ModelFallbackPlugin = plugin;
+var plugin_default = plugin;
+export {
+  plugin_default as default,
+  ModelFallbackPlugin
+};

package/dist/plugin.d.ts

@@ -0,0 +1,129 @@
+export type Options = {
+    enabled?: boolean;
+    fallback_models?: string[];
+    unavailable_models?: string[];
+    retry_on_errors?: number[];
+    max_attempts?: number;
+    cooldown_ms?: number;
+    notify?: boolean;
+};
+type Config = {
+    enabled: boolean;
+    fallbackModels: string[];
+    unavailableModels: string[];
+    retryOnErrors: number[];
+    maxAttempts: number;
+    cooldownMs: number;
+    notify: boolean;
+};
+type ModelRef = {
+    providerID: string;
+    modelID: string;
+};
+type PromptPart = {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+};
+type LastUserPayload = {
+    parts: PromptPart[];
+    messageID?: string;
+};
+type RuntimeEventInput = {
+    event: {
+        type: string;
+        properties?: unknown;
+    };
+};
+type ChatMessageInput = {
+    sessionID: string;
+    agent?: string;
+    model?: ModelRef;
+};
+type ChatMessageOutput = {
+    message: {
+        model?: ModelRef;
+    };
+    parts: PromptPart[];
+};
+type OpenCodeConfigInput = {
+    model?: string;
+    agent?: Record<string, {
+        model?: string;
+    } | undefined>;
+};
+type RuntimeInput = {
+    directory: string;
+    client: {
+        session: {
+            messages(input: unknown): Promise<unknown>;
+            promptAsync(input: unknown): Promise<unknown>;
+        };
+        tui?: {
+            showToast?(input: {
+                body: {
+                    title: string;
+                    message: string;
+                    variant: "warning";
+                    duration: number;
+                };
+            }): Promise<unknown>;
+        };
+    };
+};
+export declare function normalizeOptions(options?: Options): Config;
+export declare function parseModel(model: string): ModelRef | undefined;
+export declare function normalizeModel(model: unknown): string | undefined;
+export declare function resolveSessionID(properties: unknown): string | undefined;
+export declare function resolveEventModel(properties: unknown): string | undefined;
+export declare function isRetryableError(error: unknown, retryOnErrors: number[]): boolean;
+export declare function getLastUserPayload(messagesResponse: unknown): LastUserPayload;
+export declare function createModelFallbackPlugin(input: RuntimeInput, options?: Options): {
+    config: (opencodeConfig: OpenCodeConfigInput) => Promise<void>;
+    tool: {
+        model_fallback_control: {
+            description: string;
+            args: {
+                action: import("zod").ZodString;
+            };
+            execute(args: {
+                action: string;
+            }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+        };
+    };
+    event: ({ event }: RuntimeEventInput) => Promise<void>;
+    "chat.message": (chatInput: ChatMessageInput, output: ChatMessageOutput) => Promise<void>;
+};
+declare const plugin: (input: import("@opencode-ai/plugin").PluginInput, options: import("@opencode-ai/plugin").PluginOptions | undefined) => Promise<{
+    config: (opencodeConfig: OpenCodeConfigInput) => Promise<void>;
+    tool: {
+        model_fallback_control: {
+            description: string;
+            args: {
+                action: import("zod").ZodString;
+            };
+            execute(args: {
+                action: string;
+            }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+        };
+    };
+    event: ({ event }: RuntimeEventInput) => Promise<void>;
+    "chat.message": (chatInput: ChatMessageInput, output: ChatMessageOutput) => Promise<void>;
+}>;
+export declare const ModelFallbackPlugin: (input: import("@opencode-ai/plugin").PluginInput, options: import("@opencode-ai/plugin").PluginOptions | undefined) => Promise<{
+    config: (opencodeConfig: OpenCodeConfigInput) => Promise<void>;
+    tool: {
+        model_fallback_control: {
+            description: string;
+            args: {
+                action: import("zod").ZodString;
+            };
+            execute(args: {
+                action: string;
+            }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+        };
+    };
+    event: ({ event }: RuntimeEventInput) => Promise<void>;
+    "chat.message": (chatInput: ChatMessageInput, output: ChatMessageOutput) => Promise<void>;
+}>;
+export default plugin;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@shutovks/opencode-model-fallback",
+  "version": "1.0.7",
+  "description": "OpenCode plugin that retries failed sessions with fallback models.",
+  "homepage": "https://github.com/ShutovKS/opencode-model-fallback#readme",
+  "bugs": {
+    "url": "https://github.com/ShutovKS/opencode-model-fallback/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShutovKS/opencode-model-fallback.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && bun build ./src/index.ts --target bun --format esm --outfile dist/index.js --external @opencode-ai/plugin --external @opencode-ai/plugin/tool --external zod && tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "model-fallback",
+    "fallback",
+    "retry"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.15.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.15.13",
+    "@types/bun": "latest",
+    "typescript": "^5.9.2"
+  }
+}