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

package/docs/QA.md

@@ -0,0 +1,142 @@
+# QA evidence
+
+> **Current state (2026-10-29):** `npx vitest run` reports **330 tests passing**
+> across 26 files, and `npx tsc --noEmit` is clean. The router now models three
+> subscription providers with separate credit pools. Everything below predates
+> that migration and is kept as a historical record of how each defect was
+> found and fixed; wherever a figure here disagrees with the current code, the
+> code is authoritative. See
+> [PRO-MIGRATION-2026-10-29.md](PRO-MIGRATION-2026-10-29.md) for the current
+> behavior.
+
+> **Accounting follow-up (2026-10-28):** artifact `8c71c46c5f7616f950c6a3fcf5c42be2198407848cf9ffac15d01504496f8920` / commit `e8fa5ac`; **106 tests at the time**. The Command Code monthly cap figures in the historical evidence below (for example `capUsd: 70.38`) came from the usage summary and are superseded. The authoritative plan grant is **$70**, derived from the provider's `$14` five-hour and `$35` weekly caps; monthly usage is now `$70 − remaining`. See [ACCOUNTING-INVESTIGATION-2026-10-28.md](ACCOUNTING-INVESTIGATION-2026-10-28.md). See [DESKTOP-PROMOTION-2026-10-28.md](DESKTOP-PROMOTION-2026-10-28.md) and the pre-promotion [DESKTOP-DRY-RUN-2026-10-28.md](DESKTOP-DRY-RUN-2026-10-28.md). Statements below about an earlier global installation are historical.
+>
+> **Post-audit update:** the Option C repair is implemented on branch `option-c`. The current verification record is [QA-OPTION-C-2026-10-27.md](QA-OPTION-C-2026-10-27.md). The pre-audit results below are retained for history.
+
+All checks below were run on this machine against the installed desktop server, not only against isolated functions. **The live plugin was disabled after the stability incident documented in [STATUS-2026-10-27.md](STATUS-2026-10-27.md). The live routing results below were captured before that rollback.**
+
+## Automated checks
+
+```text
+npm run typecheck  → exit 0
+npm test           → 7 files, 69 tests passed
+```
+
+Coverage includes:
+
+- task classification, including narrow CSS, broad scope, screenshots, redesign, architecture, security, stack traces, and self-described simplicity;
+- intelligence-floor enforcement and unclassified-model exclusion;
+- premium protection, one-shot approval, and premium locking in Maximum Efficiency;
+- vision hard requirements and text-only exclusion;
+- provider-reported Go and Command Code quota parsing, including reset times and extra credits;
+- credential discovery, owner-only permission checks, and unauthorized-key fallback;
+- rolling five-hour, weekly, monthly, and per-model ledger accounting;
+- cache-loss pricing and large-context affinity;
+- manual override, pause, dry-run, and disabled-routing behavior;
+- failure classification for context overflow, network, rate limits, auth, provider outage, tool errors, and capability failures;
+- subagent premium caps;
+- configuration guardrails that prevent project files from loosening privacy or spending policy;
+- controller integration that invokes the actual prompt hook and verifies the switch occurs before the request.
+
+## Live provider-reported quota
+
+Captured from the installed desktop plugin after provider probes. Values are redacted and rounded.
+
+### OpenCode Go
+
+```json
+{
+  "providerID": "opencode-go",
+  "label": "OpenCode Go Plus",
+  "source": "provider",
+  "rolling": { "usedPct": 0, "resetsAt": "2026-10-27T21:53:04.000Z" },
+  "weekly": { "usedPct": 40, "resetsAt": "2026-11-02T00:00:00.000Z" },
+  "monthly": { "usedPct": 70, "resetsAt": "2026-11-20T11:37:14.000Z" }
+}
+```
+
+### Command Code
+
+```json
+{
+  "providerID": "commandcode",
+  "label": "Command Code GOAT",
+  "source": "provider",
+  "plan": "GOAT",
+  "planStatus": "active",
+  "rolling": { "usedPct": 0.33, "usedUsd": 0.0322, "capUsd": 14, "resetsAt": 1793156518583 },
+  "weekly": { "usedPct": 72.30, "usedUsd": 25.29, "capUsd": 35, "resetsAt": 1793428863795 },
+  "monthly": { "usedPct": 36.53, "usedUsd": 25.67, "capUsd": 70.38, "resetsAt": 1795501544000 },
+  "monthlyRemainingUsd": 44.71,
+  "extraCredits": { "purchasedUsd": 0, "freeUsd": 0, "totalUsd": 0 }
+}
+```
+
+The Command Code monthly grant is the sum of remaining included credits and billing-period usage, both provider-reported. It is not assumed from the plan name. Purchased and free credits remain separate pools.
+
+The plugin uses the Command Code CLI-compatible key because the inference key is rejected by the alpha billing routes. No key, token, email, or account identifier is included here.
+
+## Live routing decisions
+
+Each test used a new desktop session with a deliberately weak starting model. The router changed the session before the request, and the response came from the changed model.
+
+| Prompt | Tier / kind | Selected route | Result |
+|---|---|---|---|
+| Narrow CSS change with explicit file and "do not run tests" | 1 / mechanical | `opencode-go/mimo-v2.6-flash` | File changed from `white` to `#111111`; tool calls survived the switch |
+| Ordinary "reply only" prompt | 2 / unknown | `opencode-go/claude-haiku-5-5` | Completed |
+| Redesign with a screenshot, no approval | 3 / design, vision required | `opencode-go/claude-haiku-5-5` standard fallback | Premium approval warning recorded |
+| Same redesign, one-shot approval | 3 / design, vision required | `commandcode/meta/muse-spark-1.3` premium | One-shot consumed; premium route used |
+| Manual switch to `commandcode/deepseek-v4.1-flash` | manual | Kept | `/router-status` reported `manual`; no override |
+| Cross-provider switch from `opencode-go/beam-free` | 2 | `commandcode/deepseek/deepseek-v4.1-flash` | Request ran on Command Code |
+
+A real completed tool task changed a CSS file correctly on the economy route. After the classifier was tightened, the same kind of task selected `opencode-go/mimo-v2.6-flash` (economy) and the file changed from `white` to `#111111`. This verifies that switching before admission preserves tool calls.
+
+A live pause test set the router to paused, sent a prompt with the starting model `opencode-go/beam-free`, and confirmed the session stayed on `beam-free` and completed normally. Routing was then resumed.
+
+## Cross-provider proof
+
+The prompt admission hook was tested with a server that logged the pre-switch model, the post-switch model, and the model observed by the request-context hook:
+
+```json
+{"at":"prompt.before","model":{"providerID":"opencode-go","id":"iceman-contributor-free"}}
+{"at":"prompt.after","model":{"providerID":"commandcode","id":"deepseek/deepseek-v4.1-flash"}}
+{"at":"context","model":{"providerID":"commandcode","id":"deepseek/deepseek-v4.1-flash"}}
+```
+
+This proves the switch happened before the intended request, not after it.
+
+## Installed desktop verification
+
+```text
+GET /api/plugin
+{
+  "id": "opencode-smart-router",
+  "source": { "type": "local", "path": "~/.config/opencode/plugins/opencode-smart-router/index.ts" },
+  "features": { "server": true },
+  "state": { "status": "active" }
+}
+```
+
+The native commands are present in the desktop server's command list, including `router-status`, `router-explain`, `router-report`, `router-approve`, `router-auto`, `router-pin`, and `router-mode`.
+
+## What is provider-reported vs estimated
+
+| Value | Source |
+|---|---|
+| Go rolling/weekly/monthly percentages and reset times | Provider-reported |
+| Command Code included credits remaining, extras, five-hour/weekly windows, resets, plan, billing period, spend | Provider-reported |
+| Command Code per-model usage and remaining model allowance | Local estimate from observed step costs |
+| Go per-model dollar usage | Local estimate; the provider reports percentages |
+| Expected task cost, success probability, retry cost | Local model using catalog prices and task signals |
+| Premium budget and spend | Local accounting |
+
+## Cleanup
+
+All test sessions created through the desktop API were deleted after verification. `/router-reset-metrics --confirm` was used to clear test metrics and re-bootstrap the remaining real sessions. No user conversation was deleted.
+
+## Not verified
+
+- GUI panel rendering: the installed desktop 2.1.4 has no GUI plugin SDK. See [LIMITATIONS.md](LIMITATIONS.md).
+- A full desktop application process restart was not forced because it would close the user's active windows. The plugin is installed in the global config, the server reports it active, and a clean standalone server loaded it from the same global entry, which is the restart path. The persistent ledger and runtime overrides are written through OpenCode's durable plugin storage; hydration is unit-tested.
+- A live 600K-context switch test on a forked session did not execute a prompt because the source session was busy. Large-context affinity is covered by the routing unit tests and by the cache-loss pricing tests. The live plugin now estimates a large context for forks and long-lived sessions before routing, then refines it in the background.
+- Provider-side billing enforcement cannot be proven from a client. The router fails conservatively and never claims a guaranteed cap.

