mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-11-16 17:09:09 +00:00
⚠️ base-red inherited: #17219 ## Summary Behavior change: the serving provider is now always part of an entry's name, and the editor/upstream moves to a trailing parenthesis. Before, the name builder prefixed every entry with the model's editor/upstream, hiding the route and letting three incompatible `free` conventions and volatile `auto/*` names coexist. Now an entry reads `Provider - Model`, with a leading `🆓 ` when free, combos read `combo - slug`, a route suffix appears only on same-provider name collisions, and `providerTag` becomes the switch for the editor parenthesis: `true` by default, `false` drops it. ## Related Issues - No linked issue — the symptom was reproduced on the release base ## Target Branch Thanks @maxmad64bis.
192 lines
24 KiB
Markdown
192 lines
24 KiB
Markdown
# @omniroute/opencode-plugin-v2
|
|
|
|
OpenCode v2 plugin (`define({ id, setup })`, Promise API) that publishes the live OmniRoute catalog — models from `/v1/models`, combos from `/api/combos` (least-common-denominator join), enrichment (names + pricing), and usable-provider filtering — into the v2 `catalog.transform`, with `key` + `env` auth via `integration.transform`.
|
|
|
|
Companion to `@omniroute/opencode-plugin` (OpenCode v1, same repo). The two packages are independent: this one carries its own catalog-mapping logic and the v1 plugin is left untouched.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
npm install @omniroute/opencode-plugin-v2
|
|
```
|
|
|
|
`opencode.json`:
|
|
|
|
```json
|
|
{
|
|
"plugins": [
|
|
{
|
|
"package": "@omniroute/opencode-plugin-v2",
|
|
"options": {
|
|
"providerId": "omniroute",
|
|
"baseURL": "http://localhost:20128"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Local `file://` install
|
|
|
|
OpenCode resolves a local plugin **directory** by probing the subpaths
|
|
`server.*` / `index.*` (then `tui`, `rpc`) at the package root — it never
|
|
reads `package.json` `main`/`exports`. A folder exposing only `dist/` is
|
|
therefore silently skipped (no `loading plugin`, no error).
|
|
|
|
This package ships a root `server.js` re-exporting `./dist/index.js` for
|
|
exactly that probe, so pointing OpenCode at a local checkout works:
|
|
|
|
```json
|
|
{
|
|
"plugins": [
|
|
{
|
|
"package": "file:///path/to/OmniRoute/@omniroute/opencode-plugin-v2",
|
|
"options": {
|
|
"providerId": "omniroute",
|
|
"baseURL": "http://localhost:20128"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Prerequisites when targeting a folder: run `npm run build` first (the root
|
|
`server.js` re-exports `./dist/index.js`), and keep the folder's root
|
|
`server.js` — `dist/` alone is not resolvable by the host.
|
|
|
|
## Credentials
|
|
|
|
The plugin needs a gateway key to read the catalog, and looks for one in this
|
|
order:
|
|
|
|
1. **The credential you connected in OpenCode.** The plugin registers an
|
|
integration, so `opencode auth` (or the Connect action in the model picker)
|
|
can store a key for it. Nothing is written to `opencode.json` — this is the
|
|
recommended route.
|
|
2. **`apiKey` in the plugin options**, when you want a per-project override.
|
|
Remember that this puts the key in a config file you may be committing.
|
|
3. **`OMNIROUTE_API_KEY` in the environment.**
|
|
|
|
If none of the three yields a key, the catalog is empty and the plugin says so
|
|
once at startup rather than leaving you with a silent empty model list.
|
|
|
|
### The management token is a different key
|
|
|
|
Combos, provider health and enrichment (display names, pricing, free-tier
|
|
budgets) come from the gateway's `/api/*` endpoints, which most deployments
|
|
gate behind a **management** token rather than the inference key. Set it
|
|
explicitly:
|
|
|
|
```json
|
|
"options": {
|
|
"baseURL": "http://localhost:20128",
|
|
"managementReadToken": "<management read token>"
|
|
}
|
|
```
|
|
|
|
The token can also come from the `OMNIROUTE_MANAGEMENT_API_KEY` environment
|
|
variable (the option wins when both are set). Resolution order:
|
|
`managementReadToken` option, then `OMNIROUTE_MANAGEMENT_API_KEY`, then the
|
|
`apiKey` fallback.
|
|
|
|
Left unset, `managementReadToken` falls back to `apiKey` for backwards
|
|
compatibility, and the plugin warns once at startup that the fallback is
|
|
active. When a gateway rejects that fallback, the catalog still
|
|
publishes — but with raw model ids instead of display names, no canonical
|
|
alias dedupe, no pricing and no combos. The plugin warns once per endpoint
|
|
when this happens, naming the endpoint and the consequence, so the degraded
|
|
catalog is never a mystery. Environment variables must reach the opencode
|
|
server process: when the host runs as a service, export the key where the
|
|
server reads it, not only in the shell that runs `opencode models`.
|
|
|
|
## Options
|
|
|
|
| Key | Default | Notes |
|
|
| --------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `providerId` | `"omniroute"` | Provider id and integration id; models publish under `<providerId>/...` |
|
|
| `baseURL` | required | OmniRoute gateway root (no `/v1` suffix needed) |
|
|
| `apiKey` | connected credential, then `OMNIROUTE_API_KEY` | Chat key for `/v1/*` — see [Credentials](#credentials) |
|
|
| `managementReadToken` | option, then `OMNIROUTE_MANAGEMENT_API_KEY`, then `apiKey` | Management key for `/api/*` (combos, providers, enrichment) — usually **not** the same key |
|
|
| `displayName` | `"OmniRoute"` | Provider display name |
|
|
| `timeoutMs` | `10000` | Per-endpoint fetch timeout |
|
|
| `modelCacheTtlMs` | `300000` | Catalog cache TTL and background refresh period (minimum 60000 ms): the served catalog follows the gateway within this window, with no service restart; disk snapshot warms cold starts |
|
|
| `timeouts` | per-endpoint override | `{ models, combos, enrichment }` in ms; falls back to `timeoutMs` (`autoCombos` still parses but is ignored — the virtual-entries route is no longer requested) |
|
|
| `enrichment` | `true` | Fetch names + pricing (`/api/pricing*`, `/api/free-tier/summary`) |
|
|
| `providerTag` | `true` | Toggle the trailing editor parenthesis: `Provider - Model (Editor)`. The provider (the route that serves the model: Openrouter, Opencode-go, Nvidia for `nvidia/...` ids) is always shown; the editor (who made the model: MoonshotAI, Meta, DeepSeek) appears only in the parenthesis. Example: `Openrouter - MoonshotAI: Kimi K 3.1 Pro` -> `Openrouter - Kimi K 3.1 Pro (MoonshotAI)`. The parenthesis is omitted when the editor shares the provider's name. Set `false` to drop it. |
|
|
| `geminiSanitization` | `true` | Strip `$schema`/`additionalProperties` from tool schemas sent to Gemini models (`$ref` tools are forwarded untouched) |
|
|
| `usableOnly` | `false` | Filter to healthy provisioned providers (`/api/providers`) |
|
|
| `combosSource` | `"api"` | Combo source. `"api"` reads `/api/combos` and publishes a combo only when every member passes the filters; `"models"` skips that request and publishes the combo rows `/v1/models` serves. Any preset, `usableOnly`, `providersAllow` or visible/hidden list keeps `"api"` |
|
|
| `freeOnly` / `toolsOnly` / `visionOnly` | `false` / `false` / `false` | Filter to free-tier / tool-calling / image-input models; combos with a filtered member are dropped, never partial. Presets filter the pool before the default view ranks it, and a combo publishes only when every resolved member passes (dropped when a member fails or none resolves) |
|
|
| `freeSignals` | `["declared"]` | Extra signals that admit a model under `freeOnly`: `priced`, `named`, `provider-named` (see below) |
|
|
| `freeProviders` | none | Provider prefixes counted as free by `provider-named` |
|
|
| `showcasePerOwner` | `10` | Default-view entries kept per provider |
|
|
| `freshPerOwner` | `10` | Default-view fresh entries kept per provider |
|
|
| `freshWindowDays` | `90` | Freshness window in days for the fresh branch |
|
|
| `usageMemory` | `true` | Restore statically dropped entries named by 30-day usage analytics (needs a management token; inert without one) |
|
|
| `visibleModels` / `hiddenModels` | `[]` | Exact (`cc/keep-me`), suffix (`keep-me`), or branch (`prefix/*`) entries ; deny wins ; `"*"` publishes the full catalog and skips narrowing |
|
|
| `providersAllow` | `[]` | Provider allowlist by flat name, or branch claim (`prefix/*`) for exhaustive mode ; a branch claim names a branch, a flat entry names a provider prefix |
|
|
| `combos` | `true` | Set to `false` to hide every combo (no `/api/combos` request, no combo rows from `/v1/models`) ; models are unchanged |
|
|
| `apiFormat.allowAnthropic` | `false` | Route allowlisted ids to the Anthropic API block |
|
|
| `apiFormat.anthropicModels` | `[]` | Full model ids routed to Anthropic |
|
|
| `apiFormat.anthropicPrefixes` | v1 defaults | Deprecated, warns once — prefer `anthropicModels` |
|
|
| `logLevel` / `startupDebug` | `warn` / `false` | Logger verbosity |
|
|
|
|
`toolsOnly` is off by default, so the full catalog is published. Set
|
|
`toolsOnly: true` to hide models without tool calling from the host picker —
|
|
useful for agent sessions that call tools on almost every turn. It does not cap
|
|
the catalog size, and a very large catalog can still slow the host picker (see
|
|
[opencode#47615](https://github.com/anomalyco/opencode/issues/47615)).
|
|
|
|
Usage memory is on by default. Without a management token it stays inert
|
|
(a startup notice is logged) and nothing is restored — the picker stays filtered.
|
|
|
|
`"*"` publishes the full catalog and ignores showcase and fresh narrowing.
|
|
|
|
A visible branch keeps a combo when any member is in the branch ; `hiddenModels` removes the same combo the same way. Combos are filtered by members, not by combo id.
|
|
|
|
A visible entry pins its branch : the whole branch is published, including rows the default view would drop (retired rows, rows past the fresh and showcase caps) ; capability filters and `usableOnly` still apply.
|
|
|
|
## Inferred free models
|
|
|
|
`freeOnly` keeps the models the free-tier catalog classifies. That list can lag what the gateway serves, so `freeSignals` lets you opt into a few weaker signals. The default stays `["declared"]`; nothing changes unless you set it. Models admitted by an inferred signal are labelled `(free, inferred)`.
|
|
|
|
| Signal | Admits a model when |
|
|
| ---------------- | ----------------------------------------------------------------------------------------------- |
|
|
| `priced` | the pricing table lists `input` and `output` at `0` for its `<provider>/<model>` id |
|
|
| `named` | its id ends in `-free` or `:free` and the pricing table holds no price for it (any price field) |
|
|
| `provider-named` | its provider prefix ends in `-free`, or is listed in `freeProviders` |
|
|
|
|
```json
|
|
{ "freeOnly": true, "freeSignals": ["declared", "priced", "named"] }
|
|
```
|
|
|
|
What the signals do not do:
|
|
|
|
- A declared classification always wins. `one-time-initial` and `discontinued` entries are never promoted, and any price field other than zero (`input`, `output`, `cacheRead`, `cacheWrite`) vetoes every inferred signal.
|
|
- Bare ids (no provider prefix) are never inferred, and a price stored under a bare id is ignored.
|
|
- Router entries (an `auto` or `auto-*` segment after the provider prefix) carry a placeholder zero price, so `priced` skips them. Routers whose price depends on the routed target (`pareto-code`, `bodybuilder`) are not recognised and may be admitted by `priced`, `named` or `provider-named`.
|
|
- `freeProviders` matches the provider prefix as served or its alias/canonical twin, case-insensitively.
|
|
- With `provider-named` on, no overlay is needed, so the empty-overlay warning is not issued; with the other signals it still is when the overlay is fully empty.
|
|
- A zero price can also mean a trial credit or a quota the pricing table does not model. Treat `(free, inferred)` as "looks free", not as a contract.
|
|
|
|
## Tool calling on Gemini models
|
|
|
|
Gemini answers `400 INVALID_ARGUMENT` — for the whole request, not just the
|
|
offending tool — when a tool declaration carries `$schema` or
|
|
`additionalProperties`. Anything that emits standard JSON Schema therefore
|
|
breaks tool calling as soon as the chain routes to Gemini.
|
|
|
|
The plugin strips those keywords from tool schemas bound for a Gemini model of
|
|
this provider, and leaves every other request untouched. A tool carrying a
|
|
`$ref` is forwarded untouched instead of stripped: removing the reference
|
|
would widen the schema to "accept anything". Set
|
|
`"geminiSanitization": false` to turn it off.
|
|
|
|
## Migrating from the v1 plugin
|
|
|
|
The v2 plugin publishes provider id `X` bare. The v1 plugin published `opencode-X` (native-adapter gate). Sessions pinned to `opencode-X/...` must re-select the model under `X/...`.
|
|
|
|
## License
|
|
|
|
MIT
|