Skip to content

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.md
index 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.md
index 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 each
diff --git a/packages/cli/src/providers/route-candidates.test.ts b/packages/cli/src/providers/route-candidates.test.ts
index 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.ts
index 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;