package/docs/SHARED-CORE.md

@@ -0,0 +1,72 @@
+# Shared-core architecture
+
+## Verified SDK process model
+
+The installed OpenCode 2.1.4 server was probed in an isolated HOME with 20 project locations. A probe plugin recorded `process.pid`, a `globalThis` core id, and a per-location setup counter. Results:
+
+- 20 locations produced one PID and one `globalThis` core.
+- `setups` increased per location while `core` and `pid` stayed constant.
+- A second probe wrote a plugin-storage value in location 1 and read it in location 2. Location 2 read the value written by location 1, confirming OpenCode's plugin storage is process-global across locations.
+
+This is the basis for one shared core. The probe is reproducible in the lab and does not rely on an unverified assumption for this installed version.
+
+## Ownership
+
+| Layer | Owns | Instances |
+|---|---|---|
+| `SharedCore` | ledger, runtime overrides, quota cache, quota probes, session bootstrap, persistence timers, session ownership, diagnostics | exactly one per process |
+| `RouterController` bridge | project registry, project settings, prompt/retry/header hooks, commands, RPC registration, event stream, title queue | one per loaded project location |
+
+The shared core is stored under a process-global symbol. Each bridge calls `sharedCore.init`; the core loads storage once, creates one `QuotaService`, schedules one bootstrap, and schedules one quota initialization. Bridges never start their own timers or pollers.
+
+## Load path
+
+On plugin load the bridge:
+
+1. awaits only shared storage hydration (no network, no session enumeration);
+2. builds a seed registry immediately;
+3. registers commands, RPC, hooks, and the event stream;
+4. adds itself to the core;
+5. refreshes the live model catalog in the background.
+
+Session bootstrap is delayed one second; quota probing is delayed 1.5 seconds and runs once for the process. There is no provider request on the critical load path.
+
+## Lifecycle
+
+- `addBridge` registers a project and cancels any pending shutdown grace.
+- `removeBridge` removes it; when the last bridge closes, the core waits 10 seconds before persisting and shutting down.
+- The core object stays bound to the process after shutdown. A later setup revives it through `init` instead of creating a second core that would race on the same storage.
+- Bridge cleanup disposes only that bridge's commands, RPC, hooks, and event stream.
+- Shared state has bounded session ownership, ledger events, decisions, errors, and per-bridge session maps.
+
+## Project isolation
+
+Session and step events are process-global in this SDK. A session is claimed by the bridge that admitted its prompt. Event handlers ignore events for sessions owned by another bridge. `retry`, `model.request`, and model-selection handling are guarded the same way, so one project cannot suppress another project's retries, set its privacy headers, or mark it manual.
+
+The prompt hook checks `projectID` before claiming a session. Title writes are filtered by project. Commands and RPC remain location-scoped, so each project exposes its own 16 router commands.
+
+## Fail-closed policy
+
+`routing.failClosed` defaults to `true`. When no eligible route exists and the current model is unqualified, the router:
+
+1. writes a `BLOCKED` session title;
+2. sends a nonintrusive notification where supported;
+3. records a blocked decision with the reason;
+4. throws `RouterBlockedError` from the prompt hook.
+
+The installed server was probed with a throwing prompt hook: the prompt returned HTTP 500 and was not admitted; the session had no model and no request was sent. OpenCode does not expose a typed rejection API. The HTTP error is generic, so the title and notification are the user-facing explanation. This is a documented limitation, not a silent execution path. Manual selections and paused routing are outside the strict block.
+
+Every unexpected routing exception is now converted into a blocked decision, a `BLOCKED` title, and a `RouterBlockedError` before admission. A malformed model definition or an engine bug can no longer fall through to an unqualified model. The opt-out is explicit: `routing.failClosed: false`.
+
+## Quota and persistence
+
+- One `QuotaService` uses the first bridge's global integration credentials; quota snapshots are shared.
+- One ledger is shared by all projects. Provider-reported Go and Command Code observations remain distinct from local per-model estimates.
+- Persistence is debounced; a write takes a snapshot, marks clean, then re-schedules if a mutation arrived during the write.
+- No extra credits, billing changes, or unapproved provider routes are introduced.
+
+## Limits
+
+- The first loaded location's settings provide the shared quota/bootstrap configuration. Per-project routing thresholds and model approvals still come from each bridge.
+- The core is process-wide only because the installed server is one process with shared `globalThis`. If a future host isolates locations in separate processes, the core must use an external coordinator or accept one core per process with process-scoped storage keys.
+- Prompt-hook rejection is a 500 at the HTTP boundary; it is safe but not a polished typed error.

