@dylanrussell/agent-router 1.0.7 → 1.1.0

package/README.md

@@ -105,7 +105,7 @@ The everyday loop: tune your agents until you like them → `capture <name>` →
 
 ## Stacks
 
-A stack file needs one thing: an `agents` record whose entries carry a `model` string. Agent names are the `.md` basenames in your agents dir (`Omni` ↔ `Omni.md`). Any **other key** on an entry is a provider pass-through option (`reasoningEffort`, `thinking`, `temperature`, `topP`, `maxOutputTokens`, …) that opencode forwards to the model — agent-router transcribes these to the agent's frontmatter alongside `model:` and captures them back. Unknown keys are preserved round-trip.
+A stack file needs one thing: an `agents` record whose entries carry a `model` string. Agent names are the `.md` basenames in your agents dir (`Omni` ↔ `Omni.md`). Except for router-owned `fallbacks`, other keys on an entry are provider pass-through options (`reasoningEffort`, `thinking`, `temperature`, `topP`, `maxOutputTokens`, …) that opencode forwards to the model — agent-router transcribes these to the agent's frontmatter alongside `model:` and captures them back. Unknown keys are preserved round-trip.
 
 ```json
 {
@@ -127,6 +127,62 @@ A stack file needs one thing: an `agents` record whose entries carry a `model` s
 
 `capture` is the inverse: it reads the current `model:` line and option keys of every agent file (files without a `model:` line are skipped) and writes a stack. There are no bundled seed stacks — your real setup is the seed.
 
+## Ordered Fallbacks
+
+Optional per-agent fallback chains select a model for the **next explicitly submitted user turn**, not an automatic retry of the failed turn. Enable by adding `fallbacks` to a stack, applying that stack, and restarting opencode with the server plugin loaded:
+
+```json
+{
+  "agents": {
+    "oracle": {
+      "model": "openai/gpt-5.5",
+      "variant": "high",
+      "fallbacks": [
+        { "model": "anthropic/claude-sonnet-4-6", "variant": "low" },
+        { "model": "openai/gpt-5.4-mini" }
+      ]
+    }
+  }
+}
+```
+
+Model IDs and variants above are illustrative; use models and variants supported by your providers.
+
+- `model` remains the primary. Primary `variant` is an optional nonempty string; `null` clears it on apply.
+- `fallbacks` is optional, or an array of 0 to 8 objects. Each object contains only `model` (non-whitespace `provider/model`) and optional `variant` (nonempty string). `null`, bare strings, unknown candidate fields, and longer chains are rejected.
+- Candidate order is preserved. Exact `(model, variant)` duplicates, including the primary, are skipped at runtime. An omitted fallback variant clears the previous candidate's variant.
+- Only model and variant change at runtime. Agent prompts, permissions, tools, and other provider options remain unchanged; ensure those options are compatible with every candidate.
+- Validation checks every primary and fallback ID, reporting paths such as `agents.oracle.fallbacks.0.model`. It checks catalogue membership through `opencode models`, not live provider health, credentials, quota, or variant support. `validate --active` includes applied fallback metadata when its primary still matches frontmatter.
+- Failover does not rewrite frontmatter, stacks, history, or router state. `use` stores the applied chains in optional `state.json.fallbackAgents`. Old state files without that field remain valid and have no enabled chains until the stack is reapplied.
+- `capture` and displaced-history snapshots merge those applied chains with live frontmatter only when primary model and variant still match. Editing a stack alone does not alter applied metadata. Applying a stack without chains clears the applied chains, including agents omitted from that stack.
+- `back` retains its existing semantics: reapply a previous **named stack as it exists now**, not restore historical snapshot bytes. Runtime failover never adds a history entry.
+
+### Runtime Behavior And Limits
+
+The plugin watches correlated assistant `message.updated` errors, requiring the current user-message parent ID, agent, and selected provider/model. It stages the next candidate only for structured `APIError` with `isRetryable: true` and HTTP **429, 500, 502, 503, or 504**. Native opencode retries may occur before the terminal error reaches this hook. Router does not change their policy or timing.
+
+Authentication/permission errors, context overflow, content filtering, output-length errors, unknown errors, transport errors without an HTTP status, and ambiguous `session.error` notifications do not advance the chain. Router never classifies errors by substring matching.
+
+After a qualifying failure a 15-second warning toast (or log fallback) names the next model and asks for an explicit retry/continue instruction. Every notice is also logged under `agent-router`. **Review partial output and completed tools before continuing.** The mutable `chat.message` hook selects the fallback when the next prompt is admitted; no prompt is submitted by this plugin. The successful fallback stays selected for subsequent turns. Chains advance monotonically with at most eight transitions per agent/session; exhaustion produces a notice, never wraps to the primary. There are no timers, background retries, or automatic failback.
+
+Observed cancellation (`MessageAbortedError`), explicit model/agent switch events, and an incoming model/variant different from both the configured primary and current candidate disable routing for that session until restart. A switch to the same model is distinguishable only when the host emits its switch event. Hosts/UI paths that omit both the event and a changed selection cannot expose that manual intent to this plugin. Switching stacks with router tools disables running failover immediately; external CLI/TUI state changes disable it at the next prompt admission. Restart to activate the newly applied stack.
+
+Duplicate/concurrent error events advance only once per user turn. Selection and bookkeeping run synchronously before notification awaits, so delayed notices cannot overwrite cancellation/manual selection. Sessions and per-agent budgets are isolated; deleted/disabled sessions remain tombstones to prevent rearming. After 1,024 tracked sessions in one plugin instance, additional sessions receive no automatic routing until restart. Untracked sessions and subagents that bypass `chat.message` are deliberately left alone.
+
+**Verified boundary:** inspected opencode **v1.17.15** `packages/opencode/src/session/prompt.ts`: `chat.message` mutates the message before `sessions.updateMessage(info)` and the legacy session loop resolves `lastUser.model`. A deterministic in-process provider harness tests those hook semantics, explicit next-turn continuation, variant selection, and no replay/persistent writes. This is **not a real-server end-to-end provider test** and does not prove that every new v2 execution path invokes these legacy hooks. Hosts that bypass them receive no failover. There is no transparent same-turn continuation guarantee, no automatic recovery of a failed `task` invocation, and no guarantee that an LLM will not choose to repeat a tool when explicitly asked to continue.
+
+The installed SDK exposes `/v2` `client.v2.session.switchModel` for subsequent turns, but no atomic compare-and-switch/retry contract was verified. Router deliberately does **not** call it: an asynchronous model write could race a manual selection or cancellation. No direct SDK dependency is needed; plugin hooks are the integration boundary. The TUI model picker and router status still display stack/primary assignments, not session-local runtime candidates.
+
+### Install This Checkout
+
+Ordered fallbacks require agent-router **1.1.0 or later**. To test a local checkout instead of the published package, run `npm run typecheck`, `npm test`, and `npm run build` using the installed dependencies (a fresh checkout uses `pnpm install --frozen-lockfile`). Replace `/absolute/path/to/agent-router` below with your checkout path, then replace the registry router entry in the **server** `opencode.json` plugin array with:
+
+```json
+"file:///absolute/path/to/agent-router/dist/plugin.js"
+```
+
+Do not load both registry and local server plugins. If using the router TUI plugin, also replace its registry entry in `tui.json` with `file:///absolute/path/to/agent-router/dist/tui.js`. Use the checkout's CLI too: older router builds strictly validate state and cannot read the new `fallbackAgents` field. Add a chain to your stack and run `node /absolute/path/to/agent-router/dist/cli.js use <stack-name>`, then quit and restart opencode. These installation/configuration steps are instructions only; implementation and tests do not modify your live agent configuration. Start a new session, and confirm you see the explicit next-turn notice after a qualifying terminal error. Headless clients must inspect the `agent-router` log.
+
 ## Inside opencode
 
 The plugin exposes six tools the agent (or you, by asking it) can call:

