@dylanrussell/agent-router 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 2.1.0
+
+- Add opt-in account-scoped quota preflight before automatic main turns and new subagent tasks, using the usage service's credential-free RPC.
+- Skip only fresh confirmed exhausted candidates; unknown quota keeps the primary. Paid fallback requires explicit approval.
+- Add session-scoped `router_pin`, `router_auto`, and `router_routing_status` controls. Pins survive restarts with bounded storage and deletion cleanup.
+- Preserve staged next-turn reactive fallback precedence, manual overrides, and completed tools. No automatic mid-task retry is enabled.
+- Verify native main/child admission, quota recovery, durable pinning, timeout handling, and concurrent admission/disposal guards.
+
+# 2.0.2
+
+- Simplify stack chains to one model per line in precedence order, without Primary/Fallback labels.
+- Highlight the live session's selected agent/model with native theme color, bold text and a marker; show out-of-chain selections separately.
+- React to session model/agent changes, normalize default variants, and wrap full provider/model identities in narrow sidebars.
+
 # 2.0.1
 
 - Normalize V2's `default` variant so pending next-user-turn fallback is not disabled by an equivalent model reference.
@@ -21,6 +35,6 @@
 
 - Applying/backing out stacks still requires restarting OpenCode to reload agent files.
 - Terminal stack operations access local files; remote-server filesystem management is not supported.
-- Fallback notices are server logs. The sidebar shows configured routing, not session-local fallback state.
+- Fallback notices are server logs. The sidebar shows configured routing with the current session selection highlighted; it does not expose pending fallback state.
 - OpenCode 2.0.8 does not identify request kind on retry hooks. The plugin conservatively tracks the last model-request kind and only handles primary requests. Concurrent auxiliary requests can suppress fallback handling.
 - Session defaults must resolve to explicit agent/model selections before routing. Fallback routing is bounded to 1,024 tracked sessions per plugin instance.

package/README.md

@@ -175,7 +175,102 @@ Duplicate failures advance only once per admitted user turn. Routing budgets are
 
 **Verified boundary:** compiled against the published **2.0.8** API types. Deterministic adapter tests cover next-turn selection, retry veto, auxiliary-request exclusion, variants, and no replay or persistent agent writes. These are not real-provider end-to-end tests. An LLM may choose to repeat a tool when explicitly asked to continue.
 