package/install

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# OpenCode Smart Router — zero-to-working in one command.
+#
+# FOR A PERSON:
+#   curl -fsSL https://raw.githubusercontent.com/qadanm/opencode-smart-router/main/install | bash
+#   ...or, from a clone:  ./install
+#
+# FOR AN LLM / CI:
+#   The same command, plus --yes. It never prompts, prints one line per step, and exits
+#   non-zero with an actionable message on any failure. Every check happens before
+#   anything is modified, so a failure leaves the machine untouched.
+#
+# WHAT IT DOES:
+#   1. checks node/npm/git
+#   2. clones the repo to ~/.opencode-smart-router (or updates it)
+#   3. runs scripts/install.sh, which builds, installs, wires the config, and verifies
+#
+# Re-running is safe and is the update path: it pulls the latest and reinstalls.
+#
+set -euo pipefail
+
+REPO_URL="${SMART_ROUTER_REPO:-https://github.com/qadanm/opencode-smart-router.git}"
+TARGET="${SMART_ROUTER_DIR:-$HOME/.opencode-smart-router}"
+ASSUME_YES=false
+PASSTHRU=()
+
+for a in "$@"; do
+  case "$a" in
+    --yes|-y) ASSUME_YES=true; PASSTHRU+=("--yes") ;;
+    *) PASSTHRU+=("$a") ;;
+  esac
+done
+
+step() { printf '\n\033[1m==> %s\033[0m\n' "$*"; }
+die()  { printf '\033[31m  x %s\033[0m\n' "$*" >&2; exit 1; }
+
+step "OpenCode Smart Router — bootstrap"
+
+# Running from inside a checkout? Then that checkout IS the source. Cloning it
+# again would either duplicate it or, on a private repo, fail with a credential
+# prompt. `./install` is documented as the from-a-clone path, so it must work
+# without network access to the forge.
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd || true)"
+if [[ -n "${SELF_DIR:-}" && -f "$SELF_DIR/scripts/install.sh" && -d "$SELF_DIR/.git" ]]; then
+  step "Installing from this checkout"
+  echo "  source: $SELF_DIR"
+  exec "$SELF_DIR/scripts/install.sh" "${PASSTHRU[@]}"
+fi
+
+command -v git  >/dev/null || die "git is required. Install it first."
+command -v node >/dev/null || die "Node 20.12+ is required: https://nodejs.org"
+NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"
+NODE_MINOR="$(node -p 'process.versions.node.split(".")[1]')"
+(( NODE_MAJOR > 20 || (NODE_MAJOR == 20 && NODE_MINOR >= 12) )) \
+  || die "Node $(node -v) is too old; the router needs >= 20.12."
+command -v npm >/dev/null || die "npm is required (it ships with Node)."
+echo "  node $(node -v), git $(git --version | awk '{print $3}')"
+
+if [[ -d "$TARGET/.git" ]]; then
+  step "Updating existing clone at $TARGET"
+  git -C "$TARGET" fetch --quiet origin || die "could not reach $REPO_URL"
+  # Install from whatever branch the clone is on, so feature branches work too.
+  BRANCH="$(git -C "$TARGET" rev-parse --abbrev-ref HEAD)"
+  git -C "$TARGET" pull --ff-only --quiet origin "$BRANCH" \
+    || echo "  (local commits present — installing from the working tree as-is)"
+else
+  step "Cloning into $TARGET"
+  mkdir -p "$(dirname "$TARGET")"
+  git clone --quiet "$REPO_URL" "$TARGET" \
+    || die "clone failed. If the repo is private, set SMART_ROUTER_REPO to a URL you can reach."
+fi
+
+step "Running the installer"
+exec "$TARGET/scripts/install.sh" "${PASSTHRU[@]}"

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@qadanm/opencode-smart-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Subscription-aware model routing for OpenCode: nested usage windows, multi-pool credit accounting, context policy, and self-healing routing that repairs prompts and fails over deterministic rejections.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "router",
+    "llm",
+    "quota",
+    "ai",
+    "coding-agent",
+    "anthropic",
+    "model-routing"
+  ],
+  "homepage": "https://github.com/qadanm/opencode-smart-router#readme",
+  "bugs": {
+    "url": "https://github.com/qadanm/opencode-smart-router/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qadanm/opencode-smart-router.git"
+  },
+  "author": "Moe Qadan",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12"
+  },
+  "exports": {
+    ".": "./dist/npm/index.js",
+    "./source": "./src/index.ts",
+    "./rpc": "./src/rpc.ts",
+    "./allowance": "./src/allowance.ts",
+    "./tui": "./dist/tui.js",
+    "./gui-experimental": "./dist/gui-experimental.cjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts/install.sh",
+    "scripts/uninstall.sh",
+    "install",
+    "config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "docs/ARCHITECTURE.md",
+    "docs/INSTALL.md",
+    "docs/LIMITATIONS.md",
+    "docs/MODELS.md",
+    "docs/OPENDESIGN-INTEGRATION.md",
+    "docs/SHARED-CORE.md",
+    "docs/QA.md",
+    "docs/DEBUGGING-GUI.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run typecheck && npm run test",
+    "build:server": "esbuild src/index.ts --bundle --format=esm --platform=node --target=node22 --external:@opencode/plugin --external:@opencode/plugin/* --outfile=dist/index.js --legal-comments=none",
+    "build:allowance": "esbuild src/allowance.ts --bundle --format=esm --platform=neutral --target=node20 --outfile=dist/allowance.js --legal-comments=none",
+    "build:gui": "vite build --config vite.gui.config.ts",
+    "build:tui": "esbuild src/tui/index.tsx --bundle --format=esm --platform=node --target=node22 --external:@opencode/plugin --external:@opencode/plugin/* --external:@opentui/core --external:@opentui/solid --external:solid-js --outfile=dist/tui.js --legal-comments=none",
+    "build:all": "npm run build:server && npm run build:allowance && npm run build:gui && npm run build:tui",
+    "mutate": "python3 scripts/mutate.py",
+    "verify": "bash scripts/cleanroom-verify.sh",
+    "prepublishOnly": "npm run check && npm run build:npm",
+    "build:npm": "esbuild src/index.ts --bundle --format=esm --platform=node --target=node22 --packages=bundle --outfile=dist/npm/index.js --legal-comments=none --minify"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.2.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "solid-js": "^1.9.18",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.7",
+    "vite-plugin-solid": "^2.11.15",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/plugin": {
+      "optional": true
+    }
+  }
+}