@qadanm/opencode-smart-router 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+Notable changes to OpenCode Smart Router. Dates are the day the change landed on
+`main`.
+
+## Unreleased
+
+### Added
+
+- **Launch kit** (`docs/LAUNCH-KIT.md`): paste-ready copy for Discord, Hacker
+  News, X, and the opencode.cafe submission, plus the demo film assets.
+
+## 0.4.0 — 2026-11-05
+
+Self-healing routing, and npm distribution.
+
+### Added
+
+- **Self-healing routing.** A rebuilt session can carry mid-session notices
+  into the prompt as system roles, which kills the turn on any
+  Anthropic-protocol model with a 400 error. The router folds those notices
+  into user messages before the request leaves, refuses the host retry on a
+  deterministic rejection, and continues the turn on the next best eligible
+  model with one notice. The panel records what was rejected and what took
+  over. Found on a live Command Code session: the error was
+  "Invalid discriminator value. Expected 'user' | 'assistant' at
+  messages.23.role".
+- **npm package** (`@qadanm/opencode-smart-router`). One self-contained file
+  with no runtime dependencies, loadable with a single `plugin` entry so the
+  router appears in OpenCode's own ecosystem path. The full experience stays
+  with the installer.
+
+## 0.3.0 — 2026-11-05
+
+The release where the router gained a face, and where several numbers it had been
+asserting turned out to be wrong.
+
+### Added
+
+- **Desktop panel** (`./gui-experimental`). A side panel in OpenCode Desktop that
+  shows the last routing decision, why the chosen model won, every candidate that
+  lost with the reason, per-provider allowances with all their windows, and the
+  provider list. Built on the OpenCode GUI plugin API, which the SDK marks
+  experimental.
+- **First-run onboarding.** Reports the providers found on this machine, what was
+  imported from history, and what the router will do — before asking for anything.
+  Evidence rather than a questionnaire, because detection already did the finding.
+- **Terminal parity** (`./tui`). `/router-why` and `/router-quota`, plus a footer
+  status slot. Same view-model as the panel, so the two cannot disagree.
+- **Calibration.** The safety margin is now measured from the charges the provider
+  reported rather than assumed. Narrows with evidence; stays wide and warns when
+  the charges imply a wrong price.
+- **History import from OpenCode's own database.** Per-message, so each event
+  carries its real timestamp and the model that actually served it. This is what
+  makes a fixed seven-day window accurate instead of smeared onto session
+  boundaries.
+- **Per-session automatic-routing switch.** Stops the router changing the model
+  without disabling it. `SessionState.paused` existed but nothing read it, so this
+  also fixed a switch that would have silently done nothing.
+- **Account reading by paste.** OpenDesign exposes no usage API, so the estimate
+  can only see traffic the router routed. Pasting the Plan & balance page seeds
+  the real figure. Reconciled against the catalog, which reports disagreement
+  rather than absorbing it.
+
+### Fixed
+
+- **Thirteen OpenDesign models were priced wrong**, some by 4x in both directions.
+  The catalog stored a base price and then applied the Design Plan multiplier on
+  top, and several entries already had the multiplier baked in. Verified against
+  the published CoRouter catalog and pinned by 36 assertions.
+- **The Plus tier had no weekly cap**, making it look able to spend a whole month
+  in one week.
+- **The seven-day window was modelled as rolling** when the vendor documents it as
+  fixed from the subscription start, and the estimator ignored the declaration
+  entirely even after the catalog was corrected.
+- **The reported cost was discarded.** Every step carries the real charge, and the
+  estimator recomputed an approximation of it from a static table instead.
+- **Command Code's DeepSeek V4.1 Flash sent a model id the gateway rejects**, which
+  surfaced as "The provider rejected this request" on manual selection.
+- **Session titles were rewritten, and could be destroyed.** `titleIndicator`
+  defaulted to true and compact mode returned the prefix alone, losing the name
+  irrecoverably. It now defaults to false and never derives a name from its own
+  previous output.
+- **Every provider was enabled by default** regardless of whether the machine had
+  an account, so a new install produced authentication failures for providers the
+  user never claimed. Enablement now follows discovered credentials, and an
+  explicit configuration always wins.
+- **A spent allowance was not recognised.** There was no `quota_exhausted` failure
+  class, so a 402 was retried and never marked the provider spent. It now stops
+  the turn and holds the provider back until its window resets.
+- **`DEPLOYMENT.json` could not be trusted.** It recorded the commit but not that
+  the tree was dirty, so three installs were attributed to the wrong revision. It
+  now records the diff hash, the changed file count and the GUI bundle hash.
+
+### Changed
+
+- **`ui.titleIndicator` now defaults to `false`.** The router no longer edits chat
+  names. Anyone who wants the indicator back can set it, and turning it off again
+  restores any prefix a previous version added.
+- **Provider enablement is credential-aware.** A provider the user never mentioned
+  is enabled only when a credential or connection exists for it.
+- Prices, ceilings and multipliers are now checked against vendor documentation by
+  tests, so they cannot drift silently.
+
+### Known limitations
+
+- OpenDesign has no usage API for an inference key, and the account-control
+  endpoints require a credential the product does not issue. `nexu-io/open-design`
+  issue #8674 requests one and remains open. The estimate plus a pasted reading is
+  the best available figure.
+- The GUI plugin API is marked experimental by the SDK and may change between
+  OpenCode releases.
+
+## 0.2.0 — prior to this changelog
+
+Subscription-aware routing across OpenCode Go, Command Code GOAT and OpenDesign,
+with nested usage windows, multi-pool credit accounting and context policy. See
+`docs/ARCHITECTURE.md`.