-OpenCode 2.0.8 exposes no atomic compare-and-switch in the prompt hook and no request kind in the retry hook. Concurrent manual selections/admissions or auxiliary requests remain host API limitations. The sidebar displays configured routing, not the session-local runtime candidate. Terminal stack operations require local filesystem access; remote server filesystem management is not supported.
+OpenCode 2.0.8 exposes no atomic compare-and-switch in the prompt hook and no request kind in the retry hook. Concurrent manual selections/admissions or auxiliary requests remain host API limitations. The sidebar displays configured routing and highlights the current session selection, not pending fallback state. Terminal stack operations require local filesystem access; remote server filesystem management is not supported.
+
+### Opt-in quota preflight (phase 1)
+
+The server plugin can consult the usage-tracker server's `direct-api-usage.query`
+RPC before each new explicit main-session prompt and each new native `subagent`
+start. Configure the server plugin using the object form:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@dylanrussell/agent-router",
+      "options": {
+        "quotaPreflight": {
+          "enabled": true,
+          "allowPaidFallbacks": false
+        }
+      }
+    }
+  ]
+}
+```
+
+Both options default to `false`. Existing applied fallback chains supply candidate
+order; preflight never writes agent frontmatter, router state, or stacks. A staged
+reactive fallback has precedence on the next eligible admission, even when the
+primary has available or unknown quota. Preflight checks that backup and later
+candidates for known exhaustion. Otherwise, each eligible admission reconsiders
+the configured primary. Retry hooks and same-turn retry behavior are unchanged.
+
+- Only fresh, account-and-scope-matched `exhausted` evidence skips a candidate.
+  An available or unknown primary remains the primary. Expired observations,
+  reached resets, unavailable methods, malformed replies, and timeouts are unknown.
+- After earlier candidates are exhausted, an unknown backup with a service-proven
+  subscription binding may be tried. Without that binding, selecting a backup
+  requires explicit `allowPaidFallbacks: true`, which permits potentially paid
+  configured backups. If no eligible candidate remains, selection is unchanged.
+- The usage service owns shared caching, bounded stale refreshes, credential
+  resolution, explicit Headroom/Go account bindings, and model-specific OpenAI
+  scope matching. Router receives opaque references and quota decisions only;
+  it neither polls providers nor infers account equivalence from provider names.
+- Quota queries have a 3-second caller deadline and at most 16 outstanding calls,
+  including timed-out calls that ignore cancellation. Excess admissions use
+  unknown evidence rather than joining a queue. Admission ownership is bounded
+  to 1,024 sessions and concurrent main admission checks to 64.
+- Explicit initial model selections and observable manual selections take priority,
+  including selections equal to the configured primary. Native child overrides
+  are checked before model resolution in `tool.execute.before`; resumed children
+  are excluded. Main sessions whose agent is unresolved are left native.
+- Automatic selection ownership is in memory. After plugin restart, a stored
+  model is conservatively treated as pinned; explicit pins also persist in
+  plugin-scoped server storage. A second session read and observed
+  selection events guard asynchronous admission, but the host offers no atomic
+  compare-and-switch.
+
+**Explicit session controls:** with preflight enabled, the server exposes three
+additional tools. Pin/auto tools are for explicit user requests, under the host's
+normal tool-permission policy. They take no model or session arguments; their
+scope is the calling session.
+
+- `router_pin` freezes the current selection, resolving the native agent/default
+  model when no selection is stored. It disables quota preflight and clears staged
+  reactive fallback for this session. The pin persists in server plugin storage.
+  Pins share one durable value capped at 1,024 sessions across restarts. Serialized
+  writes prevent lost updates; session deletion removes its durable pin, including
+  when deletion races a pin write. Plugin cleanup drains dispatched pin writes.
+- `router_auto` clears the explicit pin and authorizes automatic routing on the
+  **next explicit user turn**. It neither switches the model nor sends a prompt.
+  Automatic ownership is not restored across plugin restarts: use this control
+  again to opt an existing selected session back in.
+- `router_routing_status` reports `automatic`/`pinned`, the current model, and a
+  concise reason. Admissions and controls also write concise server-log notices
+  such as `primary_unknown`, `known_exhaustion_fallback`, and
+  `staged_reactive_fallback`.
+
+**Picker boundary:** OpenCode 2.0.8 treats selecting the already-active model as a
+no-op and emits no selection event. Selecting an automatic fallback again in the
+standard picker does **not** pin it. Explicitly request `router_pin` to freeze it;
+request `router_auto` when ready to resume automatic routing. Different-model
+picker selections remain observable and take priority.
+
+`npm run build && npm run test:quota` exercises the production router and a fake
+quota RPC on a private native 2.0.8 host, including true native child starts,
+fresh/exhausted/unknown/reset evidence, explicit pin/auto controls, staged 429/503
+precedence, timeout, recovery, and tool continuation without midtask switching.
+It explicitly reports the native same-model picker boundary.
+`scripts/probe-admission-v2.mjs` independently records
+native admission/provenance behavior. Neither script contacts real quota APIs.
+Set `USAGE_TRACKER_SOURCE` to the usage-tracker source directory to run the same
+native main/child checks with its actual RPC definition and quota implementation,
+using synthetic credentials and direct-provider response fixtures. Service-side
+account approvals belong in usage-tracker's `options.quotaBindings`, whose records
+use `{ providerID, source, models, connection: { type, id }, approval }` for saved
+credentials (`{ type: "env", name }` for environment connections). Router options
+do not contain credentials or binding attestations.
 
 ### Install This Checkout
 
@@ -210,8 +305,8 @@ The plugin exposes six tools the agent (or you, by asking it) can call:
 
 The V2 terminal half loads from the package's `./tui` export (`cli.json`, wired up by `init`):
 
-- **Sidebar panel** — lists available stacks with the active one checked. Under **Current Stack → Configured routing**, each agent has an indented **Primary** model and ordered **Fallback 1**, **Fallback 2**, … rows. Explicit variants appear in brackets; agents without fallbacks show only their primary. Model IDs are kept in full. A `⟳ restart required` badge appears when the active stack differs from the one at TUI startup. Updates live (≤1.5s), including fallback-only and variant-only edits.
-- **Configuration, not live failover** — sidebar chains come from the active stack file, not session-local routing or the applied `state.json.fallbackAgents` snapshot. Editing a stack changes this preview but does not apply it: use the stack and restart opencode to activate changes. A fallback row is a configured candidate, not a claim that failover is enabled or that the model is currently running.
+- **Sidebar panel** — lists available stacks with the active one checked. Under **Current Stack**, each agent has one indented model per line, in precedence order, without Primary/Fallback labels. Explicit variants appear in brackets; full model IDs wrap rather than truncate. A `⟳ restart required` badge appears when the active stack differs from the one at TUI startup. File changes update live (≤1.5s).
+- **Current selection** — the live session's agent/model is highlighted in color and bold with `●`; out-of-chain selections get a separate Current row. Other agents are not presented as live selections. Configured chains still come from the active stack file, not the applied `state.json.fallbackAgents` snapshot. Editing a stack changes the preview but does not apply it: use the stack and restart opencode to activate changes. The marker reflects session selection, not proof that a request is running or that failover is enabled.
 - **Commands** — type `/` or open the command palette:
 
 | command | what it does |

package/dist/cli.js

@@ -17006,7 +17006,7 @@ async function exportStack(paths, name, toFile) {
 }
 
 // src/version.ts
-var VERSION = "2.0.1";
+var VERSION = "2.1.0";
 
 // src/cli.ts
 var log = (...args) => console.log(...args);