@route_33/opencode 0.3.0 → 0.4.0

package/README.md

@@ -13,14 +13,14 @@ The installer patches both configs: the server plugin into `opencode.json` and t
 ```jsonc
 // opencode.json — server plugin (model discovery, cost/limit enrichment, auth)
 {
-  "plugin": ["@route_33/opencode@^0.2"]
+  "plugin": ["@route_33/opencode"]
 }
 ```
 
 ```jsonc
 // tui.json — TUI plugin (the key-setup wizard)
 {
-  "plugin": ["@route_33/opencode@^0.2"]
+  "plugin": ["@route_33/opencode"]
 }
 ```
 
@@ -30,6 +30,55 @@ This plugin never writes your config: opencode has no TUI-plugin auto-discovery,
 
 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.
 
+## 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, inject zero models.
+
+The plugin does not embed or serve a static catalog.
+
+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.
+```
+
+Set `ROUTE33_DISCOVERY=0` to opt out of discovery entirely. This is logged at `info` and injects zero models without the warning.
+
+## Metadata provenance
+
+Models are decorated with metadata from the route33 gateway broadcast; `models.dev` is used only as a backfill source.
+
+- **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.
+- **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).
+
+The normative contract for limits and variants is [docs/gateway-limits-variants-broadcast.md](docs/gateway-limits-variants-broadcast.md).
+
+`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. |
+
+The plugin reads only these variables. `ROUTE33_ENRICH_CAPS` is no longer supported.
+
 ## 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.

package/dist/index.js

@@ -58,9 +58,6 @@ var ENV_DISABLE_ID_SHIM = "ROUTE33_DISABLE_ID_SHIM";
 // src/shared/env-discovery.ts
 var ENV_DISCOVERY = "ROUTE33_DISCOVERY";
 
-// src/shared/env-enrich-caps.ts
-var ENV_ENRICH_CAPS = "ROUTE33_ENRICH_CAPS";
-
 // src/shared/env-strict.ts
 var ENV_STRICT = "ROUTE33_STRICT";
 