package/dist/cli.js

@@ -15244,19 +15244,31 @@ var init_zod = __esm({
 });
 
 // src/core/schema.ts
-var StateFileSchema, AgentEntrySchema, StackFileSchema, ConfigFileSchema, OpencodeJsonSchema;
+var FallbackSchema, RoutingEntrySchema, StateFileSchema, AgentEntrySchema, StackFileSchema, ConfigFileSchema, OpencodeJsonSchema;
 var init_schema = __esm({
   "src/core/schema.ts"() {
     "use strict";
     init_zod();
+    FallbackSchema = external_exports.object({
+      model: external_exports.string().regex(/^[^/\s]+\/\S+$/, "Expected provider/model"),
+      variant: external_exports.string().min(1).optional()
+    }).strict();
+    RoutingEntrySchema = external_exports.object({
+      model: external_exports.string().min(1),
+      variant: external_exports.string().min(1).nullable().optional(),
+      fallbacks: external_exports.array(FallbackSchema).max(8).optional()
+    }).strict();
     StateFileSchema = external_exports.object({
       version: external_exports.literal(1),
       active: external_exports.string().min(1),
       previousActive: external_exports.string().min(1).nullable(),
-      lastSwitchedAt: external_exports.string().min(1)
+      lastSwitchedAt: external_exports.string().min(1),
+      fallbackAgents: external_exports.record(external_exports.string(), RoutingEntrySchema).optional()
     }).strict();
     AgentEntrySchema = external_exports.object({
-      model: external_exports.string().min(1)
+      model: external_exports.string().min(1),
+      variant: external_exports.string().min(1).nullable().optional(),
+      fallbacks: external_exports.array(FallbackSchema).max(8).optional()
     }).passthrough();
     StackFileSchema = external_exports.object({
       agents: external_exports.record(external_exports.string(), AgentEntrySchema)
@@ -16697,6 +16709,9 @@ function collectModelRefs(stack) {
   const refs = [];
   for (const [k, v] of Object.entries(stack.agents)) {
     refs.push({ path: `agents.${k}.model`, modelId: v.model });
+    for (const [index, candidate] of (v.fallbacks ?? []).entries()) {
+      refs.push({ path: `agents.${k}.fallbacks.${index}.model`, modelId: candidate.model });
+    }
   }
   return refs;
 }
@@ -16783,7 +16798,7 @@ async function applyStack(paths, name, options = {}) {
   }
   const prevState = await readState(paths.statePath);
   const prevActive = prevState?.active ?? null;
-  const displaced = { agents: entriesToStackAgents(await readAgentEntries(paths.agentsDir)) };
+  const displaced = { agents: await captureAgents(paths) };
   const historyId = await appendHistory(
     paths.historyDir,
     prevActive ?? "(none)",
@@ -16801,7 +16816,20 @@ async function applyStack(paths, name, options = {}) {
     version: 1,
     active: name,
     previousActive: prevActive,
-    lastSwitchedAt: (/* @__PURE__ */ new Date()).toISOString()
+    lastSwitchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    fallbackAgents: Object.fromEntries(
+      Object.entries(target.agents).filter(([, entry]) => entry.fallbacks?.length).map(([agent, entry]) => {
+        const variant = "variant" in entry ? entry.variant : displaced.agents[agent]?.variant;
+        return [
+          agent,
+          {
+            model: entry.model,
+            variant: typeof variant === "string" ? variant : void 0,
+            fallbacks: entry.fallbacks
+          }
+        ];
+      })
+    )
   });
   await trimHistory(paths.historyDir).catch(() => {
   });
@@ -16817,7 +16845,7 @@ function entryOptions(entry) {
   const rec = entry;
   const out = {};
   for (const [k, v] of Object.entries(rec)) {
-    if (k === "model" || RESERVED_AGENT_KEYS.has(k)) continue;
+    if (k === "model" || k === "fallbacks" || RESERVED_AGENT_KEYS.has(k)) continue;
     out[k] = v;
   }
   return out;
@@ -16829,11 +16857,24 @@ function entriesToStackAgents(entries) {
     if (!entry) continue;
     const { model, options } = entry;
     const stackEntry = { model };
-    for (const [k, v] of Object.entries(options)) stackEntry[k] = v;
+    for (const [k, v] of Object.entries(options)) {
+      if (k !== "fallbacks") stackEntry[k] = v;
+    }
     out[name] = stackEntry;
   }
   return out;
 }
+async function captureAgents(paths) {
+  const agents = entriesToStackAgents(await readAgentEntries(paths.agentsDir));
+  const state = await readState(paths.statePath);
+  for (const [name, entry] of Object.entries(agents)) {
+    const routing = state?.fallbackAgents?.[name];
+    if (routing && routing.model === entry.model && (routing.variant ?? void 0) === (entry.variant ?? void 0)) {
+      entry.fallbacks = routing.fallbacks;
+    }
+  }
+  return agents;
+}
 async function back(paths, n = 1, options = {}) {
   if (n < 1) throw new UserError("`back -n` must be at least 1.");
   const state = await readState(paths.statePath);
@@ -16867,8 +16908,7 @@ async function captureStack(paths, name, options = {}) {
   if (existsSync6(dest) && !options.force) {
     throw new UserError(`Stack "${name}" already exists. Use --force to overwrite.`);
   }
-  const entries = await readAgentEntries(paths.agentsDir);
-  const agents = entriesToStackAgents(entries);
+  const agents = await captureAgents(paths);
   if (Object.keys(agents).length === 0) {
     throw new UserError(
       `No agent .md files with a frontmatter \`model:\` line found in ${paths.agentsDir}.`
@@ -16911,7 +16951,7 @@ async function exportStack(paths, name, toFile) {
 }
 
 // src/version.ts
-var VERSION = "1.0.7";
+var VERSION = "1.1.0";
 
 // src/cli.ts
 var log = (...args) => console.log(...args);
@@ -17066,11 +17106,7 @@ async function cmdValidate(paths, name, opts) {
     targets.push({
       name: "(current frontmatter)",
       load: async () => {
-        const models = await readAgentModels(paths.agentsDir);
-        const agents = Object.fromEntries(
-          Object.entries(models).map(([k, model]) => [k, { model }])
-        );
-        return { agents };
+        return { agents: await captureAgents(paths) };
       }
     });
   } else if (opts.all) {