opencode-model-failover 0.1.0-beta.2 → 0.1.0-beta.22

package/README.md

@@ -22,6 +22,8 @@ v2-native.
   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.
+- **Forward progress.** Each failure advances along your chain instead of
+  re-selecting the entry that just failed, so later providers are reachable.
 
 ## Requirements
 
@@ -88,40 +90,67 @@ plugin entry in your OpenCode config:
 }
 ```
 
-| 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.             |
+| Option           | Type       | Default | Description                                       |
+| ---------------- | ---------- | ------- | ------------------------------------------------- |
+| `fallbackModels` | `string[]` | `[]`    | Ordered `provider/model` chain, tried in order.   |
+| `maxAttempts`    | `number`   | `2`     | Failovers per failure sequence 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:
+The plugin subscribes to the v2 event stream:
 
 ```js
 ctx.event.subscribe({ signal })
-// session.execution.failed
-//   -> { data: { sessionID, error: { type, message } } }
+// session.execution.failed        -> { data: { sessionID, error: { type, message } } }
+// session.execution.succeeded     -> { data: { sessionID } }
+// session.execution.interrupted   -> { data: { sessionID } }
+// session.model.selected          -> { data: { sessionID, model: { providerID, id } } }
+// session.step.started            -> { data: { sessionID, model: { providerID, id } } }
+// session.deleted                 -> { data: { sessionID } }
 ```
 
-On a retryable failure it:
+On a retryable `session.execution.failed` 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;
+2. picks the first chain entry that resolves, is not cooling down, is not the
+   model the session is already on, and has not been tried in this failure
+   sequence;
 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.
+### Progression and reset
+
+`maxAttempts` counts failovers within one failure sequence, not per session
+lifetime, and each completed switch is remembered so the next failure moves to
+the entry after it. That is what lets a session reach a later provider: without
+it every failure re-selected the first available entry.
+
+- A failed `switchModel` is a provider problem, not a failed inference: the
+  model is cooled down for `cooldownMs`, but no attempt is used and the chain
+  position does not move.
+- A failed *inference* does not cool the model down. It advances this session's
+  position instead, so a sibling session can still land on that model: the
+  failure is the model's problem for this request, and a process-wide cooldown
+  would take a working model away from everyone.
+- `session.execution.succeeded` and `session.execution.interrupted` end the
+  sequence, so the next failure starts at the top of the chain again.
+- `session.model.selected` and `session.step.started` record the model the
+  session is on, so a failure never selects that model again in the same
+  sequence.
+- `session.deleted` drops the session's state.
+
+The `id`/`setup` plugin shape, the `plugins` config key, and the methods above
+are the whole v2 surface it uses.
 
 ## Observing it
 
@@ -157,6 +186,16 @@ Every push to a PR publishes an installable beta to the npm `beta` dist-tag:
 opencode plugin add opencode-model-failover@beta
 ```
 
+## Development
+
+```bash
+npm install
+npm run lint       # biome check + markdownlint-cli2
+npm run lint:fix   # apply safe fixes
+npm test           # node:test
+npm run check      # lint + test
+```
+
 ## Releases (maintainers)
 
 All publishing happens in GitHub Actions via npm **trusted publishing** (OIDC
@@ -167,9 +206,11 @@ 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.
+  `vX.Y.Z` tag, and opens a GitHub release. The version is the highest of the
+  newest stable `vX.Y.Z` tag and the registry's `latest`, plus a patch, so
+  repeated merges never collide; an intentional minor/major bump in
+  `package.json` is honored. A publish that hits `E409` bumps a patch and
+  retries (bounded), because the registry read can lag a fresh publish.
 - tag `v*-beta*` → `publish` job publishes `beta` plus a prerelease GitHub
   release.
 - every PR push → `prerelease` job publishes `<version>-beta.<run_number>` to
@@ -177,11 +218,13 @@ publisher per package; the workflow filename must stay `ci.yml`):
 - 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.
+not exist yet, so `opencode-model-failover` must be published once by hand before
+the workflow can publish. Then configure the trusted publisher on npmjs.com:
+repository `nabheet/opencode-model-failover`, workflow filename `ci.yml`, and
+tick **Allow `npm publish`**. A trusted publisher created after Sep 03 2026 is
+stage-only by default, and stage-only sends CI publishes to the staging area to
+wait for a 2FA approval instead of going live. A new config must also complete
+its first successful publish within 2 days or it expires.
 
 ## License
 

package/index.js

@@ -1,42 +1,11 @@
-// 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.
+// OpenCode v2 plugin. Options and behaviour: see README.md.
 
 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.
+// Ships empty: the chain is yours to define.
 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.
+// Only retryable failures are worth failing over on; a validation error fails on every model.
 const RETRYABLE =
   /no-route|provider\.|rate|quota|overload|unavailable|server|timeout|econn|socket|network|502|503|504|429/i;
 
