Release v3.8.53 — 1,189 documented changes from 1,162 cycle commits and 208 contributor rows; full changelog in CHANGELOG.md → [3.8.53].
Merged by explicit owner decision at STOP #1 on head 6cc69650, without --admin (main has no required checks). Gate / CI passed on this head: 8 unit shards, Coverage and Quality Ratchet. Security: 0 npm, 0 CodeQL high, 0 Dependabot high.
Red at merge, accepted by the owner:
- Gate / Quality and Fast Quality Gates: complexity-ratchets and dead-code compare the whole cycle against main (11 dead exports; total complexity fell from 1,921 to 1,873). Cleanup follows in v3.8.54.
- dast-smoke: advisory.
- Release-Green: FAIL on `unit-6 no result` (cancelled at the 30-minute limit, cause not identified). Pack, boot and the other 64 commands passed on 7e640dee; there is no complete run on this head.
SonarQube is off (SONARQUBE_ENABLED=false). ⚠️ base-red inherited: #18791, #17267.
18 KiB
@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
npm install @omniroute/opencode-plugin-v2
opencode.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:
{
"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:
- 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 toopencode.json— this is the recommended route. apiKeyin the plugin options, when you want a per-project override. Remember that this puts the key in a config file you may be committing.OMNIROUTE_API_KEYin 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:
"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 |
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 |
Prefix a display name with the upstream provider it routes to |
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).
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 |
{ "freeOnly": true, "freeSignals": ["declared", "priced", "named"] }
What the signals do not do:
- A declared classification always wins.
one-time-initialanddiscontinuedentries 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
autoorauto-*segment after the provider prefix) carry a placeholder zero price, sopricedskips them. Routers whose price depends on the routed target (pareto-code,bodybuilder) are not recognised and may be admitted bypriced,namedorprovider-named. freeProvidersmatches the provider prefix as served or its alias/canonical twin, case-insensitively.- With
provider-namedon, 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