opencode-model-failover 0.0.0-stage → 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nabheet S. Sandhu
+
+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

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# opencode-model-failover
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Native model failover for [OpenCode](https://opencode.ai) **v2**.
+
+When a session fails because a model is rate-limited, overloaded, or otherwise
+unreachable, this plugin moves the session onto the next healthy model in a
+chain you define. It runs entirely on the OpenCode v2 plugin API: no HTTP
+client, no vendor SDK, no runtime dependencies.
+
+## Why
+
+OpenCode v2 has a different plugin API from v1, and the fallback plugins already
+on npm are written against the v1 API, so they do not load in v2. This plugin is
+v2-native.
+
+- **No chain ships with it.** You name the models. Nothing about the author's
+  provider setup is baked in, and the default chain is empty.
+- **Failures are filtered.** Only retryable errors (rate limits, timeouts,
+  provider and network errors, 429/502/503/504) trigger a failover. A validation
+  error would fail on every model, so it is ignored instead of burning attempts.
+- **Prompt replay is opt-in.** `autoRetry` is off by default, because re-sending
+  a prompt is a state-changing action.
+- **Cooldown.** A model whose switch fails is skipped for `cooldownMs`, so a
+  broken target is not retried on every failure.
+
+## Requirements
+
+- OpenCode **v2** (`opencode --version` reports 2.x).
+- Node **>= 22**.
+
+## Install
+
+### From npm
+
+```bash
+opencode plugin add opencode-model-failover
+```
+
+### From GitHub
+
+```bash
+opencode plugin add github:nabheet/opencode-model-failover
+```
+
+Or add it to `opencode.json(c)` directly:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-model-failover"]
+}
+```
+
+### Manual
+
+Copy this directory to `.opencode/plugins/opencode-model-failover/` (project) or
+`~/.config/opencode/plugins/opencode-model-failover/` (global), then list it:
+
+```jsonc
+{
+  "plugins": [{ "package": "./.opencode/plugins/opencode-model-failover" }]
+}
+```
+
+The v2 loader resolves `index.js` inside the directory; the `package.json`
+`main` field is not consulted.
+
+## Options
+
+The plugin does nothing until you supply a chain. Pass options through the
+plugin entry in your OpenCode config:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-model-failover",
+      "options": {
+        "fallbackModels": ["provider-a/model-x", "provider-b/model-y"],
+        "maxAttempts": 2,
+        "cooldownMs": 60000,
+        "autoRetry": false,
+        "notify": true,
+        "logFile": "/tmp/model-failover.log"
+      }
+    }
+  ]
+}
+```
+
+| Option           | Type       | Default | Description                                     |
+| ---------------- | ---------- | ------- | ----------------------------------------------- |
+| `fallbackModels` | `string[]` | `[]`    | Ordered `provider/model` chain, tried in order. |
+| `maxAttempts`    | `number`   | `2`     | Failovers per session before giving up.         |
+| `cooldownMs`     | `number`   | `60000` | Skip a model this long after a failed switch.   |
+| `autoRetry`      | `boolean`  | `false` | Replay the last user message after switching.   |
+| `notify`         | `boolean`  | `true`  | Log each failover to stderr.                    |
+| `logFile`        | `string`   | `""`    | Also append log lines to this file.             |
+
+A `provider/model` string is split on the first `/`. Entries without a `/` are
+dropped from the chain.
+
+## How it works
+
+The plugin subscribes to the v2 event stream and reacts to one event type:
+
+```js
+ctx.event.subscribe({ signal })
+// session.execution.failed
+//   -> { data: { sessionID, error: { type, message } } }
+```
+
+On a retryable failure it:
+
+1. reads the models that actually resolve with `ctx.model.list()`;
+2. picks the first chain entry that resolves and is not cooling down;
+3. moves the session with `ctx.session.switchModel({ sessionID, model })`.
+
+If `autoRetry` is on, it then reads the transcript with
+`ctx.session.context({ sessionID })` and replays the last user message with
+`ctx.session.prompt({ sessionID, text })`.
+
+The `id`/`setup` plugin shape, the `plugins` config key, and the four methods
+above are the whole v2 surface it uses.
+
+## Observing it
+
+A server-side plugin is easy to miss, so every decision is logged with a
+`[model-failover]` prefix. Set `notify: false` to silence stderr, and
+`logFile` (or the `MODEL_FALLBACK_LOG` environment variable) to append to a
+file:
+
+```bash
+MODEL_FALLBACK_LOG=/tmp/model-failover.log opencode
+```
+
+Typical lines:
+
+```text
+[model-failover] 2026-01-01T00:00:00.000Z setup: chain=[provider-a/model-x] maxAttempts=2 autoRetry=false
+[model-failover] 2026-01-01T00:00:01.000Z failed event: session=ses_123 error=provider.rateLimit msg=429
+[model-failover] 2026-01-01T00:00:01.010Z availability=12 models; looking for next in chain
+[model-failover] 2026-01-01T00:00:01.020Z session ses_123 moved to provider-a/model-x (attempt 1/2)
+```
+
+## Compatibility
+
+- Targets **OpenCode v2** (the `plugins` config key and the `id`/`setup` plugin
+  definition). OpenCode v1 used a different plugin API and is not supported.
+- No runtime dependencies. Only `node:` builtins are imported.
+
+## Prereleases
+
+Every push to a PR publishes an installable beta to the npm `beta` dist-tag:
+
+```bash
+opencode plugin add opencode-model-failover@beta
+```
+
+## Releases (maintainers)
+
+All publishing happens in GitHub Actions via npm **trusted publishing** (OIDC
+provenance). Never publish from a local shell.
+
+`.github/workflows/ci.yml` is the single workflow file (npm allows one trusted
+publisher per package; the workflow filename must stay `ci.yml`):
+
+- `test` — lint + plugin tests on `main` and PRs (Node 24).
+- push to `main` → `publish` job publishes the next patch to `latest`, pushes a
+  `vX.Y.Z` tag, and opens a GitHub release. The version is derived from the last
+  published `latest`, so repeated merges never collide; an intentional
+  minor/major bump in `package.json` is honored.
+- tag `v*-beta*` → `publish` job publishes `beta` plus a prerelease GitHub
+  release.
+- every PR push → `prerelease` job publishes `<version>-beta.<run_number>` to
+  `beta` (same-repo, non-draft, non-dependabot PRs; re-runs deduped).
+- manual dispatch → next `-beta.X` staging publish from `main`, no git change.
+
+One-time bootstrap: npm cannot attach a trusted publisher to a package that does
+not exist yet, so `opencode-model-failover` must be published once by hand
+before the workflow can publish. After that first version exists, configure the
+trusted publisher on npmjs.com (repository `nabheet/opencode-model-failover`,
+workflow filename `ci.yml`, allow `npm publish`), and CI owns every release
+after it.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/index.js

