@route_33/opencode 0.4.6 → 0.4.7-rc.2

package/README.md

@@ -1,119 +1,95 @@
 # @route_33/opencode
 
-An opencode provider plugin for the [route33.ai](https://route33.ai) AI gateway: model discovery, cost/limit metadata, and a key-setup wizard in the TUI.
+The Route 33 plugin for OpenCode: sign in with your browser, pick who pays for
+usage, and use the route_33 models — no API keys to paste, ever.
 
 ## Install
 
-```bash
-opencode plugin @route_33/opencode
+```sh
+opencode plugin add @route_33/opencode
 ```
 
-The installer patches both configs: the server plugin into `opencode.json` and the key-setup wizard (TUI plugin) into `tui.json`. To install manually instead, declare both entries yourself:
+Restart OpenCode afterwards — plugins load at startup.
 
-```jsonc
-// opencode.json — server plugin (model discovery, cost/limit enrichment, auth)
-{
-  "plugin": ["@route_33/opencode"]
-}
-```
+Prefer config? Add the package to `opencode.jsonc` instead:
 
 ```jsonc
-// tui.json — TUI plugin (the key-setup wizard)
-{
-  "plugin": ["@route_33/opencode"]
-}
-```
-
-This plugin never writes your `opencode.json` or `opencode.jsonc`: opencode has no TUI-plugin auto-discovery, so without a `tui.json` entry the wizard simply never appears — the server plugin works regardless. The only files the plugin ever writes inside your repo are an optional `.opencode/route33.key` (git-ignored automatically) and your own `.opencode/route33-overrides.json` (yours to commit or ignore).
-
-## Auth
-
-Run `opencode auth login` and choose `route_33`, or set the `ROUTE33_API_KEY` environment variable. Without a key, the TUI wizard offers to save one: per-project inside a git workspace, global otherwise. A globally stored key applies only outside git workspaces — inside a workspace, keys resolve from the environment, the workspace config, or `.opencode/route33.key` (per-project keys are the metering boundary). Skipping the project-key wizard snoozes it for 7 days — "Skip" for that workspace only, "Skip for all workspaces" everywhere (both live in opencode's TUI kv store; remove `project-key-prompt.dismissed-at*` from `~/.local/state/opencode/kv.json` to re-arm sooner). `ROUTE33_BASE_URL` overrides the default gateway URL; `ROUTE33_TUI_PROMPT=0` disables the wizard.
-
-Your key is never written into the resolved provider configuration: authentication is attached per request at fetch time, so `opencode debug config` output contains no credential material. One inert exception: the options carry the non-secret marker `__route33_fetch_shim_auth__` as `apiKey`, because the native per-model SDKs used for `anthropic/`, `openai/`, and `mistralai/` models (`@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/mistral`) refuse to construct a request without one — the marker satisfies that null check, never authenticates anything (the gateway reads only the request-time `Authorization` header, which the fetch shim injects), and no vendor env var (`ANTHROPIC_API_KEY` etc.) is needed or consulted. The marker is skipped by key resolution and never overrides an `apiKey` you authored yourself; it is visible in config dumps precisely because it is not a secret.
-
-## Model catalog
-
-The catalog is discovered dynamically. The plugin calls `GET {baseURL}/models` with your resolved API key, caches the response on disk, and injects only the models that key can see. The refresh ladder is:
-
-1. Return the fresh on-disk cache if it has not expired.
-2. Fetch live from the gateway and update the cache.
-3. If the live fetch fails, return the stale cache.
-4. If there is no cache and no live response, preserve existing generated entries and inject no replacement models.
-
-The plugin does not embed or serve a static catalog. The on-disk cache is keyed by gateway URL **and** API key, so the same key pointed at a different gateway (`ROUTE33_BASE_URL`, e.g. a local cluster) never shares a cache with production. Catalog cache envelopes are versioned; cache files from older plugin versions are ignored after an upgrade and repopulated from the gateway.
-
-If discovery yields no catalog, the plugin logs exactly one warning:
-
-```
-route33: no model catalog available — 0 models injected (reason). route33 is unusable without a catalog: resolve an API key (opencode auth login / ROUTE33_API_KEY) — the key dictates which models are available.
+{ "plugins": ["@route_33/opencode"] }
 ```
 
-Set `ROUTE33_DISCOVERY=0` to opt out of discovery entirely. This is logged at `info` and injects zero models without the warning.
+## First run
 
-## Metadata provenance
+1. Pick any route_33 model (or run `/connect` and choose **Route 33**).
+2. Open the sign-in link — your browser finishes at a Route 33 confirmation
+   page.
+3. Connect again and pick **who pays for usage in this folder**: one of your
+   Route 33 projects, or your personal key.
+4. The route_33 models appear. Done.
 
-Models are decorated with metadata from the route33 gateway broadcast; `models.dev` is used only as a backfill source.
+To change who pays later, connect again and pick another option. `/r33` shows
+the current state at any time.
 
-- **Cost**: the gateway's broadcast pricing wins; `models.dev` fills in when the broadcast carries no pricing.
-- **Limits**: the gateway's broadcast `limits` win; `models.dev` fills in when the gateway broadcasts none. Limits are omitted entirely when neither source knows them; the plugin never fabricates them.
-- **Modalities**: gateway `modalities.input` / `modalities.output` are passed through to opencode. Invalid modality values and malformed modality objects are omitted per model.
-- **Attachment**: gateway `attachment` wins whenever present. `models.dev` supplies it only when the gateway omits the field.
-- **Capabilities**: the broadcast `reasoning` and `tool_support` flags win (`tool_support` is mapped to `tool_call`); `models.dev` always backfills any capability flag left undefined.
-- **Variants**: R33 broadcast variants are passed verbatim (for example, `kimi-k3`'s `max` `reasoningEffort` variant).
+## Commands
 
-The normative broadcast contract is [docs/gateway-limits-variants-broadcast.md](docs/gateway-limits-variants-broadcast.md).
+| Command       | Effect                                                    |
+| ------------- | --------------------------------------------------------- |
+| `/r33`        | Show who pays, the active key, and its rotation state     |
+| `/r33 rotate` | Rotate the key immediately                                |
+| `/r33 reset`  | Clear who pays — connect again to pick a different option |
 
-## Managed model entries
+A browser is required for every sign-in; restarts afterwards sign in silently.
 
-Gateway-discovered `provider.route_33.models` entries are fully managed: every startup rebuilds the map from the current broadcast, then deep-merges your overrides on top. The ownership rule is the whole design — *in the broadcast (or in your overrides) ⇒ kept; anything else ⇒ dropped and logged* — so retired gateway models disappear automatically and no bookkeeping file is needed. (Versions ≤0.4.3 kept a `.opencode/route33-generated.json` ledger for this; the plugin deletes that obsolete file on first run.)
+## Keys
 
-Keep customizations in `.opencode/route33-overrides.json`, because the installed OpenCode `ProviderConfig` does not allow unknown provider-level keys such as `modelOverrides`. Overrides deep-merge onto matching generated entries and can add custom models:
+One key per workspace: each project folder uses its own Route 33 key, and
+every request carries the key of its own workspace — connecting another
+folder never changes who this one bills for. Keys are short-lived and rotate
+automatically; nothing secret is ever written to your project, logs, or
+terminal.
 
-```json
-{
-  "models": {
-    "openai/gpt-5.5": { "variants": { "fast": { "temperature": 0 } } },
-    "custom/internal": { "name": "Internal model" }
-  }
-}
-```
-
-If the gateway fetch fails with no usable cache, regeneration is skipped entirely: existing entries are never pruned on zero information.
-
-`ROUTE33_ENRICH_CAPS` has been removed; capability backfill from `models.dev` is now always on.
-
-## Model-reference tolerance
-
-Model references in your config that differ from the served ID only by digit-boundary dots versus dashes in the tail resolve automatically. For example, `anthropic/claude-opus-4.8` resolves to the served `anthropic/claude-opus-4-8` and is injected with the served wire ID. Arbitrary renames, such as `gpt5.5` for `openai/gpt-5.5`, do not resolve.
-
-## Environment variables
-
-| Variable | Effect |
-|---|---|
-| `ROUTE33_API_KEY` | Gateway API key; highest precedence. See Auth. |
-| `ROUTE33_BASE_URL` | Override the default gateway base URL. See Auth. |
-| `ROUTE33_TUI_PROMPT` | Set to `0` to disable the key-setup wizard. See Auth. |
-| `ROUTE33_DISCOVERY` | Set to `0` to disable dynamic catalog discovery. |
-| `ROUTE33_STRICT` | Set to `0` to downgrade unknown-model reference errors to a warning plus a stub entry. |
-| `ROUTE33_CACHE_DIR` | Override the directory used for the on-disk catalog cache. |
+## Direct key mode
 
-The plugin reads only these variables. `ROUTE33_ENRICH_CAPS` is no longer supported.
-
-## Exhaustion retry
-
-Starting with v0.4.6, the plugin wraps live chat/compat requests in an exhaustion retry layer. It triggers only on an HTTP `429` whose error code is `PROVIDER_LANES_EXHAUSTED` (all provider lanes exhausted). It reads the gateway's `Retry-After` response header and falls back to a client-side schedule of `5·2^(n−1)` seconds capped at 1200 when the header is missing. It waits through the delay while respecting the request's abort signal, then re-issues the identical request. It keeps retrying indefinitely until the request succeeds or the user cancels it.
-
-Non-exhaustion errors (network failures, 4xx responses from the gateway other than the exhaustion code, etc.) are passed through untouched.
-
-Each wait is logged with the attempt number, waited seconds, and the gateway's `correlationId`:
+Set `ROUTE33_API_KEY` to a gateway key and the wizard is bypassed entirely —
+no sign-in, no attribution pick, no browser, no per-workspace keys. This is
+the right choice for autonomous, headless, or remote sessions where no human
+is present or the machine has no browser. Key rotation is your responsibility.
 
+```sh
+export ROUTE33_API_KEY=r33_sk_...
 ```
-route33: exhausted; waiting <seconds>s before retry <attempt> (correlationId=<correlationId>)
-```
-
-The provider option `headerTimeout` is set to `1_500_000` ms (25 minutes). This is higher than opencode's own 300-second fetch default so that scheduled waits are not aborted while waiting for a lane to cool down. It is safe because the gateway caps provider hangs at 120 s TTFB and 240 s first-event timeouts, so the connection is never silent for anywhere near 25 minutes.
-
-## License
 
-Proprietary — "SEE LICENSE IN LICENSE". Install and use as-is via npm; copying, modification, and redistribution are not permitted. Provided AS-IS, without warranty or liability.
+## Auto-connect
+
+When a folder is not yet connected, the wizard auto-starts at OpenCode launch:
+the browser sign-in opens immediately and the project picker follows — no
+command needed. Suppress this with `ROUTE33_AUTOCONNECT=0` and use `/connect`
+(v2) or `/r33` (v1) manually instead. On remote or headless machines, use
+`ROUTE33_API_KEY` instead of the wizard.
+
+## OpenCode v1
+
+On OpenCode v1, `/r33` in the TUI signs in with the browser, opens the
+project picker, and leases this folder's key; the models load after a
+restart. The wizard auto-starts at TUI launch when the folder is
+unconnected. The auto-start does not intercept the first prompt because
+v1's TUI API offers no pre-prompt hook — the wizard runs in parallel.
+
+## Troubleshooting
+
+| Symptom                                       | What to do                                                                       |
+| --------------------------------------------- | -------------------------------------------------------------------------------- |
+| No route_33 models after start                | `/connect` → Route 33 — the silent sign-in expired; sign in once and they return |
+| "This Route 33 build has no OAuth client id"  | Update the plugin to a released build, or set `ROUTE33_CLIENT_ID` and restart    |
+| "needs a Git worktree"                        | Open a Git repository (or `git init`) in the folder, then connect again          |
+| Sign-in link never appears / SSH-only machine | Sign-in needs a browser on the same machine — there is no device-flow fallback   |
+
+## Configuration
+
+| Variable              | Purpose                                      | Default                          |
+| --------------------- | -------------------------------------------- | -------------------------------- |
+| `ROUTE33_API_KEY`     | Pre-shared gateway key (bypasses the wizard) | not set (wizard mode)            |
+| `ROUTE33_AUTOCONNECT` | Opt out of the auto-start wizard             | `1` (auto-start enabled)         |
+| `ROUTE33_CLIENT_ID`   | OAuth client identifier                      | included in released builds      |
+| `ROUTE33_AUTH_ISSUER` | OAuth issuer                                 | `https://auth.route33.ai`        |
+| `ROUTE33_API_BASE`    | Management API base                          | `https://mapi.route33.ai/api/v1` |
+| `ROUTE33_BASE_URL`    | Gateway models base                          | `https://api.route33.ai/v1`      |