@@ -58,11 +27,12 @@ export default {
     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 logFile =
+      typeof opt.logFile === "string" ? opt.logFile : process.env.MODEL_FALLBACK_LOG || "";
 
-    const attempts = new Map(); // sessionID -> failovers used
+    const attempts = new Map(); // sessionID -> failovers used in this failure sequence
+    const attempted = new Map(); // sessionID -> Set of refs already tried in this sequence
+    const current = new Map(); // sessionID -> "provider/model" selected for the session
     const busy = new Set(); // sessionID -> failover in flight
     const cooldown = new Map(); // "provider/model" -> epoch ms it is usable again
 
@@ -72,9 +42,7 @@ export default {
       if (logFile) {
         try {
           appendFileSync(logFile, `${line}\n`);
-        } catch {
-          /* best effort */
-        }
+        } catch {}
       }
       if (notify) console.error(line);
     };
@@ -98,9 +66,9 @@ export default {
       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);
+        const role = row.role || row.info?.role;
         if (role !== "user") continue;
-        const parts = row.parts || (row.info && row.info.parts) || [];
+        const parts = row.parts || row.info?.parts || [];
         const text = parts
           .filter((p) => p && p.type === "text" && typeof p.text === "string")
           .map((p) => p.text)
@@ -120,8 +88,22 @@ export default {
 
       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);
+      const tried = attempted.get(sessionID) || new Set();
+      const selected = current.get(sessionID);
+      // The model that just failed must not be picked again even if this
+      // sequence never switched to it (for example the first failure of a
+      // session that started on chain[0]).
+      if (selected) tried.add(selected);
+      log(
+        `availability=${set.size} models; already tried=${tried.size}; looking for next in chain`,
+      );
+      // Skip what the session is already on and what this failure sequence
+      // has already moved to, otherwise the first available entry is picked
+      // forever and later providers are never reached.
+      const next = chain.find(
+        (ref) =>
+          set.has(ref) && (cooldown.get(ref) || 0) <= now && !tried.has(ref) && ref !== selected,
+      );
       if (!next) {
         log("no available model left in chain");
         return;
@@ -130,29 +112,38 @@ export default {
       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) {
+        // A failed switch is a provider problem, not a failed inference: cool
+        // the model down and leave the attempt budget and progression alone,
+        // so the next failure can pick the entry after it.
         cooldown.set(next, Date.now() + cooldownMs);
-        log(`switchModel to ${next} failed: ${e && e.message}`);
+        log(`switchModel to ${next} failed: ${e?.message}`);
         return;
       }
 
+      tried.add(next);
+      attempted.set(sessionID, tried);
+      attempts.set(sessionID, used + 1);
+      // Record the new model immediately: the session.model.selected event
+      // that follows may arrive after the next failure.
+      current.set(sessionID, next);
+      log(
+        `session ${sessionID} moved to ${next} (attempt ${used + 1}/${maxAttempts}) after ` +
+          `${error?.type || "error"}`,
+      );
+
       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}`);
+        log(`autoRetry failed: ${e?.message}`);
       }
     }
 
@@ -160,12 +151,38 @@ export default {
     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 type = event?.type;
+          const sid = event?.data?.sessionID;
+
+          // A completed or user-interrupted run ends the failure sequence, so
+          // the next failure starts at the top of the chain again instead of
+          // inheriting another sequence's progress.
+          if (type === "session.execution.succeeded" || type === "session.execution.interrupted") {
+            if (!sid) continue;
+            attempted.delete(sid);
+            attempts.delete(sid);
+            continue;
+          }
+          if (type === "session.model.selected" || type === "session.step.started") {
+            const model = event.data?.model || {};
+            const id = model.id || model.modelID;
+            if (sid && model.providerID && id) current.set(sid, `${model.providerID}/${id}`);
+            continue;
+          }
+          if (type === "session.deleted") {
+            if (!sid) continue;
+            attempted.delete(sid);
+            attempts.delete(sid);
+            current.delete(sid);
+            continue;
+          }
+          if (type !== "session.execution.failed") continue;
+
+          const error = event.data?.error || {};
+          log(
+            `failed event: session=${sid} error=${error.type} msg=${String(error.message).slice(0, 120)}`,
+          );
+          if (!sid || busy.has(sid)) continue;
 
           const haystack = `${error.type || ""} ${error.message || ""}`;
           if (!RETRYABLE.test(haystack)) {
@@ -173,16 +190,14 @@ export default {
             continue;
           }
 
-          busy.add(sessionID);
+          busy.add(sid);
           try {
-            await failover(sessionID, error);
+            await failover(sid, error);
           } finally {
-            busy.delete(sessionID);
+            busy.delete(sid);
           }
         }
-      } catch {
-        /* stream aborted on unload */
-      }
+      } catch {}
     })();
 
     return () => controller.abort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-model-failover",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.22",
   "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",
@@ -42,11 +42,13 @@
     "access": "public"
   },
   "scripts": {
-    "lint": "markdownlint-cli2",
-    "test": "node --check index.js && node --test test/*.test.mjs",
-    "check": "npm run lint && npm test"
+    "lint": "biome check . && markdownlint-cli2 \"**/*.md\" \"#node_modules/**\" \"#dist/**\" \"#.git/**\"",
+    "lint:fix": "biome check --write . && markdownlint-cli2 --fix \"**/*.md\" \"#node_modules/**\" \"#dist/**\" \"#.git/**\"",
+    "check": "npm run lint && npm test",
+    "test": "node --test test/*.test.mjs"
   },
   "devDependencies": {
-    "markdownlint-cli2": "^0.23.0"
+    "@biomejs/biome": "^2.6.2",
+    "markdownlint-cli2": "^0.24.0"
   }
 }