@@ -0,0 +1,190 @@
+// opencode-model-failover — OpenCode v2 plugin.
+//
+// Native model failover built entirely on the OpenCode v2 plugin API:
+//
+//   ctx.event.subscribe()       -> session.execution.failed carries
+//                                  { data: { sessionID, error: { type, message } } }
+//   ctx.model.list()            -> which provider/model pairs actually resolve
+//   ctx.session.switchModel()   -> move the session onto a healthy model
+//   ctx.session.context()       -> read the transcript (only for autoRetry)
+//   ctx.session.prompt()        -> replay the last user message (only for autoRetry)
+//
+// Discovery: a plugin directory exposing index.js is loaded automatically from
+// .opencode/plugins/. Installing the package is enough; a config entry is only
+// needed to pass options:
+//
+//   { "plugins": [
+//       { "package": "opencode-model-failover",
+//         "options": { "fallbackModels": ["provider/model"], "autoRetry": false } } ] }
+//
+// Options (all optional):
+//   fallbackModels  string[]  provider/model chain, tried in order (default: empty)
+//   maxAttempts     number    fallbacks per session (default 2)
+//   cooldownMs      number    skip a failed model this long, in ms (default 60000)
+//   autoRetry       boolean   replay the last user message (default false)
+//   notify          boolean   log each fallback to stderr (default true)
+//   logFile         string    append log lines to this file
+//
+// No chain ships by default: set fallbackModels to your own provider/model
+// pairs. autoRetry is off by default, because replaying a prompt is a
+// state-changing action and is deliberately opt-in.
+
+import { appendFileSync } from "node:fs";
+
+// Ships empty on purpose — the chain is yours to define. Nothing about the
+// author's provider setup is baked in.
+const DEFAULT_CHAIN = [];
+
+// Failure kinds worth failing over on. A bad request or a validation error will
+// fail identically on every model, so retrying those just burns attempts.
+const RETRYABLE =
+  /no-route|provider\.|rate|quota|overload|unavailable|server|timeout|econn|socket|network|502|503|504|429/i;
+
+function splitRef(ref) {
+  const at = String(ref).indexOf("/");
+  if (at <= 0) return null;
+  return { providerID: ref.slice(0, at), modelID: ref.slice(at + 1) };
+}
+
+export default {
+  id: "model-failover",
+  async setup(ctx) {
+    const opt = ctx.options || {};
+    const chain =
+      Array.isArray(opt.fallbackModels) && opt.fallbackModels.length > 0
+        ? opt.fallbackModels.filter((m) => splitRef(m))
+        : DEFAULT_CHAIN;
+    const maxAttempts = Number.isFinite(opt.maxAttempts) ? opt.maxAttempts : 2;
+    const cooldownMs = Number.isFinite(opt.cooldownMs) ? opt.cooldownMs : 60_000;
+    const autoRetry = opt.autoRetry === true;
+    const notify = opt.notify !== false;
+    // Optional file sink — the only reliable way to observe a server-side
+    // plugin. The env var fallback keeps it usable without touching config.
+    const logFile = typeof opt.logFile === "string" ? opt.logFile : process.env.MODEL_FALLBACK_LOG || "";
+
+    const attempts = new Map(); // sessionID -> failovers used
+    const busy = new Set(); // sessionID -> failover in flight
+    const cooldown = new Map(); // "provider/model" -> epoch ms it is usable again
+
+    const log = (msg) => {
+      if (!logFile && !notify) return;
+      const line = `[model-failover] ${new Date().toISOString()} ${msg}`;
+      if (logFile) {
+        try {
+          appendFileSync(logFile, `${line}\n`);
+        } catch {
+          /* best effort */
+        }
+      }
+      if (notify) console.error(line);
+    };
+
+    log(`setup: chain=[${chain.join(", ")}] maxAttempts=${maxAttempts} autoRetry=${autoRetry}`);
+    if (chain.length === 0) {
+      log("no fallbackModels configured; set fallbackModels to enable failover");
+    }
+
+    async function availableRefs() {
+      try {
+        const listed = await ctx.model.list();
+        const rows = listed && Array.isArray(listed.data) ? listed.data : [];
+        return new Set(rows.map((m) => `${m.providerID}/${m.modelID}`));
+      } catch {
+        return new Set();
+      }
+    }
+
+    function lastUserText(messages) {
+      const rows = Array.isArray(messages) ? messages : [];
+      for (let i = rows.length - 1; i >= 0; i--) {
+        const row = rows[i] || {};
+        const role = row.role || (row.info && row.info.role);
+        if (role !== "user") continue;
+        const parts = row.parts || (row.info && row.info.parts) || [];
+        const text = parts
+          .filter((p) => p && p.type === "text" && typeof p.text === "string")
+          .map((p) => p.text)
+          .join("\n")
+          .trim();
+        if (text) return text;
+      }
+      return "";
+    }
+
+    async function failover(sessionID, error) {
+      const used = attempts.get(sessionID) || 0;
+      if (used >= maxAttempts) {
+        log(`max attempts reached for session ${sessionID} (${used}/${maxAttempts})`);
+        return;
+      }
+
+      const set = await availableRefs();
+      const now = Date.now();
+      log(`availability=${set.size} models; looking for next in chain`);
+      const next = chain.find((ref) => set.has(ref) && (cooldown.get(ref) || 0) <= now);
+      if (!next) {
+        log("no available model left in chain");
+        return;
+      }
+
+      const ref = splitRef(next);
+      if (!ref) return;
+
+      attempts.set(sessionID, used + 1);
+      try {
+        await ctx.session.switchModel({
+          sessionID,
+          model: { providerID: ref.providerID, id: ref.modelID },
+        });
+        log(
+          `session ${sessionID} moved to ${next} (attempt ${used + 1}/${maxAttempts}) after ` +
+            `${(error && error.type) || "error"}`,
+        );
+      } catch (e) {
+        cooldown.set(next, Date.now() + cooldownMs);
+        log(`switchModel to ${next} failed: ${e && e.message}`);
+        return;
+      }
+
+      if (!autoRetry) return;
+      try {
+        const transcript = await ctx.session.context({ sessionID });
+        const text = lastUserText(transcript && (transcript.data || transcript));
+        if (text) await ctx.session.prompt({ sessionID, text });
+      } catch (e) {
+        log(`autoRetry failed: ${e && e.message}`);
+      }
+    }
+
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+          if (!event || event.type !== "session.execution.failed") continue;
+          const data = event.data || {};
+          const sessionID = data.sessionID;
+          const error = data.error || {};
+          log(`failed event: session=${sessionID} error=${error.type} msg=${String(error.message).slice(0, 120)}`);
+          if (!sessionID || busy.has(sessionID)) continue;
+
+          const haystack = `${error.type || ""} ${error.message || ""}`;
+          if (!RETRYABLE.test(haystack)) {
+            log(`not retryable, ignoring: ${haystack.slice(0, 120)}`);
+            continue;
+          }
+
+          busy.add(sessionID);
+          try {
+            await failover(sessionID, error);
+          } finally {
+            busy.delete(sessionID);
+          }
+        }
+      } catch {
+        /* stream aborted on unload */
+      }
+    })();
+
+    return () => controller.abort();
+  },
+};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "opencode-model-failover",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "Native model failover for OpenCode v2: move a failed session onto the next healthy model in a chain you define.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-v2",
+    "model-failover",
+    "model-fallback",
+    "failover",
+    "rate-limit",
+    "quota",
+    "resilience",
+    "llm",
+    "ai-coding-agent"
+  ],
+  "license": "MIT",
+  "author": "Nabheet S. Sandhu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nabheet/opencode-model-failover.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nabheet/opencode-model-failover/issues"
+  },
+  "homepage": "https://github.com/nabheet/opencode-model-failover#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "markdownlint-cli2",
+    "test": "node --check index.js && node --test test/*.test.mjs",
+    "check": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.23.0"
+  }
+}