package/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing
+
+This project is small and deliberately narrow in scope, so a precise bug report
+is usually more useful than a large patch.
+
+## Before you start
+
+Open an issue describing what you want to change and why. For anything touching
+credential handling, routing eligibility, or quota arithmetic, please discuss it
+first. Those areas carry security and correctness properties that are easy to
+break from the outside, and a short conversation saves a rejected pull request.
+
+## Ground rules
+
+**Every change ships with a test.** `npm test` must pass. If behavior is hard to
+test, treat that as a design signal.
+
+**Never commit a credential, a token, an account identifier, or a personal file
+path.** Every path in the codebase derives from `homedir()`. Keep it that way.
+`safeError()` and `redact()` exist for this reason.
+
+**Do not weaken a safety property to make a test pass.** When a test fails, the
+test may be wrong (it has happened) or the code may be wrong. Work out which
+before editing either.
+
+**Provider facts need a source.** Allowances, multipliers, context windows, and
+prices are claims about the world. Cite where a number came from, with a
+retrieval date, in a comment. An unsourced number that looks authoritative is
+worse than an admitted gap.
+
+## Development
+
+```bash
+npm install
+npm run typecheck        # tsc --noEmit
+npm test                 # vitest run
+npm run check            # both
+npm run build:server     # the plugin bundle
+npm run build:allowance  # the standalone allowance core
+```
+
+Node 20.12 or newer.
+
+## Architecture boundaries
+
+Two rules keep this maintainable and publishable.
+
+**The allowance core stays portable.** `src/allowance.ts` is the public,
+host-independent surface. It may import only `core/plans/catalog`,
+`core/context/strategy`, `core/quota/report`, and `core/types`. It must never
+touch the filesystem, the network, the environment, or the host's plugin API.
+`test/allowance-api.test.ts` enforces this. If that test fails, the change is
+wrong, not the test.
+
+**Plans are data, not code.** A subscription tier is a `PlanDefinition` in
+`src/core/plans/catalog.ts`. Do not add `if (plan === "pro")` to a routing or
+quota module. If a new tier needs different behavior instead of different
+numbers, that is an architecture discussion.
+
+Provider HTTP handling belongs in `src/core/quota/*-provider.ts`. Routing policy
+belongs in `src/core/routing/` and `src/core/policy/`.
+
+## Adding a provider
+
+A provider adapter documents four things before it is accepted:
+
+- which credential it needs, and whether that credential can read usage;
+- every host it contacts, and whether each call is read-only;
+- how it reports confidence (`provider`, `estimate`, or `unknown`), and why;
+- what it does when the usage source is unavailable.
+
+A provider whose limits cannot be read must report `estimated` or `unknown`. It
+must never report an unknown allowance as unlimited.
+
+## Adding a plan
+
+Add a `PlanDefinition` with a source citation and a retrieval date. Add a test
+for the pool shape, the nesting invariants, and the absence of windows the plan
+does not have. A plan with no five-hour window must not report "0% of a five-hour
+limit," because that implies a ceiling nothing can hit.
+
+## Commit messages
+
+Explain why, not what. The diff already shows what. A commit that fixes a subtle
+bug should say how the bug showed up, because that part is not recoverable from
+the code.
+
+## Out of scope
+
+Likely to be declined:
+
+- spending money on your behalf;
+- acquiring credentials or control keys automatically;
+- disabling provider-side prompt caching;
+- silently truncating or discarding conversation history;
+- telemetry or analytics.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moe Qadan
+
+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,342 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+<img alt="smart router" src="assets/logo.svg" width="300">
+
+<h3>A model router for OpenCode that bills against your subscription, not a price list</h3>
+
+<p>Every other router asks what a token costs. This one asks what your plan allows, what is about to expire, and what you already paid for. MIT licensed.</p>
+
+<p>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/OpenCode-2.x-000000.svg" alt="OpenCode 2.x">
+  <img src="https://img.shields.io/badge/tests-759%20passing-2ea44f.svg" alt="759 tests">
+  <img src="https://img.shields.io/badge/runtime-Node%2020.12%2B-339933.svg" alt="Node 20.12+">
+</p>
+
+<p>
+  <a href="#install"><b>Install</b></a> &nbsp;·&nbsp;
+  <a href="#how-it-decides">How it decides</a> &nbsp;·&nbsp;
+  <a href="#commands">Commands</a> &nbsp;·&nbsp;
+  <a href="docs/ARCHITECTURE.md">Architecture</a> &nbsp;·&nbsp;
+  <a href="docs/LIMITATIONS.md">Limitations</a>
+</p>
+
+<br>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg">
+  <img alt="Your prompt goes to the smart router, which classifies and prices it against your real quota before OpenCode sends the step to one provider" src="assets/architecture-light.svg" width="880">
+</picture>
+
+<br>
+
+<p>
+  <a href="assets/screenshots/router-panel.png"><img alt="The router panel beside a live OpenCode session: the model it chose and why, the allowance windows it is spending against, and every provider it can route to" src="assets/screenshots/router-panel.png" width="720"></a>
+</p>
+
+<table>
+  <tr>
+    <td align="center" width="50%">
+      <a href="assets/screenshots/router-decision.png"><img alt="The decision inspector: the winning model with its estimated cost, and the runner-ups it beat" src="assets/screenshots/router-decision.png" width="376"></a>
+      <br><sub>The choice, laid out with its runner-ups</sub>
+    </td>
+    <td align="center" width="50%">
+      <a href="assets/screenshots/router-allowances.png"><img alt="Allowance meters for each provider: five-hour, seven-day and monthly windows, the credit pools behind them, and an honest lower-bound marker where the figure is an estimate" src="assets/screenshots/router-allowances.png" width="376"></a>
+      <br><sub>What is left, per window and per pool</sub>
+    </td>
+  </tr>
+</table>
+
+<p>
+  <a href="assets/screenshots/router-onboarding.png"><img alt="First-run onboarding: what the router found on this machine, what it learned from your history, and the one thing it cannot see, with the exact page to paste" src="assets/screenshots/router-onboarding.png" width="720"></a>
+</p>
+
+</div>
+
+---
+
+If you pay for a coding plan, you are not buying tokens. You are buying a set of
+windows that expire. A five-hour window sits inside a seven-day window inside a
+monthly ceiling, some windows are metered per model and do not pool, and a few
+plans run two credit pools that draw at different rates.
+
+Token-based routers cannot see any of that. They price every request the same way
+and happily spend the last dollar of an allowance that was about to reset anyway.
+This router models the plan you actually bought.
+
+## The problem, concretely
+
+You have three subscriptions. One has 90% of its five-hour window free but resets
+in forty minutes. Another has a huge untouched monthly pool. A third is nearly
+exhausted and expires tonight.
+
+A price-per-token router picks the same model every time. Whichever is cheapest on
+paper. It ignores that the first allowance is about to evaporate, that the second
+is your real safety margin, and that the third will be wasted if nobody spends it.
+
+The smart router ranks by what a request actually costs *you*: the modelled
+allowance it consumes, adjusted for how much of that allowance would otherwise be
+lost. When a pool is about to expire and mostly unspent, spending it is close to
+free. When a pool is nearly gone, it stops being attractive.
+
+<p align="center">
+  <img alt="Comparison: a fixed price-per-token router keeps choosing the same model, while the smart router shifts its choice as allowances fill and expire" src="assets/demo.svg" width="760">
+</p>
+
+## Install
+
+Requires Node 20.12+, npm and git. No `jq`, no global CLI, nothing to configure.
+
+### From npm
+
+Add the plugin to your `opencode.json`; OpenCode installs it from npm at startup:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@qadanm/opencode-smart-router"]
+}
+```
+
+That is the routing core in one self-contained file. The full experience (desktop
+panel, terminal commands, history import, first-run onboarding) comes from the
+installer below.
+
+### Full experience (recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/qadanm/opencode-smart-router/main/install | bash
+```
+
+Or from a clone:
+
+```bash
+git clone https://github.com/qadanm/opencode-smart-router.git
+cd opencode-smart-router && ./install
+```
+
+It validates the source, runs the full suite, backs up your config, builds, installs,
+and confirms the bundle loads. Every check runs before anything is written, so a
+failed install leaves your machine exactly as it was.
+
+Non-interactive, for CI or an agent:
+
+```bash
+./install --yes
+```
+
+See what it would do without touching anything:
+
+```bash
+./install --dry-run
+```
+
+Restart OpenCode, then run `/router-status` in any session.
+
+Already using it? Run `./install` again to update. Installs are versioned, so a
+running session keeps the module it loaded and picks up the new one on next start.
+
+**[Full install, verify and rollback guide →](docs/INSTALL.md)**
+
+## How it decides
+
+<p align="center">
+  <img alt="Pipeline: classify the task, evaluate each approved model for eligibility, price it against quota, then pick the lowest effective cost with a cache-affinity margin" src="assets/pipeline-light.svg" width="820">
+</p>
+
+Every prompt is classified locally, in about a millisecond, from its structure
+rather than its wording. The router reads scope, attachments, agent type, context
+size and recent failures, then holds substantive engineering work to an
+intelligence floor and requires native image input for anything visual.
+
+Then it does the part that matters:
+
+1. **Eligibility first.** A model is discarded if a plan cannot fund it, if a
+   provider allowance is exhausted, if the task needs vision the model lacks, or
+   if the intelligence floor excludes it. Refusals are recorded with the reason.
+2. **Price against the plan.** Cost is the modelled allowance a request consumes
+   in the windows that will actually be charged, not a per-token rate.
+3. **Discount what is expiring.** Prepaid allowance about to reset is priced near
+   its probability of being wasted. It is a bounded discount, never free, because
+   a pool with no headroom cannot carry the work.
+4. **Prefer staying put.** Switching discards a warm prompt cache, which costs real
+   money. The router only moves when the saving clears a margin.
+
+When a genuinely near-expiry window and a cheap provider disagree, the router picks
+the option that spends money you have already committed to losing.
+
+## Self-healing routing
+
+Some providers reject a rebuilt session outright. OpenCode turns mid-session
+notices into system-role messages, and the Anthropic protocol only accepts user
+and assistant roles, so one notice kills the whole turn with a 400 error.
+
+The router handles this before it can happen. For Anthropic-protocol models it
+folds system entries after the first message into user messages on the way out,
+so the request leaves in a shape the provider accepts. Utility requests, like
+title generation, are left alone.
+
+When a provider still says no, a 400 that would reproduce on every retry gets
+its own failure class and the host's retry is refused. The router holds the
+rejecting model back for five minutes, re-routes the same task to the next best
+eligible choice, and continues the turn with a single `[router]` notice. One
+failover per prompt, never a loop. The hold covers every session, because a
+gateway that rejects one rebuilt session will reject others like it. The
+panel's last decision records what was rejected and what took over.
+
+## What it will not do
+
+- Never buys credits, changes billing, or enables top-ups.
+- Never routes to a provider you did not approve.
+- Never spends premium quota without an explicit one-shot approval or a budget you set.
+- Never switches a session to a model OpenCode cannot currently resolve.
+- Never fails open on missing quota data when other providers already reported.
+- Never blocks your other work when one provider is at its limit.
+
+## Status
+
+Version 0.4.0. Routing runs on the maintainer's machine in automatic mode;
+premium escalation and purchased-credit spending are disabled. Current behavior
+and open questions are in
+[docs/PRO-MIGRATION-2026-10-29.md](docs/PRO-MIGRATION-2026-10-29.md).
+
+Published on npm as `@qadanm/opencode-smart-router`. The unscoped name
+`opencode-smart-router` belongs to an unrelated GPL project, so this package
+lives under a scope.
+
+## Commands
+
+Everything is a native slash command. No GUI needed, and routing works with the
+command panel closed.
+
+| Command | Purpose |
+|---|---|
+| `/router-status` | Runtime mode, selected model, task tier, quota, warnings |
+| `/router-explain` | Last decision, signals, candidate costs, reasons |
+| `/router-why` | Why this model, for the prompt you just sent |
+| `/router-report` | Local usage, switches, premium prevention, retries, latency |
+| `/router-floor` | The intelligence floor in force and what it admits |
+| `/router-mode efficiency\|balanced\|premium` | Change routing mode |
+| `/router-dry-run on\|off` | Explain decisions without changing the model |
+| `/router-auto` | Clear a manual override, resume automatic routing |
+| `/router-pin provider/model` | Pin a model for this session |
+| `/router-exclude provider/model` | Exclude a model from automatic routing |
+| `/router-approve` | Approve one premium request for this session |
+| `/router-pause` / `/router-resume` | Pause or resume routing globally |
+| `/router-premium-budget <usd>` | Set the premium budget |
+| `/router-reserve provider monthly weekly fiveHour` | Adjust provider reserves |
+| `/router-reset-metrics --confirm` | Reset metrics and routing state, not conversations |
+
+Selecting a model in the desktop picker is detected and respected. The session
+reports `manual` until you run `/router-auto`.
+
+## Configuration
+
+The defaults are safe and need no file. To change them:
+
+```bash
+cp config.example.json ~/.config/opencode/smart-router.json
+chmod 600 ~/.config/opencode/smart-router.json
+```
+
+A project may add `.opencode/smart-router.json`. A project file can tighten policy.
+It cannot loosen global restrictions.
+
+Worth knowing:
+
+- Mode: `balanced`
+- Premium: `ask`, $0 budget, one-shot approval available
+- Training-enabled and free promotional models: blocked
+- Purchased extra credits: blocked
+- Prompt text storage: disabled
+- Quota polling: every 5 minutes, with backoff
+- Provider reserves: 10% monthly, 15% weekly, 10% five-hour
+
+### Credential discovery
+
+Credentials are read from explicit paths, never guessed from arbitrary files.
+Nothing is logged. `safeError()` and `redact()` exist so a failure message cannot
+leak a key. The full model is in [docs/INSTALL.md](docs/INSTALL.md#credentials).
+
+## The portable core
+
+`dist/allowance.js` is a standalone module with no host dependency. You can use it
+without OpenCode, to answer "when does this plan run out":
+
+```js
+import { projectExhaustion } from "./dist/allowance.js"
+
+projectExhaustion({
+  usedUsd: 12.4,
+  capUsd: 30,
+  windowMs: 7 * 24 * 60 * 60 * 1000,
+  elapsedMs: 3.1 * 24 * 60 * 60 * 1000,
+  label: "weekly",
+})
+// { willExhaust: true, exhaustsAt, explanation: "...runs out about 6.2 hours from now." }
+```
+
+It reads no files, opens no socket, inspects no environment variable, and imports
+nothing from the host. A test enforces that, so it cannot drift.
+
+## Tests
+
+```bash
+npm test          # the suite
+npm run verify    # clean room: empty HOME, fresh install, typecheck, tests, builds
+npm run mutate    # prove each safety test fails when its property breaks
+```
+
+759 tests across 63 files cover classification, eligibility, quota parsing,
+credential discovery and its security properties, ledger accounting, pool
+reconciliation, documented peak pricing, cache-aware routing, premium protection,
+purchased-credit blocking, manual overrides, failure classification, configuration
+guardrails, context policy, quota honesty, the portable allowance API, and
+controller integration.
+
+Two commands exist because passing tests prove less than they appear to. `verify`
+repeats everything in a clean room with an empty `HOME`, so a pass cannot depend on
+this machine. `mutate` reverts each of 62 safety properties in turn and fails if the
+suite still passes, which is the only way to know a test is guarding anything.
+
+Live evidence is in [docs/QA.md](docs/QA.md).
+
+## Design notes
+
+A few decisions that are easy to get wrong, and why they are the way they are:
+
+- **Offline enforcement is an allow-list of one provider**, not a deny-list of
+  known hosted ones. A deny-list fails open the moment someone adds a provider.
+- **A saturated gateway is not a broken model.** Capacity refusals hold the
+  endpoint back without charging the failure to the single model behind it.
+- **Quota that expires unused is a sunk cost**, so the router prices it near its
+  probability of being wasted instead of at sticker price.
+- **A refusal outlives the reading that produced it.** An exhausted allowance stays
+  excluded until a fresh probe clears it.
+
+More in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome. Before opening a PR:
+
+```bash
+npm run check     # typecheck + full suite
+npm run verify    # the same, in a clean room with an empty HOME
+npm run mutate    # prove the safety tests still catch their properties
+```
+
+A change that alters routing behavior needs a test that fails without it. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for conventions, and [SECURITY.md](SECURITY.md)
+for reporting a vulnerability.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Copyright (c) 2026 Moe Qadan.
+
+Use it, modify it, ship it, sell it. Keep the copyright notice and permission text
+with any substantial copy, and understand that it comes with no warranty. The
+routing decisions it makes are estimates from modelled quota data, not guarantees
+from your providers.