@@ -346,22 +343,21 @@ function toModelPatch(meta, routingSlug, forceReasoning, nativeNpm) {
 
 // src/config/build-provider-blocks.ts
 var PROVIDER_DISPLAY_NAME = "route_33";
-function vendorOf(slug2) {
-  return slug2.slice(0, slug2.indexOf("/"));
+function vendorOf(slug) {
+  return slug.slice(0, slug.indexOf("/"));
 }
 function buildProviderBlocks(enriched, options) {
-  const { apiKey, baseURL, aliasTargets } = options;
+  const { apiKey, baseURL } = options;
   const resolveKeyNow = options.resolveKeyNow ?? (() => void 0);
   const route33Models = {};
-  for (const slug2 of Object.keys(enriched).sort()) {
-    const meta = enriched[slug2];
+  for (const slug of Object.keys(enriched).sort()) {
+    const meta = enriched[slug];
     if (meta === void 0) continue;
-    const aliasTarget = aliasTargets?.[slug2];
-    const vendor = vendorOf(slug2);
+    const vendor = vendorOf(slug);
     const nativeNpm = NATIVE_SDK_BY_VENDOR[vendor];
-    route33Models[slug2] = toModelPatch(
+    route33Models[slug] = toModelPatch(
       meta,
-      aliasTarget,
+      void 0,
       vendor === "anthropic",
       nativeNpm
     );
@@ -576,18 +572,45 @@ function parseEntries(payload) {
     "response is neither {data:[\u2026]} nor a bare array"
   );
 }
+function positiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function parseLimit(raw) {
+  if (!isRecord5(raw)) return void 0;
+  if (!positiveInteger(raw.context) || !positiveInteger(raw.output))
+    return void 0;
+  return { context: raw.context, output: raw.output };
+}
+function parseCapabilities(raw) {
+  if (!isRecord5(raw)) return void 0;
+  const capabilities = {};
+  if (raw.reasoning === true) capabilities.reasoning = true;
+  if (raw.tool_support === true) capabilities.tool_call = true;
+  return Object.keys(capabilities).length > 0 ? capabilities : void 0;
+}
+function parseVariants(raw) {
+  if (!isRecord5(raw)) return void 0;
+  if (!Object.values(raw).every(isRecord5)) return void 0;
+  return raw;
+}
 function toCatalogModels(entries, env) {
   const models = {};
   for (const entry of entries) {
     if (!isRecord5(entry) || typeof entry.id !== "string") continue;
-    const slug2 = normalizeId(entry.id, env);
-    if (!slug2 || models[slug2]) continue;
-    const model = { id: slug2 };
+    const slug = normalizeId(entry.id, env);
+    if (!slug || models[slug]) continue;
+    const model = { id: slug };
     const displayName = typeof entry.display_name === "string" ? entry.display_name.trim() : "";
     if (displayName !== "") model.displayName = displayName;
     if (isRecord5(entry.pricing) && extractPricing(entry.pricing) !== void 0)
       model.pricing = entry.pricing;
-    models[slug2] = model;
+    const limit = parseLimit(entry.limits);
+    if (limit !== void 0) model.limit = limit;
+    const capabilities = parseCapabilities(entry.capabilities);
+    if (capabilities !== void 0) model.capabilities = capabilities;
+    const variants = parseVariants(entry.variants);
+    if (variants !== void 0) model.variants = variants;
+    models[slug] = model;
   }
   return models;
 }
@@ -647,19 +670,17 @@ async function fetchCatalog(opts) {
 }
 
 // src/catalog/catalog-service.ts
-function seedResult(seed, why) {
-  const models = {};
-  for (const entry of seed) {
-    models[entry.slug] = { id: entry.slug };
-  }
-  logger.info(`catalog source: seed (${why}; ${seed.length} model(s))`);
-  return { models, source: "seed" };
+function noneResult(reason, optOut) {
+  const message = `route33: no model catalog available \u2014 0 models injected (${reason}). route33 is unusable without a catalog: resolve an API key (opencode auth login / ROUTE33_API_KEY) \u2014 the key dictates which models are available.`;
+  if (optOut) logger.info(message);
+  else logger.warn(message);
+  return { models: {}, source: "none" };
 }
 async function runLadder(opts) {
-  const { key, baseURL, seed, env = process.env, fetchImpl, now } = opts;
+  const { key, baseURL, env = process.env, fetchImpl, now } = opts;
   if (env[ENV_DISCOVERY] === "0")
-    return seedResult(seed, `discovery disabled via ${ENV_DISCOVERY}=0`);
-  if (!key) return seedResult(seed, "no API key resolved");
+    return noneResult(`discovery disabled via ${ENV_DISCOVERY}=0`, true);
+  if (!key) return noneResult("no API key resolved", false);
   const fresh = readFreshCatalog({ key, env, now });
   if (fresh) {
     logger.info(
@@ -686,280 +707,33 @@ async function runLadder(opts) {
     );
     return { models: stale, source: "stale-cache" };
   }
-  return seedResult(seed, "live fetch failed and no cache available");
+  return noneResult("live fetch failed and no cache available", false);
 }
 async function getCatalog(opts) {
   try {
     return await runLadder(opts);
   } catch (error) {
     logger.error(
-      `unexpected catalog-service failure \u2014 degrading to seed: ${error instanceof Error ? error.message : String(error)}`
+      `unexpected catalog-service failure \u2014 no catalog available: ${error instanceof Error ? error.message : String(error)}`
     );
-    try {
-      return seedResult(opts.seed, "unexpected internal failure");
-    } catch {
-      return { models: {}, source: "seed" };
-    }
+    return noneResult("unexpected internal failure", false);
   }
 }
 
-// src/catalog/seed/anthropic-gateway-limit.ts
-var ANTHROPIC_GATEWAY_LIMIT = {
-  context: 1e6,
-  output: 32e3
-};
-
-// src/catalog/seed/slug.ts
-var slug = (s) => s;
-
-// src/catalog/seed/claude-opus.ts
-var CLAUDE_OPUS = {
-  slug: slug("anthropic/claude-opus-4.8"),
-  name: "Claude Opus 4.8",
-  cost: {
-    input: 5,
-    // source: models.dev 2026-07-04 (key: anthropic/claude-opus-4-8, dash form)
-    output: 25,
-    // source: models.dev 2026-07-04
-    cache_read: 0.5,
-    // source: models.dev 2026-07-04
-    cache_write: 6.25
-    // source: models.dev 2026-07-04
-  },
-  limit: ANTHROPIC_GATEWAY_LIMIT,
-  capabilities: { reasoning: true }
-};
-
-// src/catalog/seed/claude-sonnet.ts
-var CLAUDE_SONNET = {
-  slug: slug("anthropic/claude-sonnet-4.6"),
-  name: "Claude Sonnet 4.6",
-  cost: {
-    input: 3,
-    // source: models.dev 2026-07-04 (key: anthropic/claude-sonnet-4-6, dash form)
-    output: 15,
-    // source: models.dev 2026-07-04
-    cache_read: 0.3,
-    // source: models.dev 2026-07-04
-    cache_write: 3.75
-    // source: models.dev 2026-07-04
-  },
-  limit: ANTHROPIC_GATEWAY_LIMIT,
-  capabilities: { reasoning: true }
-};
-
-// src/catalog/seed/gemini-3-1-pro-preview.ts
-var GEMINI_3_1_PRO_PREVIEW = {
-  slug: slug("google/gemini-3.1-pro-preview"),
-  name: "Gemini 3.1 Pro Preview",
-  cost: {
-    input: 2,
-    // source: models.dev 2026-07-04
-    output: 12,
-    // source: models.dev 2026-07-04
-    cache_read: 0.2,
-    // source: models.dev 2026-07-04
-    // models.dev's context tier boundary is exactly 200,000 tokens here —
-    // context_over_200k is the lossless encoding (D20 "certainty achieved").
-    context_over_200k: {
-      input: 4,
-      // source: models.dev 2026-07-04
-      output: 18,
-      // source: models.dev 2026-07-04
-      cache_read: 0.4
-      // source: models.dev 2026-07-04
-    }
-  },
-  limit: { context: 1048576, output: 65536 },
-  // source: models.dev 2026-07-04
-  capabilities: {}
-};
-
-// src/catalog/seed/glm-5-2.ts
-var GLM_5_2 = {
-  slug: slug("z-ai/glm-5.2"),
-  name: "GLM-5.2",
-  cost: {
-    input: 1.4,
-    // source: models.dev 2026-07-04 (provider key: zai)
-    output: 4.4,
-    // source: models.dev 2026-07-04
-    cache_read: 0.26
-    // source: models.dev 2026-07-04
-    // cache_write deliberately OMITTED: models.dev lists a literal 0, which
-    // the seed contract forbids as a recorded price. Omission makes opencode
-    // bill cache writes at the input rate — the conservative D20 fallback
-    // (overestimate over a possibly-wrong free write).
-  },
-  limit: { context: 1e6, output: 131072 },
-  // source: models.dev 2026-07-04
-  capabilities: {}
-};
-
-// src/catalog/seed/gpt-4o-mini.ts
-var GPT_4O_MINI = {
-  slug: slug("openai/gpt-4o-mini"),
-  name: "GPT-4o mini",
-  cost: {
-    input: 0.15,
-    // source: models.dev 2026-07-04
-    output: 0.6,
-    // source: models.dev 2026-07-04
-    cache_read: 0.075
-    // source: models.dev 2026-07-04
-  },
-  limit: { context: 128e3, output: 16384 },
-  // source: models.dev 2026-07-04
-  capabilities: {}
-};
-
-// src/catalog/seed/gpt-5-4-mini.ts
-var GPT_5_4_MINI = {
-  slug: slug("openai/gpt-5.4-mini"),
-  name: "GPT-5.4 mini",
-  cost: {
-    input: 0.75,
-    // source: models.dev 2026-07-04
-    output: 4.5,
-    // source: models.dev 2026-07-04
-    cache_read: 0.075
-    // source: models.dev 2026-07-04
-  },
-  limit: { context: 4e5, output: 128e3 },
-  // source: models.dev 2026-07-04
-  // Reasoning model; opencode's variants gate (transform.ts) requires the flag.
-  capabilities: { reasoning: true }
-};
-
-// src/catalog/seed/gpt-5-5.ts
-var GPT_5_5 = {
-  slug: slug("openai/gpt-5.5"),
-  name: "GPT-5.5",
-  cost: {
-    input: 5,
-    // source: models.dev 2026-07-04
-    output: 30,
-    // source: models.dev 2026-07-04
-    cache_read: 0.5,
-    // source: models.dev 2026-07-04
-    // models.dev lists a context tier at 272k tokens (input 10 / output 45 /
-    // cache_read 1) AND ships this pre-computed context_over_200k with the
-    // same rates. The 272k boundary itself is inexpressible in the config
-    // schema; billing the higher tier from 200k instead only ever
-    // OVER-estimates the 200k–272k window — D20's conservative branch,
-    // encoded precisely rather than flattened to a max rate.
-    context_over_200k: {
-      input: 10,
-      // source: models.dev 2026-07-04
-      output: 45,
-      // source: models.dev 2026-07-04
-      cache_read: 1
-      // source: models.dev 2026-07-04
-    }
-  },
-  limit: { context: 105e4, output: 128e3 },
-  // source: models.dev 2026-07-04
-  // Reasoning model; opencode's variants gate (transform.ts) requires the flag.
-  capabilities: { reasoning: true }
-};
-
-// src/catalog/seed/kimi-k2-6.ts
-var KIMI_K2_6 = {
-  slug: slug("moonshotai/kimi-k2.6"),
-  name: "Kimi K2.6",
-  cost: {
-    input: 0.95,
-    // source: models.dev 2026-07-04
-    output: 4,
-    // source: models.dev 2026-07-04
-    cache_read: 0.16
-    // source: models.dev 2026-07-04
-  },
-  limit: { context: 262144, output: 262144 },
-  // source: models.dev 2026-07-04
-  capabilities: {}
-};
-
-// src/catalog/seed/kimi-k2-7-code.ts
-var KIMI_K2_7_CODE = {
-  slug: slug("moonshotai/kimi-k2.7-code"),
-  name: "Kimi K2.7 Code",
-  cost: {
-    input: 0.95,
-    // source: models.dev 2026-07-04
-    output: 4,
-    // source: models.dev 2026-07-04
-    cache_read: 0.19
-    // source: models.dev 2026-07-04
-  },
-  limit: { context: 262144, output: 262144 },
-  // source: models.dev 2026-07-04
-  capabilities: {}
-};
-
-// src/catalog/seed/kimi-k3.ts
-var KIMI_K3 = {
-  slug: slug("moonshotai/kimi-k3"),
-  name: "Kimi K3",
-  cost: {
-    input: 3,
-    // source: models.dev 2026-07-18
-    output: 15,
-    // source: models.dev 2026-07-18
-    cache_read: 0.3
-    // source: models.dev 2026-07-18
-  },
-  limit: { context: 1048576, output: 131072 },
-  // source: models.dev 2026-07-18
-  capabilities: { reasoning: true },
-  // opencode-go parity: the openai-compatible lowerer wires reasoning_effort: "max".
-  variants: { max: { reasoningEffort: "max" } }
-};
-
-// src/catalog/seed/seed.ts
-var SEED = [
-  GPT_5_5,
-  GPT_5_4_MINI,
-  GEMINI_3_1_PRO_PREVIEW,
-  KIMI_K2_6,
-  KIMI_K2_7_CODE,
-  KIMI_K3,
-  GPT_4O_MINI,
-  GLM_5_2,
-  CLAUDE_OPUS,
-  CLAUDE_SONNET,
-  // D10 dash-form aliases — spread from their canonical entries so
-  // cost/limit/capabilities stay identical by construction.
-  {
-    ...CLAUDE_OPUS,
-    slug: slug("anthropic/claude-opus-4-8"),
-    name: `${CLAUDE_OPUS.name} (alias)`,
-    aliasOf: CLAUDE_OPUS.slug
-  },
-  {
-    ...CLAUDE_SONNET,
-    slug: slug("anthropic/claude-sonnet-4-6"),
-    name: `${CLAUDE_SONNET.name} (alias)`,
-    aliasOf: CLAUDE_SONNET.slug
-  }
-];
-
-// src/enrich/static-meta.ts
-var lookupSeed = (slug2) => SEED.find((entry) => entry.slug === slug2) ?? SEED.find((entry) => entry.aliasOf === slug2);
-
 // src/enrich/enrich-model.ts
-function resolveCost(catalogModel, modelsDevLookup, seed) {
+function resolveCost(catalogModel, modelsDevLookup) {
   const r33Cost = catalogModel?.pricing !== void 0 ? extractPricing(catalogModel.pricing) : void 0;
-  return r33Cost ?? modelsDevLookup?.cost ?? seed?.cost;
+  return r33Cost ?? modelsDevLookup?.cost;
 }
-function resolveLimit(seed, modelsDevLookup) {
-  return seed?.limit ?? modelsDevLookup?.limit;
+function resolveLimit(catalogModel, modelsDevLookup) {
+  return catalogModel?.limit ?? modelsDevLookup?.limit;
 }
-function resolveCapabilities(seed, modelsDevLookup, env) {
-  const base = seed?.capabilities ?? {};
-  if (env[ENV_ENRICH_CAPS] !== "1" || modelsDevLookup === void 0)
-    return base;
-  const result = { ...base };
+function resolveCapabilities(catalogModel, modelsDevLookup) {
+  const result = {};
+  const broadcast = catalogModel?.capabilities;
+  if (broadcast?.reasoning !== void 0) result.reasoning = broadcast.reasoning;
+  if (broadcast?.tool_call !== void 0) result.tool_call = broadcast.tool_call;
+  if (modelsDevLookup === void 0) return result;
   if (result.reasoning === void 0 && modelsDevLookup.reasoning !== void 0)
     result.reasoning = modelsDevLookup.reasoning;
   if (result.tool_call === void 0 && modelsDevLookup.tool_call !== void 0)
@@ -971,21 +745,25 @@ function resolveCapabilities(seed, modelsDevLookup, env) {
   }
   return result;
 }
-function enrichModel(slug2, sources) {
-  const env = sources.env ?? process.env;
-  const seed = lookupSeed(slug2);
-  const modelsDevLookup = sources.modelsDev.lookup(slug2);
-  const capabilities = resolveCapabilities(seed, modelsDevLookup, env);
+function enrichModel(slug, sources) {
+  const modelsDevLookup = sources.modelsDev.lookup(slug);
   const catalogModel = sources.catalogModel;
-  const name = catalogModel !== void 0 && catalogModel.id === slug2 && catalogModel.displayName !== void 0 ? catalogModel.displayName : slug2;
+  const capabilities = resolveCapabilities(catalogModel, modelsDevLookup);
+  const name = catalogModel !== void 0 && catalogModel.id === slug && catalogModel.displayName !== void 0 ? catalogModel.displayName : slug;
   const meta = { name, capabilities };
-  const limit = resolveLimit(seed, modelsDevLookup);
-  if (limit !== void 0) meta.limit = limit;
-  if (seed?.variants !== void 0) meta.variants = seed.variants;
-  const cost = resolveCost(sources.catalogModel, modelsDevLookup, seed);
+  const limit = resolveLimit(catalogModel, modelsDevLookup);
+  if (limit === void 0) {
+    logger.warn(
+      `limit metadata unavailable for ${slug} \u2014 no context/output ceiling will be enforced until added`
+    );
+  } else {
+    meta.limit = limit;
+  }
+  if (catalogModel?.variants !== void 0) meta.variants = catalogModel.variants;
+  const cost = resolveCost(catalogModel, modelsDevLookup);
   if (cost === void 0) {
     logger.warn(
-      `cost metadata unavailable for ${slug2} \u2014 reported cost will be $0 until added`
+      `cost metadata unavailable for ${slug} \u2014 reported cost will be $0 until added`
     );
     return meta;
   }
@@ -1095,11 +873,11 @@ function swapLast(value, from, to) {
   const index = value.lastIndexOf(from);
   return index === -1 ? value : `${value.slice(0, index)}${to}${value.slice(index + 1)}`;
 }
-function probeCandidates(slug2) {
-  const sep = slug2.indexOf("/");
-  if (sep <= 0 || sep >= slug2.length - 1) return [];
-  const vendor = slug2.slice(0, sep);
-  const model = slug2.slice(sep + 1);
+function probeCandidates(slug) {
+  const sep = slug.indexOf("/");
+  if (sep <= 0 || sep >= slug.length - 1) return [];
+  const vendor = slug.slice(0, sep);
+  const model = slug.slice(sep + 1);
   const vendors = [vendor];
   const alias = VENDOR_ALIASES[vendor];
   if (alias !== void 0 && alias !== vendor) vendors.push(alias);
@@ -1150,8 +928,8 @@ function buildLookup(model) {
   }
   return result;
 }
-function lookupSlug(data, slug2) {
-  for (const [providerKey, modelKey] of probeCandidates(slug2)) {
+function lookupSlug(data, slug) {
+  for (const [providerKey, modelKey] of probeCandidates(slug)) {
     const provider = data[providerKey];
     if (!isRecord6(provider) || !isRecord6(provider.models)) continue;
     const model = provider.models[modelKey];
@@ -1182,7 +960,7 @@ function writeCache(cachePath, envelope) {
   }
 }
 function makeSource(source, data) {
-  return { source, lookup: (slug2) => lookupSlug(data, slug2) };
+  return { source, lookup: (slug) => lookupSlug(data, slug) };
 }
 async function loadModelsDev(options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -1208,65 +986,16 @@ async function loadModelsDev(options = {}) {
   return { source: null, lookup: () => void 0 };
 }
 
-// src/config/build-alias-targets.ts
-var SEED_ALIAS_TARGETS = Object.fromEntries(
-  SEED.flatMap(
-    (entry) => entry.aliasOf === void 0 ? [] : [[entry.slug, entry.aliasOf]]
-  )
-);
-function buildAliasTargets(catalog) {
-  const targets = { ...SEED_ALIAS_TARGETS };
-  if (catalog.source === "seed") return targets;
-  for (const entry of SEED) {
-    if (entry.aliasOf === void 0) continue;
-    const aliasSlug = entry.slug;
-    const canonicalSlug = entry.aliasOf;
-    const aliasPresent = catalog.models[aliasSlug] !== void 0;
-    const canonicalPresent = catalog.models[canonicalSlug] !== void 0;
-    if (aliasPresent && !canonicalPresent) {
-      targets[canonicalSlug] = aliasSlug;
-      delete targets[aliasSlug];
-    } else if (aliasPresent && canonicalPresent) {
-      delete targets[aliasSlug];
-      delete targets[canonicalSlug];
-    }
-  }
-  return targets;
-}
-
 // src/config/enrich-catalog.ts
-function enrichOne(slug2, catalogModel, modelsDev, env) {
+function enrichOne(slug, catalogModel, modelsDev, env) {
   const sources = { modelsDev, env };
   if (catalogModel !== void 0) sources.catalogModel = catalogModel;
-  return enrichModel(slug2, sources);
+  return enrichModel(slug, sources);
 }
 function enrichCatalog(catalog, modelsDev, env) {
   const enriched = {};
-  for (const slug2 of Object.keys(catalog.models)) {
-    enriched[slug2] = enrichOne(slug2, catalog.models[slug2], modelsDev, env);
-  }
-  for (const entry of SEED) {
-    if (entry.aliasOf === void 0) continue;
-    const aliasSlug = entry.slug;
-    const canonicalSlug = entry.aliasOf;
-    const aliasPresent = enriched[aliasSlug] !== void 0;
-    const canonicalPresent = enriched[canonicalSlug] !== void 0;
-    if (aliasPresent === canonicalPresent) continue;
-    if (canonicalPresent) {
-      enriched[aliasSlug] = enrichOne(
-        aliasSlug,
-        catalog.models[canonicalSlug],
-        modelsDev,
-        env
-      );
-    } else {
-      enriched[canonicalSlug] = enrichOne(
-        canonicalSlug,
-        catalog.models[aliasSlug],
-        modelsDev,
-        env
-      );
-    }
+  for (const slug of Object.keys(catalog.models)) {
+    enriched[slug] = enrichOne(slug, catalog.models[slug], modelsDev, env);
   }
   return enriched;
 }
@@ -1475,6 +1204,26 @@ function findMissingRefs(cfg, refs) {
   return [...byRef.values()].sort((a, b) => a.ref.localeCompare(b.ref));
 }
 
+// src/config/inject-aliased.ts
+function deepClone(value) {
+  if (Array.isArray(value)) return value.map((item) => deepClone(item));
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, field]) => [key, deepClone(field)])
+    );
+  }
+  return value;
+}
+function injectAliased(cfg, missing, servedKey) {
+  const models = cfg.provider?.[missing.providerId]?.models;
+  if (models === void 0) return;
+  const served = models[servedKey];
+  if (typeof served !== "object" || served === null) return;
+  const entry = deepClone(served);
+  entry.id = servedKey;
+  models[missing.modelKey] = entry;
+}
+
 // src/config/inject-stubs.ts
 function injectStubs(cfg, missing) {
   if (cfg.provider === void 0) cfg.provider = {};
@@ -1487,6 +1236,40 @@ function injectStubs(cfg, missing) {
   }
 }
 
+// src/config/resolve-spelling.ts
+function isDigit(char) {
+  return char !== void 0 && char >= "0" && char <= "9";
+}
+function swapAtDigitBoundaries(tail, from, to) {
+  let out = "";
+  for (let i = 0; i < tail.length; i++) {
+    const char = tail[i];
+    out += char === from && isDigit(tail[i - 1]) && isDigit(tail[i + 1]) ? to : char;
+  }
+  return out;
+}
+function resolveSpelling(modelKey, availableKeys2) {
+  const sep = modelKey.indexOf("/");
+  const vendor = sep === -1 ? "" : modelKey.slice(0, sep);
+  const tail = sep === -1 ? modelKey : modelKey.slice(sep + 1);
+  const candidates = /* @__PURE__ */ new Set();
+  for (const swapped of [
+    swapAtDigitBoundaries(tail, ".", "-"),
+    swapAtDigitBoundaries(tail, "-", ".")
+  ]) {
+    if (swapped !== tail) candidates.add(swapped);
+  }
+  if (candidates.size === 0) return void 0;
+  const matches = [];
+  for (const key of availableKeys2) {
+    const keySep = key.indexOf("/");
+    const keyVendor = keySep === -1 ? "" : key.slice(0, keySep);
+    const keyTail = keySep === -1 ? key : key.slice(keySep + 1);
+    if (keyVendor === vendor && candidates.has(keyTail)) matches.push(key);
+  }
+  return matches.length === 1 ? matches[0] : void 0;
+}
+
 // src/config/validation-error.ts
 var Route33ValidationError = class extends Error {
   missingRefs;
@@ -1510,9 +1293,25 @@ function validateRefs(cfg, options = {}) {
   const refs = [...collectCfgRefs(cfg), ...collectFlavourRefs(env, cwd)];
   const missing = findMissingRefs(cfg, refs);
   if (missing.length === 0) return;
-  const details = describeMissing(cfg, missing);
-  const missingIds = missing.map((entry) => entry.ref);
-  if (missing.some((entry) => entry.legacyReplacement !== void 0)) {
+  const unresolved = [];
+  for (const entry of missing) {
+    const servedKey = entry.legacyReplacement === void 0 ? resolveSpelling(
+      entry.modelKey,
+      Object.keys(cfg.provider?.[entry.providerId]?.models ?? {})
+    ) : void 0;
+    if (servedKey === void 0) {
+      unresolved.push(entry);
+      continue;
+    }
+    injectAliased(cfg, entry, servedKey);
+    logger.info(
+      `${entry.ref} resolved to the served spelling "${entry.providerId}/${servedKey}" via dot\u2194dash tolerance \u2014 injected an aliased model entry routing to the served id`
+    );
+  }
+  if (unresolved.length === 0) return;
+  const details = describeMissing(cfg, unresolved);
+  const missingIds = unresolved.map((entry) => entry.ref);
+  if (unresolved.some((entry) => entry.legacyReplacement !== void 0)) {
     throw new Route33ValidationError(details, missingIds);
   }
   if (env[ENV_STRICT] === "0") {
@@ -1521,14 +1320,21 @@ function validateRefs(cfg, options = {}) {
 
 (${ENV_STRICT}=0 \u2014 continuing with name-only stub entries)`
     );
-    injectStubs(cfg, missing);
+    injectStubs(cfg, unresolved);
     return;
   }
   if (options.keyResolved === false) {
     logger.warn(
-      `no route_33 API key resolved \u2014 catalog is seed-only; ${missing.length} referenced model(s) are unavailable until a key is configured: ${missingIds.join(", ")}. Enter a key via the project-key prompt, \`opencode auth login\`, ${ENV_API_KEY}, or a provider.route_33.options.apiKey literal, then restart. (Continuing with name-only stub entries.)`
+      `no route_33 API key resolved \u2014 no model catalog available; ${unresolved.length} referenced model(s) are unavailable until a key is configured: ${missingIds.join(", ")}. Enter a key via the project-key prompt, \`opencode auth login\`, ${ENV_API_KEY}, or a provider.route_33.options.apiKey literal, then restart. (Continuing with name-only stub entries.)`
     );
-    injectStubs(cfg, missing);
+    injectStubs(cfg, unresolved);
+    return;
+  }
+  if (options.catalogAvailable === false) {
+    logger.warn(
+      `route33 model catalog unavailable \u2014 ${unresolved.length} referenced model(s) could not be validated against the key-scoped catalog: ${missingIds.join(", ")}. Restore gateway connectivity (a warm cache is reused automatically) or declare the model explicitly under "provider" in opencode.jsonc, then restart. (Continuing with name-only stub entries.)`
+    );
+    injectStubs(cfg, unresolved);
     return;
   }
   throw new Route33ValidationError(`${details}
@@ -1546,16 +1352,17 @@ function createConfigHook(options = {}) {
   const fetchImpl = options.fetchImpl;
   return async (cfg) => {
     let key;
+    let catalogAvailable = false;
     try {
       key = resolveKey(cfg, env, cwd);
       const baseURL = resolveBaseUrl(cfg, env, cwd);
       const catalog = await getCatalog({
         key,
         baseURL,
-        seed: SEED,
         env,
         fetchImpl
       });
+      catalogAvailable = catalog.source !== "none";
       const modelsDevOptions = {
         cacheDir: resolveCacheDir(env)
       };
@@ -1565,7 +1372,6 @@ function createConfigHook(options = {}) {
       const blocks = buildProviderBlocks(enriched, {
         apiKey: key,
         baseURL,
-        aliasTargets: buildAliasTargets(catalog),
         // Per-request resolution for the live-auth fetch: a prompt-entered
         // key applies to the very next request, no restart. The static
         // apiKey above stays the boot-time/catalog path.
@@ -1578,7 +1384,12 @@ function createConfigHook(options = {}) {
       );
     }
     try {
-      validateRefs(cfg, { env, cwd, keyResolved: key !== void 0 });
+      validateRefs(cfg, {
+        env,
+        cwd,
+        keyResolved: key !== void 0,
+        catalogAvailable
+      });
     } catch (error) {
       if (error instanceof Route33ValidationError) {
         logger.error(error.message);

package/docs/gateway-limits-variants-broadcast.md

@@ -0,0 +1,131 @@
+# Gateway limits and variants broadcast proposal
+
+**To:** R33 gateway team  
+**From:** opencode-route33 plugin maintainers  
+**Date:** 2026-08-10  
+**Subject:** Embedding per-model limits and variants in `GET /v1/models`
+
+## Problem
+
+This document is the limits and variants sibling of the [gateway pricing broadcast proposal](./gateway-pricing-proposal.md) from 2026-07-07. That contract shipped and proved that extra JSON fields on the standard OpenAI-compatible `/v1/models` response do not break clients.
+
+The opencode-route33 plugin previously kept a static seed catalog with hardcoded `context_window`, `max_output_tokens`, capability flags, and variant definitions. That file has been deleted. The gateway already persists `context_window` and `max_output_tokens` on `canonical_models`, and the catalog now needs to treat variants as platform-curated data (for example, `kimi-k3`'s `max` variant that sets `reasoningEffort: "max"`). Without a broadcast contract, plugin consumers fall back to stale seed data or fabricated defaults, which violates the never-accept-loss principle for model metadata.
+
+This creates three gaps:
+
+1. **Stale or fabricated limits.** The plugin has no source of truth for token ceilings once the seed catalog is gone.
+2. **Variants out of sync.** Model-specific parameter variants (max reasoning effort, output style presets, and so on) must live with the curated catalog, not in a plugin-side JSON file.
+3. **New-model lag.** A model that appears in the gateway catalog without published limit/variant metadata is treated as a lossy fallback.
+
+## Recommendation
+
+Extend each entry of the existing `GET /v1/models` response with two new optional fields:
+
+- `limits`: `{ "context": number, "output": number }`, present only when both values are positive integers.
+- `variants`: `Record<string, Record<string, unknown>>`, passed through verbatim from the platform's curated catalog.
+
+Existing unchanged fields (`id`, `object`, `created`, `owned_by`, plus optional `display_name`, `pricing`, `capabilities`, and `endpoints`) remain unchanged. Extra JSON fields still do not break OpenAI-compatible clients, so the catalog stays one round trip and atomically consistent.
+
+### Concrete JSON example
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "anthropic/claude-opus-4-8",
+      "object": "model",
+      "created": 1767225600,
+      "owned_by": "anthropic",
+      "display_name": "Claude Opus 4.8",
+      "pricing": {
+        "input": 5,
+        "output": 25,
+        "cache_read": 0.5,
+        "cache_write": 6.25
+      },
+      "capabilities": {
+        "modality": "text",
+        "context_tier": "large",
+        "tool_support": true,
+        "structured_output": true,
+        "generation_class": "chat",
+        "reasoning": true
+      },
+      "endpoints": ["chat", "messages"],
+      "limits": {
+        "context": 1000000,
+        "output": 128000
+      },
+      "variants": {
+        "max": {
+          "reasoningEffort": "max"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Field semantics
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | string | Canonical model identifier in `vendor/slug` form |
+| `object` | string | Always `"model"` |
+| `created` | integer | Unix epoch timestamp when the model was added to the catalog |
+| `owned_by` | string | Model vendor, matching the `vendor` portion of `id` |
+| `display_name` | string or omitted | Human-readable model label |
+| `pricing` | object or omitted | Pricing object as defined in the 2026-07-07 pricing broadcast |
+| `capabilities` | object or omitted | Structured capability flags |
+| `capabilities.modality` | string | Input/output modality, for example `"text"` |
+| `capabilities.context_tier` | string | Qualitative size class, for example `"large"` |
+| `capabilities.tool_support` | boolean | Native tool calling; mapped to opencode `tool_call` when `true` |
+| `capabilities.structured_output` | boolean | Native structured / JSON mode support |
+| `capabilities.generation_class` | string | Interaction style, for example `"chat"` |
+| `capabilities.reasoning` | boolean | Exposes reasoning or extended thinking; mapped to opencode `reasoning` when `true` |
+| `endpoints` | array of strings or omitted | Supported gateway endpoints, for example `["chat", "messages"]` |
+| `limits` | object or omitted | Per-model token limits |
+| `limits.context` | positive integer | Maximum context-window tokens |
+| `limits.output` | positive integer | Maximum completion tokens |
+| `variants` | object or omitted | Per-model parameter variants, a record of records |
+
+### Consumer parse rules
+
+The opencode-route33 plugin consumes this shape with the following rules:
+
+- `limits` is accepted only when both `context` and `output` are present and are positive integers. Partial or invalid `limits` objects are ignored. This mirrors the models.dev `normalizeLimit` rule.
+- `capabilities.reasoning` with the boolean value `true` maps to opencode's `reasoning` flag. Any non-boolean value is skipped.
+- `capabilities.tool_support` with the boolean value `true` maps to opencode's `tool_call` flag. Any non-boolean value is skipped.
+- `variants` is accepted only when it is a `Record<string, Record<string, unknown>>` and is passed through verbatim. Malformed variants are skipped.
+- Unknown or malformed fields are ignored. Parsing is never fatal.
+
+### Why embed limits and variants on `/v1/models`
+
+- **Single round trip.** The plugin fetches the catalog anyway, so embedding removes a second request for limit and variant metadata.
+- **No client breakage.** OpenAI-compatible consumers ignore unknown keys, so existing integrations keep working exactly as before.
+- **Curator is the source of truth.** The platform owns `canonical_models.context_window`, `canonical_models.max_output_tokens`, and the JSONB variants column, so the broadcast comes from the same place the gateway already trusts.
+- **No unit conversion or schema drift.** `limits.context` and `limits.output` are plain token counts, identical to opencode's internal limit schema, and `variants` is a passthrough of the platform JSONB value.
+
+## Curated-limits audit reference (models.dev parity, verified 2026-08-10)
+
+These entries were cross-checked against models.dev on 2026-08-10 and should be the values broadcast by the gateway:
+
+- Anthropic `claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5`: `1,000,000` context / `128,000` output
+- Anthropic `claude-haiku-4-5`: `200,000` context / `64,000` output
+- `moonshotai/kimi-k3`: `1,048,576` context / `131,072` output, with the `max` variant (`reasoningEffort: "max"`)
+- `minimax/minimax-m3`, `nvidia/nemotron-3-ultra`, `mistralai/mistral-medium-3.5`, and `qwen/qwen3.7-plus` keep their curated values (none of these appear in models.dev, so platform values stand).
+
+## Alternative: separate metadata endpoint
+
+If the gateway team prefers not to extend the standard `/v1/models` shape, a separate endpoint is acceptable:
+
+```
+GET /v1/models/metadata
+```
+
+It should return the same per-model fields and types documented above (`id`, `object`, `created`, `owned_by`, optional `display_name`, `pricing`, `capabilities`, `endpoints`, `limits`, and `variants`). The plugin would fetch this endpoint and merge the additional metadata with the catalog. The parse rules remain identical, only the HTTP envelope changes.
+
+## Secondary option (later)
+
+Publish route33 limit and variant metadata on models.dev via a community TOML PR. This is useful for non-gateway consumers, but it does not solve the key-scoped freshness problem or the single-round-trip goal. Recommended as a follow-up, not a substitute.

package/docs/gateway-pricing-proposal.md

@@ -0,0 +1,96 @@
+# Gateway pricing broadcast proposal
+
+**To:** R33 gateway team  
+**From:** opencode-route33 plugin maintainers  
+**Date:** 2026-07-07 (rev 2 — switched to the `input`/`output` per-1M vocabulary)  
+**Subject:** Embedding per-model pricing in `GET /v1/models`
+
+## Problem
+
+The route33.ai gateway exposes `GET /v1/models` for key-scoped catalog discovery, but the response carries no pricing metadata today. Downstream consumers (the opencode-route33 plugin, bench cost aggregation, and user-facing cost estimates) must source prices from an external registry (models.dev) and a hard-coded seed catalog. This creates three gaps:
+
+1. **Stale prices** — models.dev is community-maintained and can lag behind gateway rate changes.
+2. **Key-scoped pricing mismatch** — the gateway may offer tiered or negotiated rates per key; a global registry cannot express that.
+3. **New-model lag** — a model that appears in the gateway catalog but not in models.dev reports $0 cost until someone manually adds it to the seed.
+
+## Recommendation
+
+Embed a `pricing` object inside each entry of the existing `GET /v1/models` response, using the models.dev vocabulary: `input`, `output`, `cache_read`, `cache_write` as **numeric USD per 1M tokens**. Extra JSON fields do not break OpenAI-compatible clients, and key-scoped pricing rides the same key-scoped catalog response (one round trip, atomic catalog-plus-pricing consistency).
+
+### Concrete JSON example
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "openai/gpt-5.5",
+      "object": "model",
+      "created": 1751234567,
+      "owned_by": "openai",
+      "pricing": {
+        "input": 5.0,
+        "output": 30.0,
+        "cache_read": 0.5,
+        "cache_write": 1.0
+      }
+    },
+    {
+      "id": "anthropic/claude-opus-4-8",
+      "object": "model",
+      "created": 1751234568,
+      "owned_by": "anthropic",
+      "pricing": {
+        "input": 5.0,
+        "output": 25.0,
+        "cache_read": 0.5,
+        "cache_write": 6.25
+      }
+    }
+  ]
+}
+```
+
+**Field semantics** (numeric USD **per 1M tokens**):
+
+| Field         | Meaning           |
+| ------------- | ----------------- |
+| `input`       | Input token rate  |
+| `output`      | Output token rate |
+| `cache_read`  | Cache read rate   |
+| `cache_write` | Cache write rate  |
+
+All values are JSON numbers representing the cost of **one million tokens** in USD. `input` and `output` are required for a pricing entry to be consumed; the cache fields are optional.
+
+### Why `input`/`output` per-1M numbers
+
+- **Terminology match** — `input`/`output` is route33's own token vocabulary, and the modern industry direction (OpenAI's Responses API and Anthropic's Messages API both report `input_tokens`/`output_tokens`).
+- **Consumer match** — this is byte-identical to opencode's native cost schema and the models.dev registry vocabulary, so the opencode-route33 plugin passes values through with **zero unit conversion**.
+- **Human-scale numbers** — `5.0` per 1M reads and reviews better than `"0.000005"` per token, and sidesteps the ecosystem trap of conflating per-token with per-1M values, which has caused real underpricing bugs in other provider plugins.
+
+### One vocabulary only (do not mix)
+
+The plugin also recognizes the OpenRouter vocabulary (`prompt`, `completion`, `input_cache_read`, `input_cache_write` as string USD **per token**) as an accepted alternative shape. **Pick exactly one vocabulary.** A payload mixing keys from both sets is ambiguous about units and is deliberately ignored by the plugin.
+
+### Alternative: byte-pure OpenAI surface
+
+If the gateway team prefers not to extend the standard `/v1/models` shape, a separate endpoint is acceptable:
+
+```
+GET /v1/models/pricing
+```
+
+With the **same vocabulary** (`input`, `output`, `cache_read`, `cache_write` as numeric USD-per-1M fields) and the same key-scoped semantics. The plugin would fetch this endpoint alongside the catalog and merge the pricing layer.
+
+## Zero plugin changes needed
+
+The opencode-route33 plugin already ships a **dual-shape pricing extractor** (decision D14) that is dormant today and will activate automatically the moment recognizable pricing fields appear:
+
+- **models.dev vocabulary** (numeric USD per 1M) → passed through unchanged. **(recommended)**
+- **OpenRouter vocabulary** (string USD per token) → converted `×1,000,000` to opencode's per-1M numbers.
+
+Adopting either the embedded or the separate-endpoint contract above requires **zero changes** to the plugin — the dormant path becomes active without a version bump.
+
+## Secondary option (later)
+
+Register route33 in models.dev via a community TOML PR. This is useful for non-gateway consumers, but it does not solve the key-scoped-pricing or stale-data problems. Recommended as a follow-up, not a substitute.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@route_33/opencode",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "description": "opencode provider plugin for the route33.ai AI gateway — key-scoped model discovery, cost/limit enrichment, auth, and the key-setup wizard.",
@@ -31,7 +31,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"