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

package/CHANGELOG.md

@@ -0,0 +1,286 @@
+# 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.6.1 — 2026-11-06
+
+A defect in the router can no longer stop the editor.
+
+Version 0.6.0 could refuse every prompt, in every mode, until the plugin was
+removed by hand. Two defects compounded to cause it. This release fixes both,
+and adds the missing test layer that would have caught them. The full account is
+in [docs/INCIDENT-2026-11-06-prompt-lockout.md](docs/INCIDENT-2026-11-06-prompt-lockout.md).
+
+### Fixed
+
+- **An inherited shared core is no longer adopted.** The process-wide core in
+  `globalThis` is stamped with `SHARED_CORE_API`; a core from a different
+  version is replaced rather than reused. A new bundle could previously inherit
+  a core built by an older release, whose ledger had no `planPoolSpent()`, and
+  every prompt then threw. `init()` also repairs a ledger that is not a
+  `LedgerStore` instance.
+- **`routing.failClosed` defaults to `false`.** Blocking is now opt-in and means
+  one thing: what to do when this plugin cannot produce a decision. The old
+  default escalated an internal `TypeError` into a refusal to serve the prompt,
+  including in manual mode. An internal defect now degrades to "do not route",
+  which is what would have happened with the plugin uninstalled.
+- **Quota safety is a separate, unconditional gate.** A provider configured for
+  probing but with no reading is still refused, regardless of `failClosed`,
+  because that is a spending decision rather than a response to plugin failure.
+- **A failed setup installs no prompt hook.** The entry point used to leave a
+  "minimal fail-closed hook" behind when `initialize()` threw, turning a failed
+  setup into an editor that refused every message. A location whose setup failed
+  now has no router.
+- **Hooks cannot throw or hang at the host boundary.** OpenCode does not catch a
+  plugin hook that throws and does not time out one that never settles; both
+  were verified against a real OpenCode 2.2.5 process. Every hook is wrapped in
+  `containHook()`, and routing runs against a 10 second deadline
+  (`withDeadline()`), after which the prompt proceeds unrouted.
+- **Routing only considers models the host can serve.** The router offered the
+  whole seed catalog as candidates. On a fresh install it switched a session to
+  `opencode-go/claude-haiku-5-5`, which that machine did not have, and the next
+  step failed with "Model unavailable". Candidates are now filtered to the
+  host's own model list, and an empty result means no route rather than an
+  unfiltered fallback.
+- **Model discovery is awaited on the first routing decision.** Discovery starts
+  in the background, so the first prompt after startup could route against an
+  empty list, which is the window in which an unservable model was reachable.
+
+### Added
+
+- `scripts/isolated-e2e.sh`: runs a real OpenCode in a temporary HOME with its
+  own config, data, and cache, installs a deliberately broken plugin, and
+  asserts only that OpenCode still answers a prompt. It refuses to run if any
+  path escapes the sandbox. Seven scenarios pass; two are recorded as host
+  limitations because they demonstrate that OpenCode has no defense at that
+  boundary. It runs against a loopback model stub that it starts itself, so it
+  needs no credentials and cannot be blocked by provider quota. A CI job runs
+  it on every push.
+- Regression suites: `test/shared-core-skew.test.ts` and
+  `test/shared-core-adoption.test.ts` (a stale core must not be adopted or break
+  routing), `test/fail-open-contract.test.ts` (an internal defect must not block
+  a prompt), `test/containment.test.ts` (hooks cannot throw or hang),
+  `test/setup-failure-never-blocks.test.ts` (a failed setup leaves no router),
+  `test/routing-servable-models.test.ts` (only servable models are candidates).
+- Six new entries in the mutation harness, one per corrected property.
+
+### Changed
+
+- `config.example.json` ships `failClosed: false`. Copying the example used to
+  inherit the old blocking default.
+- `scripts/cleanroom-verify.sh` now overlays the working tree onto `HEAD` and
+  reports how many uncommitted paths it covered. Before this, a run with work in
+  progress verified the previous commit and reported a pass that said nothing
+  about the changes being made.
+
+### Fixed in CI
+
+- The `host-survival` job now installs OpenCode V2 from its release binaries
+  instead of Homebrew, which does not exist on Ubuntu runners, and verifies the
+  download against the published `SHA256SUMS`. It also asserts the major version
+  is 2, so a future change to the installer cannot quietly point the suite at
+  OpenCode 1, whose hook surface and CLI differ.
+- `test/history.test.ts` no longer fails on the declared Node 20.12 floor, where
+  `node:sqlite` does not exist. The reader already degraded gracefully there; the
+  test now asserts that degradation and skips only the two cases that genuinely
+  require a real database. The suite passes on 20.12 with two honest skips rather
+  than two failures.
+- The eight calibration properties the mutation harness listed as unguarded now
+  have `test/calibration-policy.test.ts`. They were not missing guards, they were
+  pointed at a file that covers a different module, so the properties were never
+  exercised. All 69 mutations are now caught.
+
+## 0.6.0 — 2026-11-06
+
+Tier-3 work escalates by itself, paid from the plan-model pool.
+
+### Added
+
+- **Automatic flagship escalation** (`premium.mode: "auto"`, now the default):
+  a tier-3 task routes to the plan-model pool (Claude Sonnet 5.5, GPT-6.1 Sol)
+  without a per-task approval prompt while the pool has budget. When the pool
+  is spent, escalation degrades to an approval gate and the router serves the
+  task with the strongest ordinary model - a routing refusal never fails a
+  serviceable task. Tier-1 and tier-2 work always stays on the ordinary pool.
+- **Plan-model pool ledger**: monthly buckets tracking spend against the
+  OpenDesign plan-model allowance (Pro: $120/month), persisted across
+  restarts, separate from Design Plan credits and from other providers'
+  premium spend. The cap is read from the resolved plan catalog.
+- **Per-kind capability evidence**: `ModelRecord.capabilities` (coding,
+  debugging, agentic, architecture) from named benchmarks with provenance,
+  moving expected success by at most 4 points - enough to break a close
+  ranking, never enough to overrule a gate. Unscored models stay neutral:
+  absent evidence is unknown, not zero.
+- **Context probes** (`scripts/probe-plan-model-context.py`): end-to-end
+  800K-token verification with memorization sentinels and truncation checks.
+
+### Changed
+
+- GPT-6.1 Sol is scored (intelligence 55, Artificial Analysis v5.0.1) and
+  auto-approved for tier-3 escalation along with Sonnet 5.5, both by owner
+  instruction 2026-11-06. DeepSeek's observed 39.5 is untouched.
+- Catalog context windows raised from measured (328K/400K) to probed-verified
+  800K for both flagships after passed end-to-end probes on 2026-11-06; the
+  advertised 1M is deliberately NOT claimed, and Sol's long-context surcharge
+  above 272K was confirmed by the billed amounts.
+- MiniMax M3.1 Flash is classified as a Design Plan model. The gateway serves
+  it both inside and outside the Design Plan group and OpenDesign has not
+  published which applies, so the conservative choice is made: treating an
+  ordinary tier-2 workhorse as a plan model keeps routine work from draining
+  the escalation pool. Before this, a tier-3 task could land on it as a
+  premium model that a tier-2 flag itself made eligible.
+
+### Fixed
+
+- A partial settings file no longer produces a warning for every key it leaves
+  out. Absent and invalid are now distinct: a key you did not write takes its
+  default silently, while a key you did write with the wrong type still reports
+  the problem. Before this, a config that only set `providers.opendesign.plan`
+  emitted around fifty warnings and hid the ones that mattered.
+
+## 0.5.0 — 2026-11-06
+
+The router stops taking things that are not its to take.
+
+### Changed
+
+- **The router no longer renames sessions.** The `AUTO · OD · model — name`
+  title prefix is gone, for new chats and for every chat going forward. A chat
+  title is the owner's name for the work; status belongs in the panel, the
+  terminal footer and the decision record. The `ui.titleIndicator` setting is
+  removed and ignored if present.
+- `/router-title off` now strips prefixes this plugin wrote in earlier versions
+  and reports how many titles it cleaned. Titles that lost their separator are
+  left alone rather than rewritten.
+- Existing installs were repaired in place: every prefixed title was restored
+  from its separator, or from the session's own first user message when the
+  separator was already gone.
+
+### Added
+
+- Earlier review pass carried in this release: self-heal floor fallback, real
+  safety-margin enforcement, task-scoped rejection memory, strict failure joins,
+  request-clock threading, and metric-neutral decision notes.
+
+### Removed
+
+- **Sidebar project grouping (never released on npm).** The desktop app ships
+  this natively behind Settings -> Experimental -> Organize vertical sidebar ->
+  Projects (upstream commit `2bb4988`, after the installed v2.2.5). A plugin
+  copy would duplicate app code and fight the native version. The reasoning and
+  the prior-art notes are in `docs/SIDEBAR-GROUPING-TABLED.md`.
+
+## 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,103 @@
+# 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.
+
+## Releasing
+
+See [README → Releases](README.md#releases). Publishing happens in CI through npm
+trusted publishing, so a maintainer never handles a long-lived token or relays a
+one-time password. Never publish from a working copy: the workflow checks the tag
+against `package.json` and re-runs the full suite first.
+
+## 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.