Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(routing): put a vendor's own dynamic subscription first in its band
Jack Rudenkoc327eb0c57f7
diff --git a/CLAUDE.md b/CLAUDE.mdindex a68ce125..7c18daec 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -61,7 +61,7 @@ negative case: if you are about to type one of those words, stop and use the lef| chat model | text model, LLM | text among its input modalities AND among its output modalities; other modalities on either side never exclude one (`in: [file,image,text]` is a chat model, `in: [audio]` is not) || type | shape, kind, variant (for a discriminator) | the field that says how to read the rest of an object: `pricing.type` is `flat`, `tiered`, `free` or `unavailable`. The catalog spelled it `shape` until the cutover on generation `g-20260921062451697-f490edba`; claudish reads `type` only, with no alias || route candidate | option, hop (before filtering), chain entry | one `(provider, wire id)` pair gathered for a model, BEFORE the credential and availability filters. A candidate is a proposal; a hop is what survived |-| tier | class, category, rank, level | a provider's routing class: `subscription`, `dynamic-subscription`, `native`, `gateway`, `fallback`. Ordering is by tier first, and only then by vendor and price |+| tier | class, category, rank, level | a provider's routing class: `subscription`, `dynamic-subscription`, `native`, `gateway`, `fallback`. Ordering is by tier first, and only then by vendor and price — except that the two subscription tiers count as one, so a vendor's own dynamic subscription leads another vendor's catalog subscription (`gk@` before `zengo@` for `grok-4.x`) || namespace claim | pattern match, native claim | a dynamic subscription becoming a candidate because its `nativeModelPatterns` match the name. It exists so the availability filter can ASK the account; it is never evidence that the account is served |**Providers and routing**diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.mdindex 0907d090..3057c60d 100644--- a/ai-docs/architecture/routing.md+++ b/ai-docs/architecture/routing.md@@ -108,9 +108,13 @@ steps, and only the first changed:to, including by the fallback hop. `[]` is a match: the user said "no route".2. **Otherwise gather from the catalog** — `gatherRouteCandidates` (`route-candidates.ts`)reads every `aggregators[]` connection the cloud models catalog publishes for the model- and orders them: tier (`subscription` → `dynamic-subscription` → `native` → `gateway`),- then the model's own vendor, then cheapest (unknown price last), then larger context- window, then provider name.+ and orders them: band (both subscription tiers → `native` → `gateway`), then the+ model's own vendor, then tier (`subscription` before `dynamic-subscription`), then+ cheapest (unknown price last), then larger context window, then provider name. The+ shared band exists so a vendor's own dynamic subscription leads: before 2026-09-24+ tier came first and `grok-4.6`/`grok-4.7` went Zen Go → Grok Build → xAI; now Grok+ Build (xAI's own) leads. The strict route gate showed those two chains and nothing+ else move (generation `g-20260923145315478-d7a326bd`).3. **Append the fallback hop** (below).4. Credential filter (unchanged).5. Availability filter — only a POSITIVE "not-served" removes anything, and it asks eachdiff --git a/packages/cli/src/providers/route-candidates.test.ts b/packages/cli/src/providers/route-candidates.test.tsindex e2915e17..7371ddfd 100644--- a/packages/cli/src/providers/route-candidates.test.ts+++ b/packages/cli/src/providers/route-candidates.test.ts@@ -330,6 +330,119 @@ describe("catalog route candidate gathering and order", () => {});});+describe("the subscription band", () => {+ test("a vendor's own dynamic subscription leads another vendor's catalog subscription", () => {+ const candidate = gatheredCandidate("kimi-k3", "kimi");+ const catalog: RouteCandidate = {+ ...candidate,+ provider: "opencode-zen-go",+ wireId: "kimi-k3",+ tier: "subscription",+ isVendorOwn: false,+ };+ const dynamic: RouteCandidate = {+ ...candidate,+ provider: "grok-subscription",+ wireId: "kimi-k3",+ tier: "dynamic-subscription",+ isVendorOwn: true,+ };++ for (const pair of [+ [catalog, dynamic],+ [dynamic, catalog],+ ]) {+ expect(pair.sort(compareRouteCandidates).map(({ provider }) => provider)).toEqual([+ "grok-subscription",+ "opencode-zen-go",+ ]);+ }+ });++ describe("inside the band a catalog subscription leads a dynamic one when the vendor rule ties", () => {+ for (const isVendorOwn of [true, false]) {+ test(`both isVendorOwn = ${isVendorOwn}`, () => {+ const candidate = gatheredCandidate("kimi-k3", "kimi");+ const dynamic: RouteCandidate = {+ ...candidate,+ provider: "antigravity",+ wireId: "kimi-k3",+ tier: "dynamic-subscription",+ isVendorOwn,+ };+ const catalog: RouteCandidate = {+ ...candidate,+ provider: "opencode-zen-go",+ wireId: "kimi-k3",+ tier: "subscription",+ isVendorOwn,+ };++ for (const pair of [+ [dynamic, catalog],+ [catalog, dynamic],+ ]) {+ expect(pair.sort(compareRouteCandidates).map(({ provider }) => provider)).toEqual([+ "opencode-zen-go",+ "antigravity",+ ]);+ }+ });+ }+ });++ test("the vendor rule never crosses a band", () => {+ const candidate = gatheredCandidate("kimi-k3", "kimi");+ const vendorNative: RouteCandidate = {+ ...candidate,+ provider: "xai-native",+ wireId: "kimi-k3",+ tier: "native",+ isVendorOwn: true,+ };+ const dynamic: RouteCandidate = {+ ...candidate,+ provider: "zz-dynamic",+ wireId: "kimi-k3",+ tier: "dynamic-subscription",+ isVendorOwn: false,+ };+ const vendorGateway: RouteCandidate = {+ ...candidate,+ provider: "aa-gateway",+ wireId: "kimi-k3",+ tier: "gateway",+ isVendorOwn: true,+ };+ const native: RouteCandidate = {+ ...candidate,+ provider: "zz-native",+ wireId: "kimi-k3",+ tier: "native",+ isVendorOwn: false,+ };++ for (const pair of [+ [vendorNative, dynamic],+ [dynamic, vendorNative],+ ]) {+ expect(pair.sort(compareRouteCandidates).map(({ provider }) => provider)).toEqual([+ "zz-dynamic",+ "xai-native",+ ]);+ }+ for (const pair of [+ [vendorGateway, native],+ [native, vendorGateway],+ ]) {+ expect(pair.sort(compareRouteCandidates).map(({ provider }) => provider)).toEqual([+ "zz-native",+ "aa-gateway",+ ]);+ }+ });+});+describe("namespace claims and availability", () => {test("a namespace claim is gathered but the dynamic models catalog may remove it", async () => {const gathered = gatherRouteCandidates("gemini-3.8-flash", cachePath);diff --git a/packages/cli/src/providers/route-candidates.ts b/packages/cli/src/providers/route-candidates.tsindex 9f6f728f..0c95ee84 100644--- a/packages/cli/src/providers/route-candidates.ts+++ b/packages/cli/src/providers/route-candidates.ts@@ -51,12 +51,19 @@* this and nothing else:** user rules (elsewhere, verbatim, never merged with any of this)- * then tier: subscription → dynamic-subscription → native → gateway → fallback- * within a tier: the model's own vendor first+ * then band: subscription (both subscription tiers) → native → gateway → fallback+ * within a band: the model's own vendor first+ * then tier: subscription before dynamic-subscription* then cheapest by catalog price (unknown last)* then larger context window* then provider name, ascending, for determinism*+ * The two subscription tiers share one band so that a vendor's OWN dynamic+ * subscription goes first: `grok-4.x` goes Grok Build → OpenCode Zen Go → xAI.+ * With tier first, Zen Go's catalog-published plan led Grok Build, xAI's own,+ * on 3 of 1,143 catalog models (generation g-20260923145315478-d7a326bd); the+ * project owner decided the vendor's own plan leads (2026-09-24).+ ** No local preference list, and NO LOCAL STATE. A spent subscription limit is* never remembered: the request moves to the next hop, which is the existing* chain's job. A module that remembered would answer differently on two@@ -134,6 +141,11 @@ const TIER_RANK: Record<RouteTier, number> = {fallback: 4,};+/** A tier's band: both subscription tiers share the first; every other tier is its own. */+function bandRank(tier: RouteTier): number {+ return tier === "dynamic-subscription" ? TIER_RANK.subscription : TIER_RANK[tier];+}+/** `routeId/routeProfileId`, the spelling the backend contract and the reports use. */function routeLabel(route: CatalogRouteBinding | undefined): string {return route ? `${route.routeId}/${route.routeProfileId}` : "(no route)";@@ -352,12 +364,19 @@ function gatherFromNamespaceClaims(* backend re-publish with nothing in claudish having changed.*/export function compareRouteCandidates(a: RouteCandidate, b: RouteCandidate): number {- const byTier = TIER_RANK[a.tier] - TIER_RANK[b.tier];- if (byTier !== 0) return byTier;+ const byBand = bandRank(a.tier) - bandRank(b.tier);+ if (byBand !== 0) return byBand;- // The vendor's own route, before anyone reselling it.+ // The vendor's own route, before anyone reselling it — across both+ // subscription tiers, which is the only place a band holds two.if (a.isVendorOwn !== b.isVendorOwn) return a.isVendorOwn ? -1 : 1;+ // Inside the subscription band, a catalog-published plan before a dynamic+ // one: its membership is evidence, where a namespace claim is only a question+ // the availability filter asks the account.+ const byTier = TIER_RANK[a.tier] - TIER_RANK[b.tier];+ if (byTier !== 0) return byTier;+const byPrice = compareByConnectionPrice(a.price, b.price);if (byPrice !== 0) return byPrice;