Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(catalog): consume the repaired models-index contract

Jack Rudenkod50ae6a24b24
diff --git a/packages/cli/src/adapters/base-api-format.ts b/packages/cli/src/adapters/base-api-format.ts
index f91125b7..43a63df3 100644
--- a/packages/cli/src/adapters/base-api-format.ts
+++ b/packages/cli/src/adapters/base-api-format.ts
@@ -13,7 +13,12 @@ import { getModelPricing } from "../handlers/shared/remote-provider-types.js";
import { log } from "../logger.js";
import type { StreamFormat } from "../providers/transport/types.js";
import type { APIFormat } from "./api-format.js";
-import { type ReasoningCapability, lookupModel, lookupModelReasoning } from "./model-catalog.js";
+import {
+ type ReasoningCapability,
+ lookupModel,
+ lookupModelReasoning,
+ lookupModelReasoningStatus,
+} from "./model-catalog.js";
import type { ModelDialect } from "./model-dialect.js";
import { rejectedOptionalParams } from "./optional-param-rejection.js";
import {
@@ -104,6 +109,78 @@ const NON_ANTHROPIC_REASONING_FIELDS = [
"thinking_budget",
] as const;
+/**
+ * Smallest reasoning budget a provider will accept.
+ *
+ * Anthropic's Messages API documents `budget_tokens >= 1024`, and the
+ * Anthropic-compatible endpoints claudish speaks to inherit it. Below this a
+ * budget is not "small", it is invalid, so the correct move is to stop
+ * expressing depth as a budget rather than to send a smaller number.
+ */
+export const MIN_THINKING_BUDGET = 1024;
+
+/**
+ * Output tokens reserved for the answer itself when a budget is clamped.
+ *
+ * A budget equal to the ceiling is rejected outright (`max_completion_tokens
+ * [32000] must be greater than thinking_budget [38912]` is the same rule seen
+ * from the other side), and a budget one token under it leaves a model that has
+ * thought and cannot speak. Reserving a real slice keeps a clamped request
+ * useful rather than merely legal.
+ */
+export const ANSWER_TOKEN_RESERVE = 1024;
+
+/**
+ * The output ceiling a reasoning budget must fit under.
+ *
+ * Read from the ORIGINAL Claude-format request first, because `max_tokens` is
+ * the field every wire derives its own ceiling from and the only one guaranteed
+ * to be present before the payload is built. The payload is consulted second,
+ * under all three names the wires use, so a dialect that runs after its
+ * converter still sees the number actually being sent.
+ *
+ * Deliberately NOT the catalog's `maxOutputTokens`: the provider validates the
+ * budget against the ceiling in the request, so that is the number that decides
+ * whether the pair is legal.
+ */
+export function outputCeilingOf(originalRequest: any, payload?: any): number | undefined {
+ const candidates = [
+ originalRequest?.max_tokens,
+ payload?.max_tokens,
+ payload?.max_completion_tokens,
+ payload?.max_output_tokens,
+ ];
+ for (const value of candidates) {
+ if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+ }
+ return undefined;
+}
+
+/**
+ * Fit a reasoning budget under an output ceiling.
+ *
+ * Returns:
+ * - the budget unchanged when it already fits,
+ * - a smaller budget when the ceiling requires one,
+ * - `undefined` when there is no budget to send in the first place (effort
+ * `max` omits it so the model uses its own maximum), or when no ceiling is
+ * known and the caller's number therefore stands,
+ * - `"no-room"` when the ceiling cannot hold a legal budget AND leave room to
+ * answer. That is a distinct outcome from "no budget": the caller must stop
+ * expressing depth as a budget, not send the request without one.
+ */
+export function clampThinkingBudget(
+ budget: number | undefined,
+ ceiling: number | undefined
+): number | undefined | "no-room" {
+ if (budget === undefined) return undefined;
+ if (ceiling === undefined) return budget;
+
+ const allowed = ceiling - ANSWER_TOKEN_RESERVE;
+ if (allowed < MIN_THINKING_BUDGET) return "no-room";
+ return Math.min(budget, allowed);
+}
+
export interface AdapterResult {
/** Cleaned text content (with XML/special formats removed) */
cleanedText: string;
@@ -471,9 +548,42 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
* vocabulary (MiniMax answers `adaptive`, not `enabled`).
*/
protected applyAnthropicWireReasoning(request: any, originalRequest: any): any {
+ // ── Truthful unknown ────────────────────────────────────────────────────
+ //
+ // Checked FIRST, before the request's own effort signal, because an unknown
+ // control makes every downstream branch a guess regardless of what was
+ // asked for.
+ //
+ // There is no generic fallback here any more. The one that used to sit at
+ // the bottom of this method emitted the effort ladder's token budget for any
+ // model the catalog did not describe, which is how `qwen3.8-max` was sent
+ // `budget_tokens: 38912` against a `max_tokens` of 32000 and rejected with
+ // "max_completion_tokens [32000] must be greater than thinking_budget
+ // [38912]" — a 400 before any inference, on a model the provider serves
+ // perfectly well.
+ //
+ // A guessed knob is not a safe default. It is a claim about a wire contract
+ // we have not read, and the failure lands on the newest models, which are
+ // exactly the ones the catalog has not caught up with yet.
+ //
+ // `supportsThinking` is deliberately NOT consulted as a substitute. The
+ // catalog publishes that flag even while reporting the status unknown
+ // (`query-handler.ts` sets `reasoningStatus: "unknown"` and can still emit
+ // `supportsThinking` from coarse capability data), so it is present exactly
+ // where it proves nothing about the knob.
+ const status = this.lookupReasoningStatus();
+ if (status !== "known") {
+ log(
+ `[${this.getName()}] ${this.modelId} reasoning control ${status === "unknown" ? "unknown" : "absent from the catalog"} -> no reasoning parameter emitted`
+ );
+ return request;
+ }
+
const reasoning = this.lookupReasoningCapability();
// Catalog is explicit that the model cannot reason — never switch it on.
+ // This is a KNOWN answer, and the opposite instruction to the unknown case
+ // above: there we say nothing, here we say off.
if (reasoning?.supported === false) {
request.thinking = { type: "disabled" };
log(`[${this.getName()}] ${this.modelId} reports no reasoning support -> thinking: disabled`);
@@ -486,58 +596,127 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
if (!effort) return request;
if (effort === "none" || effort === "minimal") {
+ // `mandatory` means the model cannot run with reasoning off, so a
+ // `disabled` here is a request the provider must reject. Honour the
+ // intent as far as the model allows: the lowest level it advertises.
+ if (reasoning?.mandatory) {
+ return this.enableAnthropicEffort(request, effort, reasoning, "mandatory reasoning");
+ }
request.thinking = { type: "disabled" };
log(`[${this.getName()}] effort ${effort} -> thinking.type: disabled for ${this.modelId}`);
return request;
}
- // A token budget is only legitimate where the catalog says the model takes
- // one (`control: "budget"` / `supportsBudgetTokens`).
- if (reasoning && (reasoning.control === "budget" || reasoning.supportsBudgetTokens)) {
- return this.enableAnthropicThinkingWithBudget(request, effort, "catalog: budget-controlled");
+ // ── Control-driven dispatch ─────────────────────────────────────────────
+ //
+ // `control` is authoritative and is read BEFORE `supportsBudgetTokens`.
+ // That order is the rule: a model may advertise discrete levels AND accept a
+ // budget, and in that case the levels are the control the vendor documents.
+ // The previous code tested `control === "budget" || supportsBudgetTokens`,
+ // so an optional budget capability silently overrode an effort control and
+ // sent a token count to a model whose knob is a level.
+ const control = reasoning?.control;
+ const advertisesEfforts = (reasoning?.efforts?.length ?? 0) > 0;
+
+ if (control === "effort" || (control === undefined && advertisesEfforts)) {
+ return this.enableAnthropicEffort(request, effort, reasoning, "catalog: effort-controlled");
}
- // A discrete level: clamp into what this model actually advertises.
- const advertised = reasoning?.efforts?.length ? reasoning : undefined;
- if (advertised) {
- const level = this.clampToAdvertisedEffort(effort, advertised);
- request.thinking = { type: "enabled" };
- if (level) {
- request.output_config = { ...(request.output_config ?? {}), effort: level };
- }
- log(
- `[${this.getName()}] effort ${effort} -> thinking: enabled, output_config.effort: ${level ?? "(none advertised)"} for ${this.modelId} (advertised: ${advertised.efforts?.join("/")})`
- );
- return request;
+ if (control === "budget" || (control === undefined && reasoning?.supportsBudgetTokens)) {
+ return this.enableAnthropicBudget(request, effort, originalRequest, reasoning);
+ }
+
+ // `toggle`, `adaptive`, or a control this build does not recognise:
+ // reasoning is on/off only. Emit the switch and no depth.
+ request.thinking = { type: "enabled" };
+ this.stripAnthropicEffortField(request);
+ log(
+ `[${this.getName()}] effort ${effort} -> thinking: enabled (no depth knob; catalog control=${control ?? "unspecified"}) for ${this.modelId}`
+ );
+ return request;
+ }
+
+ /**
+ * Emit a discrete level, clamped into what the model advertises.
+ *
+ * Never also emits a budget: on this wire `output_config.effort` and
+ * `thinking.budget_tokens` are two spellings of the same intent, and sending
+ * both is a self-contradicting payload.
+ */
+ private enableAnthropicEffort(
+ request: any,
+ effort: EffortLevel,
+ reasoning: ReasoningCapability | undefined,
+ why: string
+ ): any {
+ const level = reasoning ? this.clampToAdvertisedEffort(effort, reasoning) : undefined;
+ request.thinking = { type: "enabled" };
+ if (level) {
+ request.output_config = { ...(request.output_config ?? {}), effort: level };
}
+ log(
+ `[${this.getName()}] effort ${effort} -> thinking: enabled, output_config.effort: ${level ?? "(none advertised)"} for ${this.modelId} (${why}; advertised: ${reasoning?.efforts?.join("/") ?? "none"})`
+ );
+ return request;
+ }
- // `control: "toggle"` (or an unrecognized control with no level list):
- // reasoning is on/off only. Emit the switch and nothing else.
- if (reasoning) {
- request.thinking = { type: "enabled" };
+ /**
+ * Emit a token budget, clamped to fit under the request's output ceiling.
+ *
+ * The ceiling is the REQUEST's `max_tokens`, not the catalog's
+ * `maxOutputTokens`, because `max_tokens` is the number the provider
+ * validates the budget against — it is the one we are about to send.
+ */
+ private enableAnthropicBudget(
+ request: any,
+ effort: EffortLevel,
+ originalRequest: any,
+ reasoning: ReasoningCapability | undefined
+ ): any {
+ const requested = this.effortToThinkingTokenBudget(effort);
+ const ceiling = outputCeilingOf(originalRequest, request);
+ const budget = clampThinkingBudget(requested, ceiling);
+
+ if (budget === "no-room") {
+ // The ceiling cannot hold a legal budget AND leave room for an answer.
+ // A mandatory-reasoning model still has to reason, so send the plain
+ // on-switch and let the provider pick its own depth; anything else is a
+ // payload it must reject.
+ if (reasoning?.mandatory) {
+ request.thinking = { type: "enabled" };
+ } else {
+ request.thinking = { type: "disabled" };
+ }
+ this.stripAnthropicEffortField(request);
log(
- `[${this.getName()}] effort ${effort} -> thinking: enabled (no depth knob; catalog control=${reasoning.control ?? "unknown"}) for ${this.modelId}`
+ `[${this.getName()}] effort ${effort} -> budget ${requested ?? "(model max)"} does not fit under max_tokens ${ceiling}; sent thinking.type: ${request.thinking.type} for ${this.modelId}`
);
return request;
}
- // No catalog entry at all (cold cache, or a model newer than the catalog —
- // qwen3.8-max-preview is exactly this today). No information means keep the
- // generic behaviour rather than guess a narrower one.
- return this.enableAnthropicThinkingWithBudget(request, effort, "no catalog entry");
- }
-
- /** Enable Anthropic-wire thinking with the generic token-budget ladder. */
- private enableAnthropicThinkingWithBudget(request: any, effort: EffortLevel, why: string): any {
- const budget = this.effortToThinkingTokenBudget(effort);
request.thinking =
budget === undefined ? { type: "enabled" } : { type: "enabled", budget_tokens: budget };
+ // A budget and a level are mutually exclusive expressions of depth.
+ this.stripAnthropicEffortField(request);
log(
- `[${this.getName()}] effort ${effort} -> thinking: enabled, budget_tokens: ${budget ?? "(model max)"} for ${this.modelId} (${why})`
+ `[${this.getName()}] effort ${effort} -> thinking: enabled, budget_tokens: ${budget ?? "(model max)"}${
+ budget !== undefined && budget !== requested ? ` (clamped from ${requested} under max_tokens ${ceiling})` : ""
+ } for ${this.modelId} (catalog: budget-controlled)`
);
return request;
}
+ /**
+ * Remove `output_config.effort` from a payload that expresses depth another
+ * way, dropping the container when it is left empty.
+ */
+ private stripAnthropicEffortField(request: any): void {
+ if (!request?.output_config || typeof request.output_config !== "object") return;
+ if (request.output_config.effort === undefined) return;
+ delete request.output_config.effort;
+ if (Object.keys(request.output_config).length === 0) delete request.output_config;
+ }
+
/**
* Clamp a requested level into the set a model actually advertises.
*
@@ -628,6 +807,21 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
}
}
+ /**
+ * Whether the catalog KNOWS this model's reasoning control.
+ *
+ * Fail-soft to `undefined`, which callers must treat exactly like
+ * `"unknown"`: emit no reasoning parameter. A lookup that threw has told us
+ * nothing, and "nothing" must never become a guessed knob.
+ */
+ protected lookupReasoningStatus(): "known" | "unknown" | undefined {
+ try {
+ return lookupModelReasoningStatus(this.modelId);
+ } catch {
+ return undefined;
+ }
+ }
+
/**
* Effort → token budget (claudish convention), shared by DashScope's
* `thinking_budget` and Anthropic's `thinking.budget_tokens`. `max` omits the
diff --git a/packages/cli/src/adapters/catalog-contract-payload.test.ts b/packages/cli/src/adapters/catalog-contract-payload.test.ts
new file mode 100644
index 00000000..56a6c797
--- /dev/null
+++ b/packages/cli/src/adapters/catalog-contract-payload.test.ts
@@ -0,0 +1,312 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+ type CachedSubscriptionPlan,
+ type DiskCacheV2,
+ type ReasoningCapability,
+ type SlimModelEntry,
+ writeAllModelsCache,
+} from "../providers/all-models-cache.js";
+import { AnthropicAPIFormat } from "./anthropic-api-format.js";
+import {
+ ANSWER_TOKEN_RESERVE,
+ type BaseAPIFormat,
+ EFFORT_LEVELS,
+ type EffortLevel,
+ clampThinkingBudget,
+ outputCeilingOf,
+} from "./base-api-format.js";
+import { resolveModelDialect } from "./dialect-manager.js";
+import { lookupModelReasoning, lookupModelReasoningStatus } from "./model-catalog.js";
+
+let tempDir = "";
+let cachePath = "";
+
+interface GeneratedPayload {
+ model: string;
+ max_tokens: number;
+ thinking?: { type?: string; budget_tokens?: number };
+ output_config?: { effort?: string };
+ enable_thinking?: boolean;
+ thinking_budget?: number;
+}
+
+beforeEach(() => {
+ tempDir = mkdtempSync(join(tmpdir(), "claudish-catalog-payload-"));
+ cachePath = join(tempDir, "all-models.json");
+});
+
+afterEach(() => {
+ rmSync(tempDir, { recursive: true, force: true });
+ tempDir = "";
+ cachePath = "";
+});
+
+function writeCatalog(entries: SlimModelEntry[], plans: CachedSubscriptionPlan[] = []): void {
+ const cache: DiskCacheV2 = {
+ version: 2,
+ lastUpdated: "2030-01-01T00:00:00.000Z",
+ entries,
+ models: [],
+ plans,
+ };
+ writeAllModelsCache(cache, cachePath);
+}
+
+function entry(
+ modelId: string,
+ reasoningStatus: "known" | "unknown",
+ reasoning?: ReasoningCapability,
+ supportsThinking?: boolean
+): SlimModelEntry {
+ return {
+ modelId,
+ aliases: [],
+ sources: {},
+ reasoningStatus,
+ ...(reasoning ? { reasoning } : {}),
+ ...(supportsThinking !== undefined ? { supportsThinking } : {}),
+ };
+}
+
+/**
+ * BaseAPIFormat has no cachePath constructor seam. Shadow only the resolved
+ * instance's metadata readers so the production dialect logic reads this
+ * test's temp cache without a process-wide module mock or real-cache write.
+ */
+function useTempCatalog(dialect: BaseAPIFormat, modelId: string): void {
+ const withCatalogReaders = dialect as BaseAPIFormat & {
+ lookupReasoningCapability(): ReasoningCapability | undefined;
+ lookupReasoningStatus(): "known" | "unknown" | undefined;
+ };
+ withCatalogReaders.lookupReasoningCapability = () => lookupModelReasoning(modelId, cachePath);
+ withCatalogReaders.lookupReasoningStatus = () => lookupModelReasoningStatus(modelId, cachePath);
+}
+
+/** Exact production sequence from ComposedHandler steps 4 and 5. */
+function buildAnthropicPayload(
+ modelId: string,
+ effort: EffortLevel,
+ maxTokens = 32_000
+): GeneratedPayload {
+ const claudeRequest = {
+ model: "caller-model-is-replaced",
+ messages: [],
+ tools: [],
+ max_tokens: maxTokens,
+ output_config: { effort },
+ };
+ const converter = new AnthropicAPIFormat(modelId, "future-subscription-provider");
+ const messages = converter.convertMessages(claudeRequest);
+ const tools = converter.convertTools(claudeRequest);
+ const payload = converter.buildPayload(claudeRequest, messages, tools);
+ converter.prepareRequest(payload, claudeRequest);
+ const dialect = resolveModelDialect(modelId, converter.getStreamFormat());
+ useTempCatalog(dialect, modelId);
+ dialect.prepareRequest(payload, claudeRequest);
+ return payload;
+}
+
+/** Production path when Qwen's OpenAI-shaped dialect is also the converter. */
+function buildNativeQwenPayload(effort: EffortLevel, maxTokens: number): GeneratedPayload {
+ const modelId = "qwen4.2-nebula";
+ const claudeRequest = {
+ model: "caller-model-is-replaced",
+ messages: [],
+ tools: [],
+ max_tokens: maxTokens,
+ output_config: { effort },
+ };
+ const converter = resolveModelDialect(modelId);
+ expect(converter.getStreamFormat()).toBe("openai-sse");
+ const messages = converter.convertMessages(claudeRequest);
+ const tools = converter.convertTools(claudeRequest);
+ const payload = converter.buildPayload(claudeRequest, messages, tools);
+ converter.prepareRequest(payload, claudeRequest);
+ return payload;
+}
+
+function expectNoCompetingDepthKnobs(payload: GeneratedPayload): void {
+ expect(
+ payload.thinking?.budget_tokens !== undefined && payload.output_config?.effort !== undefined
+ ).toBe(false);
+}
+
+describe("catalog-driven Anthropic request payloads", () => {
+ test("unknown reasoning emits no knob at every effort, even with supportsThinking true", () => {
+ writeCatalog(
+ [entry("qwen3.8-max-preview", "unknown", undefined, true)],
+ [
+ {
+ id: "future-plan",
+ modelDescriptions: {
+ "qwen3.8-max": { status: "described", modelId: "qwen3.8-max-preview" },
+ },
+ },
+ ]
+ );
+
+ for (const effort of EFFORT_LEVELS) {
+ const payload = buildAnthropicPayload("qwen3.8-max", effort);
+ expect(payload.model).toBe("qwen3.8-max");
+ expect(payload.max_tokens).toBe(32_000);
+ expect(payload.thinking).toBeUndefined();
+ expect(payload.output_config?.effort).toBeUndefined();
+ expectNoCompetingDepthKnobs(payload);
+ }
+ });
+
+ test("uses canonical metadata without rewriting the inference wire id", () => {
+ writeCatalog(
+ [
+ entry("qwen3.8-flash-canonical", "known", {
+ supported: true,
+ control: "effort",
+ efforts: ["low", "high"],
+ }),
+ ],
+ [
+ {
+ id: "future-plan",
+ modelDescriptions: {
+ "qwen3.8-flash": {
+ status: "described",
+ modelId: "qwen3.8-flash-canonical",
+ },
+ },
+ },
+ ]
+ );
+
+ const payload = buildAnthropicPayload("qwen3.8-flash", "medium");
+
+ expect(payload.model).toBe("qwen3.8-flash");
+ expect(payload.thinking).toEqual({ type: "enabled" });
+ expect(payload.output_config?.effort).toBe("high");
+ expect(payload.thinking?.budget_tokens).toBeUndefined();
+ expectNoCompetingDepthKnobs(payload);
+ });
+
+ test("effort control clamps into the advertised set and never emits a budget", () => {
+ writeCatalog([
+ entry("orion-effort-2030", "known", {
+ supported: true,
+ control: "effort",
+ efforts: ["low", "high"],
+ }),
+ ]);
+
+ const payload = buildAnthropicPayload("orion-effort-2030", "medium");
+
+ expect(payload.thinking).toEqual({ type: "enabled" });
+ expect(payload.output_config?.effort).toBe("high");
+ expect(payload.thinking?.budget_tokens).toBeUndefined();
+ expectNoCompetingDepthKnobs(payload);
+ });
+
+ test("effort control remains authoritative when budget tokens are also supported", () => {
+ writeCatalog([
+ entry("orion-hybrid-2030", "known", {
+ supported: true,
+ control: "effort",
+ efforts: ["high", "max"],
+ supportsBudgetTokens: true,
+ }),
+ ]);
+
+ const payload = buildAnthropicPayload("orion-hybrid-2030", "xhigh");
+
+ expect(payload.thinking).toEqual({ type: "enabled" });
+ expect(payload.output_config?.effort).toBe("max");
+ expect(payload.thinking?.budget_tokens).toBeUndefined();
+ expectNoCompetingDepthKnobs(payload);
+ });
+
+ test("budget control never emits a budget at or above max_tokens", () => {
+ writeCatalog([
+ entry("orion-budget-2030", "known", {
+ supported: true,
+ control: "budget",
+ supportsBudgetTokens: true,
+ }),
+ ]);
+
+ for (const maxTokens of [4096, 8192, 32_000, 64_000]) {
+ for (const effort of EFFORT_LEVELS) {
+ const payload = buildAnthropicPayload("orion-budget-2030", effort, maxTokens);
+ const budget = payload.thinking?.budget_tokens;
+
+ expect(payload.max_tokens).toBe(maxTokens);
+ expect(budget === undefined || budget < payload.max_tokens).toBe(true);
+ expectNoCompetingDepthKnobs(payload);
+
+ if (["low", "medium", "high", "xhigh"].includes(effort)) {
+ expect(typeof budget).toBe("number");
+ expect(budget).toBeLessThan(payload.max_tokens);
+ } else {
+ expect(budget).toBeUndefined();
+ }
+ }
+ }
+ });
+
+ test("explicit unsupported reasoning disables thinking instead of behaving as unknown", () => {
+ writeCatalog([
+ entry("orion-no-reasoning-2030", "known", {
+ supported: false,
+ control: "none",
+ }),
+ ]);
+
+ const payload = buildAnthropicPayload("orion-no-reasoning-2030", "max");
+
+ expect(payload.thinking).toEqual({ type: "disabled" });
+ expect(payload.output_config?.effort).toBeUndefined();
+ expectNoCompetingDepthKnobs(payload);
+ });
+});
+
+describe("reasoning budget ceiling helpers", () => {
+ test("outputCeilingOf prefers the original request and supports every payload spelling", () => {
+ expect(outputCeilingOf({ max_tokens: 4096 }, { max_completion_tokens: 8192 })).toBe(4096);
+ expect(outputCeilingOf({}, { max_tokens: 8192 })).toBe(8192);
+ expect(outputCeilingOf({}, { max_completion_tokens: 32_000 })).toBe(32_000);
+ expect(outputCeilingOf({}, { max_output_tokens: 64_000 })).toBe(64_000);
+ expect(outputCeilingOf({ max_tokens: 0 }, { max_tokens: Number.NaN })).toBeUndefined();
+ });
+
+ test("clampThinkingBudget preserves valid values, clamps oversized ones, and reports no-room", () => {
+ expect(clampThinkingBudget(undefined, 4096)).toBeUndefined();
+ expect(clampThinkingBudget(2048, undefined)).toBe(2048);
+ expect(clampThinkingBudget(2048, 4096)).toBe(2048);
+ expect(clampThinkingBudget(38_912, 32_000)).toBe(32_000 - ANSWER_TOKEN_RESERVE);
+ expect(clampThinkingBudget(2048, 2047)).toBe("no-room");
+ expect(clampThinkingBudget(2048, 2048)).toBe(1024);
+ });
+});
+
+describe("Qwen native OpenAI-wire request payloads", () => {
+ test("thinking_budget always stays below the request output ceiling", () => {
+ for (const maxTokens of [4096, 8192, 32_000, 64_000]) {
+ for (const effort of EFFORT_LEVELS) {
+ const payload = buildNativeQwenPayload(effort, maxTokens);
+ const budget = payload.thinking_budget;
+
+ expect(payload.max_tokens).toBe(maxTokens);
+ expect(budget === undefined || budget < payload.max_tokens).toBe(true);
+ }
+ }
+ });
+
+ test("cannot reproduce the rejected 32000 ceiling with a 38912 thinking budget", () => {
+ const payload = buildNativeQwenPayload("xhigh", 32_000);
+
+ expect(payload.max_tokens).toBe(32_000);
+ expect(payload.enable_thinking).toBe(true);
+ expect(payload.thinking_budget).toBe(32_000 - ANSWER_TOKEN_RESERVE);
+ expect(payload.thinking_budget).toBeLessThan(payload.max_tokens);
+ expect(payload.thinking_budget).not.toBe(38_912);
+ });
+});
diff --git a/packages/cli/src/adapters/model-catalog.test.ts b/packages/cli/src/adapters/model-catalog.test.ts
index a38533db..bf53e3e7 100644
--- a/packages/cli/src/adapters/model-catalog.test.ts
+++ b/packages/cli/src/adapters/model-catalog.test.ts
@@ -8,7 +8,12 @@ import {
type SlimModelEntry,
writeAllModelsCache,
} from "../providers/all-models-cache.js";
-import { resolveSubscriptionRouting } from "./model-catalog.js";
+import {
+ lookupModel,
+ lookupModelReasoning,
+ lookupModelReasoningStatus,
+ resolveSubscriptionRouting,
+} from "./model-catalog.js";
type VendorPlan = CachedSubscriptionPlan & { provider: string };
@@ -62,7 +67,7 @@ function routedPlan(id: string, provider: string, providerUid: string): VendorPl
};
}
-function writeCatalog(entries: SlimModelEntry[], plans: VendorPlan[]): void {
+function writeCatalog(entries: SlimModelEntry[], plans: CachedSubscriptionPlan[]): void {
const cache: DiskCacheV2 = {
version: 2,
lastUpdated: new Date().toISOString(),
@@ -137,3 +142,177 @@ describe("resolveSubscriptionRouting", () => {
});
});
});
+
+describe("plan modelDescriptions metadata lookup", () => {
+ const describedEntries: SlimModelEntry[] = [
+ {
+ modelId: "qwen3.8-max-preview",
+ aliases: [],
+ sources: {},
+ contextWindow: 262_144,
+ reasoningStatus: "known",
+ reasoning: { supported: true, control: "budget", supportsBudgetTokens: true },
+ },
+ {
+ modelId: "qwen3.8-flash-canonical",
+ aliases: [],
+ sources: {},
+ contextWindow: 131_072,
+ reasoningStatus: "known",
+ reasoning: { supported: true, control: "effort", efforts: ["low", "high"] },
+ },
+ {
+ modelId: "claude-opus-4-5",
+ aliases: [],
+ sources: {},
+ contextWindow: 200_000,
+ reasoningStatus: "known",
+ reasoning: { supported: true, control: "effort", efforts: ["high", "max"] },
+ },
+ ];
+
+ function writeDescribedCatalog(): void {
+ writeCatalog(describedEntries, [
+ {
+ id: "future-subscription-plan",
+ modelDescriptions: {
+ "qwen3.8-max": { status: "described", modelId: "qwen3.8-max-preview" },
+ "qwen3.8-flash": { status: "described", modelId: "qwen3.8-flash-canonical" },
+ "claude-opus-4-5-20251101": { status: "described", modelId: "claude-opus-4-5" },
+ },
+ },
+ ]);
+ }
+
+ test("resolves exact plan wire ids through their different canonical metadata ids", () => {
+ writeDescribedCatalog();
+
+ for (const [wireId, canonicalId, contextWindow] of [
+ ["qwen3.8-max", "qwen3.8-max-preview", 262_144],
+ ["qwen3.8-flash", "qwen3.8-flash-canonical", 131_072],
+ ["claude-opus-4-5-20251101", "claude-opus-4-5", 200_000],
+ ] as const) {
+ expect(lookupModel(wireId, cachePath)).toEqual({
+ modelId: canonicalId,
+ contextWindow,
+ supportsVision: undefined,
+ releaseDate: undefined,
+ });
+ expect(lookupModelReasoningStatus(wireId, cachePath)).toBe("known");
+ expect(lookupModelReasoning(wireId, cachePath)?.supported).toBe(true);
+ }
+ });
+
+ test("treats missing and ambiguous as negative answers without fuzzy matching", () => {
+ writeCatalog(
+ [
+ {
+ modelId: "qwen3.9-max-preview",
+ aliases: [],
+ sources: {},
+ contextWindow: 262_144,
+ reasoningStatus: "known",
+ reasoning: { supported: true, control: "budget" },
+ },
+ {
+ modelId: "qwen3.9-flash-preview",
+ aliases: [],
+ sources: {},
+ contextWindow: 131_072,
+ reasoningStatus: "known",
+ reasoning: { supported: true, control: "effort", efforts: ["high"] },
+ },
+ ],
+ [
+ {
+ id: "future-subscription-plan",
+ modelDescriptions: {
+ "qwen3.9-max": { status: "missing" },
+ "qwen3.9-flash": { status: "ambiguous" },
+ },
+ },
+ ]
+ );
+
+ for (const wireId of ["qwen3.9-max", "qwen3.9-flash"]) {
+ expect(lookupModel(wireId, cachePath)).toBeUndefined();
+ expect(lookupModelReasoning(wireId, cachePath)).toBeUndefined();
+ expect(lookupModelReasoningStatus(wireId, cachePath)).toBeUndefined();
+ }
+ });
+
+ test("keeps old caches without modelDescriptions working through ids and aliases", () => {
+ writeCatalog(
+ [
+ {
+ modelId: "legacy-canonical-model",
+ aliases: ["legacy-wire-model"],
+ sources: {},
+ contextWindow: 98_304,
+ reasoning: { supported: true, control: "toggle" },
+ },
+ ],
+ [{ id: "legacy-plan" }]
+ );
+
+ expect(lookupModel("legacy-canonical-model", cachePath)?.contextWindow).toBe(98_304);
+ expect(lookupModel("legacy-wire-model", cachePath)?.modelId).toBe("legacy-canonical-model");
+ expect(lookupModelReasoningStatus("legacy-wire-model", cachePath)).toBe("known");
+ });
+});
+
+describe("lookupModelReasoningStatus", () => {
+ test("preserves explicit and legacy knowledge without manufacturing a control", () => {
+ writeCatalog(
+ [
+ {
+ modelId: "explicit-unknown",
+ aliases: [],
+ sources: {},
+ reasoningStatus: "unknown",
+ supportsThinking: true,
+ },
+ {
+ modelId: "explicit-known",
+ aliases: [],
+ sources: {},
+ reasoningStatus: "known",
+ reasoning: { supported: false, control: "none" },
+ },
+ {
+ modelId: "legacy-described",
+ aliases: [],
+ sources: {},
+ reasoning: { supported: true, control: "toggle" },
+ },
+ {
+ modelId: "legacy-undescribed",
+ aliases: [],
+ sources: {},
+ supportsThinking: false,
+ },
+ ],
+ [
+ {
+ id: "negative-plan",
+ modelDescriptions: {
+ "missing-wire": { status: "missing" },
+ "ambiguous-wire": { status: "ambiguous" },
+ },
+ },
+ ]
+ );
+
+ expect(lookupModelReasoningStatus("explicit-unknown", cachePath)).toBe("unknown");
+ expect(lookupModelReasoning("explicit-unknown", cachePath)).toBeUndefined();
+ expect(lookupModelReasoningStatus("explicit-known", cachePath)).toBe("known");
+ expect(lookupModelReasoningStatus("legacy-described", cachePath)).toBe("known");
+ expect(lookupModelReasoningStatus("legacy-undescribed", cachePath)).toBe("unknown");
+ expect(lookupModelReasoning("legacy-undescribed", cachePath)).toBeUndefined();
+
+ for (const modelId of ["not-in-the-catalog", "missing-wire", "ambiguous-wire"]) {
+ expect(lookupModelReasoningStatus(modelId, cachePath)).toBeUndefined();
+ expect(lookupModelReasoning(modelId, cachePath)).toBeUndefined();
+ }
+ });
+});
diff --git a/packages/cli/src/adapters/model-catalog.ts b/packages/cli/src/adapters/model-catalog.ts
index a1722349..dd4bd19b 100644
--- a/packages/cli/src/adapters/model-catalog.ts
+++ b/packages/cli/src/adapters/model-catalog.ts
@@ -18,6 +18,7 @@ import {
type RouteVariant,
type SlimModelEntry,
readAllModelsCache,
+ reasoningStatusOf,
} from "../providers/all-models-cache.js";
import { compareByReleaseDateDesc } from "../providers/model-ordering.js";
@@ -91,6 +92,53 @@ export function lookupModelReasoning(
return findCacheEntry(modelId, cachePath)?.reasoning;
}
+/**
+ * Whether the catalog KNOWS this model's reasoning control.
+ *
+ * Three answers, and they are three different instructions:
+ *
+ * - `"known"` — {@link lookupModelReasoning} describes the real wire control.
+ * Use it.
+ * - `"unknown"` — the catalog has the model but never learned its control.
+ * Send NO reasoning knob. Do not fall back to a budget, a toggle, or
+ * `supportsThinking`; the catalog publishes that flag even when the status is
+ * unknown, so it is present exactly when it proves nothing.
+ * - `undefined` — no row at all (cold cache, or a model the catalog does not
+ * carry). Same instruction as `"unknown"`, reported separately so a caller
+ * can tell "the catalog is silent about everything" from "the catalog knows
+ * this model and is explicit that the control was never described".
+ *
+ * None of the three is a reason to drop a route. A model claudish cannot
+ * describe is still a model the provider will serve.
+ */
+export function lookupModelReasoningStatus(
+ modelId: string,
+ cachePath?: string
+): "known" | "unknown" | undefined {
+ const entry = findCacheEntry(modelId, cachePath);
+ return entry ? reasoningStatusOf(entry) : undefined;
+}
+
+/**
+ * The model's published output ceiling, or undefined when the catalog has none.
+ *
+ * Undefined means UNKNOWN, never zero and never "unlimited". The slim
+ * projection omits the field rather than sending a null, and it does not carry
+ * the `maxOutputTokensNotApplicable` flag the richer projections use, so a
+ * missing value cannot be distinguished from "not applicable to this model".
+ *
+ * This is reporting data. Request shaping clamps against the REQUEST's own
+ * ceiling, because that is the number the provider validates a reasoning budget
+ * against.
+ */
+export function lookupModelMaxOutputTokens(
+ modelId: string,
+ cachePath?: string
+): number | undefined {
+ const value = findCacheEntry(modelId, cachePath)?.maxOutputTokens;
+ return typeof value === "number" && value > 0 ? value : undefined;
+}
+
/**
* The output-token parameter name this model's API expects.
*
@@ -431,6 +479,50 @@ function findCacheEntry(modelId: string, cachePath?: string): SlimModelEntry | u
}
}
+ // Last step: the id may be a subscription plan's WIRE id, which is not
+ // required to exist as a catalog id or alias. `modelDescriptions` is the
+ // catalog's own exact map from such an id to the canonical row that describes
+ // it — `claude-opus-4-5-20251101` is the dated id Claude Code sends, while
+ // the row is stored undated.
+ //
+ // Metadata only. The canonical id is never returned to a caller that builds a
+ // request: every consumer of this function reads capability fields, and the
+ // id sent upstream stays the one the caller was given.
+ const canonical = resolvePlanDescribedModelId(modelId, cache.plans);
+ if (!canonical) return undefined;
+
+ const canonicalLower = canonical.toLowerCase();
+ for (const entry of cache.entries) {
+ if (entry.modelId.toLowerCase() === canonicalLower) return entry;
+ if (entry.aliases?.some((a) => a.toLowerCase() === canonicalLower)) return entry;
+ }
+
+ return undefined;
+}
+
+/**
+ * The canonical catalog id a plan's exact roster id resolves to, or undefined.
+ *
+ * Only a `described` resolution answers. `missing` and `ambiguous` are the
+ * catalog stating that IT could not resolve the id, and inventing a lookup on
+ * top of that verdict is precisely the guessing this map exists to end — so
+ * they return undefined and the caller degrades to "no information".
+ *
+ * The scan is across plans because one wire id can appear in several (three
+ * plans list `qwen3.8-max`). They agree by construction: each generation builds
+ * the map against one model snapshot. Taking the first `described` hit is
+ * therefore deterministic, and a disagreement would be a backend defect rather
+ * than something to arbitrate here.
+ */
+export function resolvePlanDescribedModelId(
+ wireId: string,
+ plans: CachedSubscriptionPlan[] | undefined
+): string | undefined {
+ if (!plans) return undefined;
+ for (const plan of plans) {
+ const described = plan.modelDescriptions?.[wireId];
+ if (described?.status === "described" && described.modelId) return described.modelId;
+ }
return undefined;
}
diff --git a/packages/cli/src/adapters/qwen-model-dialect.ts b/packages/cli/src/adapters/qwen-model-dialect.ts
index d59fdc2a..5f467da4 100644
--- a/packages/cli/src/adapters/qwen-model-dialect.ts
+++ b/packages/cli/src/adapters/qwen-model-dialect.ts
@@ -19,7 +19,13 @@
*/
import { log } from "../logger.js";
-import { type AdapterResult, BaseAPIFormat, matchesModelFamily } from "./base-api-format.js";
+import {
+ type AdapterResult,
+ BaseAPIFormat,
+ clampThinkingBudget,
+ matchesModelFamily,
+ outputCeilingOf,
+} from "./base-api-format.js";
// Qwen special tokens that should be stripped from output
const QWEN_SPECIAL_TOKENS = [
@@ -80,13 +86,42 @@ export class QwenModelDialect extends BaseAPIFormat {
log(`[QwenModelDialect] effort ${effort} -> enable_thinking: false for ${this.modelId}`);
} else {
request.enable_thinking = true;
- const budget = this.effortToThinkingTokenBudget(effort);
- if (budget !== undefined) {
- request.thinking_budget = budget;
+ const requested = this.effortToThinkingTokenBudget(effort);
+
+ // DashScope validates the budget against the output ceiling in the SAME
+ // request and rejects the pair outright:
+ //
+ // 400 [invalid_parameter_error] max_completion_tokens [32000] must be
+ // greater than thinking_budget [38912]
+ //
+ // The ladder's `xhigh` rung is 38912 while Claude Code's `max_tokens` is
+ // routinely 32000 (and 4096 by default), so the two collide without any
+ // user being able to reach either number. Clamping here rather than
+ // lowering the ladder keeps the requested depth wherever the ceiling
+ // affords it.
+ const ceiling = outputCeilingOf(originalRequest, request);
+ const budget = clampThinkingBudget(requested, ceiling);
+
+ if (budget === "no-room") {
+ // No legal budget fits and still leaves room to answer. Reasoning stays
+ // ON — the effort asked for it — with the depth left to the model,
+ // which is the only remaining payload this endpoint accepts.
+ delete request.thinking_budget;
+ log(
+ `[QwenModelDialect] effort ${effort} -> enable_thinking: true, no thinking_budget (${requested} does not fit under ceiling ${ceiling}) for ${this.modelId}`
+ );
+ } else {
+ if (budget !== undefined) {
+ request.thinking_budget = budget;
+ }
+ log(
+ `[QwenModelDialect] effort ${effort} -> enable_thinking: true, thinking_budget: ${budget ?? "(model max)"}${
+ budget !== undefined && budget !== requested
+ ? ` (clamped from ${requested} under ceiling ${ceiling})`
+ : ""
+ } for ${this.modelId}`
+ );
}
- log(
- `[QwenModelDialect] effort ${effort} -> enable_thinking: true, thinking_budget: ${budget ?? "(model max)"} for ${this.modelId}`
- );
}
// Cleanup: remove raw thinking object so it doesn't double-send.
diff --git a/packages/cli/src/providers/all-models-cache.test.ts b/packages/cli/src/providers/all-models-cache.test.ts
index dfd2659c..809813b0 100644
--- a/packages/cli/src/providers/all-models-cache.test.ts
+++ b/packages/cli/src/providers/all-models-cache.test.ts
@@ -14,6 +14,7 @@ import {
type DiskCacheV2,
type SlimModelEntry,
readAllModelsCache,
+ reasoningStatusOf,
writeAllModelsCache,
} from "./all-models-cache.js";
@@ -206,3 +207,39 @@ describe("all-models-cache helpers", () => {
expect(result!.entries).toEqual([]);
});
});
+
+describe("reasoningStatusOf", () => {
+ test("keeps explicit unknown truthful even when coarse thinking support is true", () => {
+ expect(
+ reasoningStatusOf({
+ ...sampleEntry("orion-8.0-future", "future-labs/orion-8.0-future"),
+ reasoningStatus: "unknown",
+ supportsThinking: true,
+ })
+ ).toBe("unknown");
+ });
+
+ test("returns explicit known", () => {
+ expect(
+ reasoningStatusOf({
+ ...sampleEntry("orion-8.1-future", "future-labs/orion-8.1-future"),
+ reasoningStatus: "known",
+ })
+ ).toBe("known");
+ });
+
+ test("infers only from a self-describing reasoning record in older caches", () => {
+ expect(
+ reasoningStatusOf({
+ ...sampleEntry("legacy-described", "future-labs/legacy-described"),
+ reasoning: { supported: true, control: "toggle" },
+ })
+ ).toBe("known");
+ expect(
+ reasoningStatusOf({
+ ...sampleEntry("legacy-undescribed", "future-labs/legacy-undescribed"),
+ supportsThinking: true,
+ })
+ ).toBe("unknown");
+ });
+});
diff --git a/packages/cli/src/providers/all-models-cache.ts b/packages/cli/src/providers/all-models-cache.ts
index e6157fda..1b9b8f92 100644
--- a/packages/cli/src/providers/all-models-cache.ts
+++ b/packages/cli/src/providers/all-models-cache.ts
@@ -125,6 +125,39 @@ export interface SlimModelEntry {
releaseDate?: string;
/** Context window in tokens (present when Firebase has it) */
contextWindow?: number;
+ /**
+ * The model's own output ceiling, when the catalog publishes one.
+ *
+ * ABSENT MEANS UNKNOWN, never zero. The slim projection omits the field
+ * entirely when it has no value, and it does NOT carry the
+ * `maxOutputTokensNotApplicable` flag that the fuller projections use — so
+ * "no number here" cannot be told apart from "the concept does not apply to
+ * this model", and both must be treated as "we do not know".
+ *
+ * A reasoning budget is clamped against the REQUEST's ceiling rather than
+ * this one (`max_tokens` is what the provider validates against), so this
+ * value informs reporting, not request shaping.
+ */
+ maxOutputTokens?: number;
+ /**
+ * Whether the catalog KNOWS this model's reasoning control.
+ *
+ * `"known"` — the `reasoning` record below describes the real wire control.
+ * `"unknown"` — the source never described it. This is NOT the same as an
+ * explicit unsupported record (`reasoning.supported === false`), and the two
+ * demand opposite behaviour: unsupported means "switch reasoning off",
+ * unknown means "emit no reasoning knob at all and change nothing".
+ *
+ * Absent on caches written before the field existed. Treat absent as
+ * `"known"` only when a `reasoning` record is present — see
+ * {@link reasoningStatusOf}, which is the single place that rule lives.
+ *
+ * Do NOT derive a control from {@link supportsThinking} when this is
+ * `"unknown"`. The backend sets `reasoningStatus: "unknown"` while still
+ * publishing `supportsThinking` from coarse capability data, so the flag is
+ * present precisely in the case where it proves nothing about the knob.
+ */
+ reasoningStatus?: "known" | "unknown";
/**
* Reasoning capability (present when Firebase has it). Already carried by the
* on-disk `?catalog=slim` payload; the type previously dropped it, so every
@@ -174,6 +207,46 @@ export interface SlimModelEntry {
endpoints?: Record<string, ModelEndpoint>;
}
+/**
+ * Whether this entry's reasoning control is KNOWN, for entries written by any
+ * catalog version.
+ *
+ * The backend always sends `reasoningStatus` now, so the live path is a plain
+ * read. The inference below exists only for a cache written before the field
+ * shipped, and it is deliberately conservative: a `reasoning` record is
+ * self-describing, so its presence means known; its absence on an old cache is
+ * indistinguishable from "never described", so it reads unknown.
+ *
+ * That inference matches what the backend itself does
+ * (`reasoningStatus: reasoning !== undefined ? "known" : "unknown"`), so an old
+ * cache degrades to the same answer a fresh one would give rather than to a
+ * guess of its own.
+ */
+export function reasoningStatusOf(entry: SlimModelEntry): "known" | "unknown" {
+ if (entry.reasoningStatus === "known" || entry.reasoningStatus === "unknown") {
+ return entry.reasoningStatus;
+ }
+ return entry.reasoning !== undefined ? "known" : "unknown";
+}
+
+/**
+ * How one exact plan roster id resolves to a canonical catalog description.
+ *
+ * The KEY this is stored under is the wire id the provider expects for
+ * inference; `modelId` is the canonical id that carries the metadata. They are
+ * frequently different (`claude-opus-4-5-20251101` is the wire id, the row is
+ * stored undated), and conflating them is the whole point of the map: resolve
+ * metadata through `modelId`, keep sending the key.
+ *
+ * `missing` and `ambiguous` are explicit negative answers, not absence. They
+ * say the catalog looked and could not resolve the id, which is information —
+ * it must not be read as "this model has no reasoning" or as grounds to drop a
+ * subscription route.
+ */
+export type CatalogPlanModelDescription =
+ | { status: "described"; modelId: string }
+ | { status: "missing" | "ambiguous" };
+
export type SubscriptionModelDiscovery = "catalog" | "client" | "hybrid";
/** Minimal queryPlans projection needed by the synchronous routing engine. */
@@ -196,6 +269,15 @@ export interface CachedSubscriptionPlan {
prefix?: string;
nativeModelProviders?: string[];
};
+ /**
+ * Exact plan roster id → canonical catalog description.
+ *
+ * Published for routed catalog/hybrid plans. Absent on `client`-discovery
+ * plans, whose `includedModels` are display labels rather than wire ids, and
+ * absent on caches written before the field shipped — in both cases callers
+ * fall back to matching the id directly against the catalog.
+ */
+ modelDescriptions?: Record<string, CatalogPlanModelDescription>;
}
/**
@@ -211,6 +293,16 @@ export interface DiskCacheV2 {
models: Array<{ id: string }>;
/** Additive queryPlans cache. Absent on legacy v2 files. */
plans?: CachedSubscriptionPlan[];
+ /**
+ * The catalog generation every page in `entries` AND `plans` was read from.
+ *
+ * Recorded so the file can state which snapshot it is, rather than being an
+ * undated merge. A refresh writes this only when every page and the plans
+ * document agreed on one revision, so its presence is the assertion that the
+ * file is internally consistent. Absent on files written before pinning
+ * existed, which are still readable and are simply not known to be coherent.
+ */
+ catalogRevision?: string;
}
export const ALL_MODELS_CACHE_PATH = join(homedir(), ".claudish", "all-models.json");
@@ -244,6 +336,12 @@ export function readAllModelsCache(path: string = ALL_MODELS_CACHE_PATH): DiskCa
const models = Array.isArray(data.models) ? (data.models as Array<{ id: string }>) : [];
const entries = Array.isArray(data.entries) ? (data.entries as SlimModelEntry[]) : [];
const plans = Array.isArray(data.plans) ? (data.plans as CachedSubscriptionPlan[]) : undefined;
+ // Read back explicitly. This function rebuilds the object from a known field
+ // list rather than spreading `data`, so any field not named here is silently
+ // dropped on the way in — which is what happened to `catalogRevision` until
+ // a round-trip check caught it writing correctly and reading back undefined.
+ const catalogRevision =
+ typeof data.catalogRevision === "string" ? data.catalogRevision : undefined;
return {
version: 2,
@@ -251,6 +349,7 @@ export function readAllModelsCache(path: string = ALL_MODELS_CACHE_PATH): DiskCa
entries,
models,
...(plans !== undefined ? { plans } : {}),
+ ...(catalogRevision !== undefined ? { catalogRevision } : {}),
};
}
@@ -281,6 +380,11 @@ export function writeAllModelsCache(
...(data.plans !== undefined || existing?.plans !== undefined
? { plans: data.plans ?? existing?.plans ?? [] }
: {}),
+ // Carried, never merged from `existing`. The revision describes the entries
+ // and plans written in THIS call; inheriting the previous file's value onto
+ // a partial write would stamp new data with an old snapshot's identity and
+ // make the coherence claim a lie.
+ ...(data.catalogRevision !== undefined ? { catalogRevision: data.catalogRevision } : {}),
};
mkdirSync(dirname(path), { recursive: true });
diff --git a/packages/cli/src/providers/catalog-client.test.ts b/packages/cli/src/providers/catalog-client.test.ts
index daab3081..6a7617cd 100644
--- a/packages/cli/src/providers/catalog-client.test.ts
+++ b/packages/cli/src/providers/catalog-client.test.ts
@@ -1,7 +1,12 @@
import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type SlimModelEntry, readAllModelsCache } from "./all-models-cache.js";
import {
_resetCatalogClient,
catalogWarmDisabledFor,
+ getCatalogEntries,
refreshCatalog,
resolveTargetForCatalog,
} from "./catalog-client.js";
@@ -9,17 +14,35 @@ import { parseModelSpec } from "./model-parser.js";
const realFetch = globalThis.fetch;
let previousDisableCatalogWarm: string | undefined;
+let previousCatalogUrl: string | undefined;
+let previousPlansUrl: string | undefined;
+const tempDirs: string[] = [];
+
+function tempCachePath(prefix = "claudish-catalog-client-"): string {
+ const dir = mkdtempSync(join(tmpdir(), prefix));
+ tempDirs.push(dir);
+ return join(dir, "all-models.json");
+}
+
+function restoreEnv(name: string, value: string | undefined): void {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+}
beforeEach(() => {
previousDisableCatalogWarm = process.env.CLAUDISH_DISABLE_CATALOG_WARM;
+ previousCatalogUrl = process.env.CLAUDISH_CATALOG_URL;
+ previousPlansUrl = process.env.CLAUDISH_PLANS_URL;
_resetCatalogClient();
});
afterEach(() => {
- if (previousDisableCatalogWarm === undefined) {
- delete process.env.CLAUDISH_DISABLE_CATALOG_WARM;
- } else {
- process.env.CLAUDISH_DISABLE_CATALOG_WARM = previousDisableCatalogWarm;
+ restoreEnv("CLAUDISH_DISABLE_CATALOG_WARM", previousDisableCatalogWarm);
+ restoreEnv("CLAUDISH_CATALOG_URL", previousCatalogUrl);
+ restoreEnv("CLAUDISH_PLANS_URL", previousPlansUrl);
+ while (tempDirs.length > 0) {
+ const dir = tempDirs.pop();
+ if (dir) rmSync(dir, { recursive: true, force: true });
}
globalThis.fetch = realFetch;
_resetCatalogClient();
@@ -49,7 +72,7 @@ describe("refreshCatalog catalog-warm kill switch", () => {
);
globalThis.fetch = fetchStub as unknown as typeof fetch;
- const outcome = await refreshCatalog(100);
+ const outcome = await refreshCatalog(100, { cachePath: tempCachePath() });
expect(outcome).toEqual({ kind: "fetch_failed", reason: "disabled" });
expect(fetchStub).not.toHaveBeenCalled();
@@ -74,6 +97,270 @@ describe("refreshCatalog catalog-warm kill switch", () => {
}
});
+const catalogEntry = (modelId: string): SlimModelEntry => ({
+ modelId,
+ aliases: [],
+ sources: { "openrouter-api": { externalId: `future-labs/${modelId}` } },
+ reasoningStatus: "unknown",
+});
+
+describe("refreshCatalog revision-pinned pagination", () => {
+ let server: ReturnType<typeof Bun.serve> | undefined;
+ let cachePath = "";
+ let handleRequest: (request: Request) => Response | Promise<Response>;
+
+ beforeEach(() => {
+ cachePath = tempCachePath();
+ handleRequest = () => new Response(null, { status: 500 });
+ server = Bun.serve({
+ port: 0,
+ fetch: (request) => handleRequest(request),
+ });
+ const origin = `http://127.0.0.1:${server.port}`;
+
+ // ORDER IS LOAD-BEARING. The URL redirect goes up BEFORE the warm gate comes
+ // down, and never the other way round.
+ //
+ // `proxy-server.ts` fires an un-awaited `warmCatalog()` on every
+ // `createProxyServer`, so a detached refresh can reach `catalogWarmDisabled()`
+ // at any instant while this suite runs. Clearing the gate first leaves a
+ // window in which such a refresh is enabled AND still pointed at the live
+ // catalog — it then fetches over the network and writes the developer's real
+ // `~/.claudish/all-models.json`.
+ //
+ // That is not hypothetical. It is the leak `catalog-client.ts` documents
+ // having measured on 2026-09-15, and this file reproduced it on 2026-09-17:
+ // `guard-real-config` reported "REAL MODEL CATALOG CACHE MUTATED — changed
+ // lastUpdated" on one `test:safe` run and not the next, because whether the
+ // detached warm lands inside the window depends on file ordering.
+ //
+ // With this order, anything that slips through hits the local server instead,
+ // and the guard's remaining job is a backstop rather than a cleanup.
+ process.env.CLAUDISH_CATALOG_URL = `${origin}/queryModels?status=active&catalog=slim&limit=7`;
+ process.env.CLAUDISH_PLANS_URL = `${origin}/queryPlans`;
+ delete process.env.CLAUDISH_DISABLE_CATALOG_WARM;
+ });
+
+ afterEach(() => {
+ server?.stop(true);
+ server = undefined;
+ });
+
+ function json(data: unknown, revision?: string, status = 200): Response {
+ const headers = new Headers({ "Content-Type": "application/json" });
+ if (revision) headers.set("X-Catalog-Revision", revision);
+ return new Response(JSON.stringify(data), { status, headers });
+ }
+
+ async function seedPreviousGeneration(): Promise<{
+ bytes: string;
+ memory: SlimModelEntry[];
+ }> {
+ const previousEntry = catalogEntry("orion-7.3-future");
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ if (url.pathname === "/queryModels") {
+ return json(
+ { models: [previousEntry], total: 1, offset: 0, limit: 1000, hasMore: false },
+ "revision-previous"
+ );
+ }
+ if (url.pathname === "/queryPlans") {
+ return json({ plans: [{ id: "previous-plan" }] }, "revision-previous");
+ }
+ return new Response(null, { status: 404 });
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "refreshed",
+ modelCount: 1,
+ catalogRevision: "revision-previous",
+ pages: 1,
+ });
+ const memory = getCatalogEntries();
+ expect(memory).toEqual([previousEntry]);
+ return { bytes: readFileSync(cachePath, "utf-8"), memory: memory! };
+ }
+
+ function expectPreviousGenerationPreserved(previous: {
+ bytes: string;
+ memory: SlimModelEntry[];
+ }): void {
+ expect(readFileSync(cachePath, "utf-8")).toBe(previous.bytes);
+ expect(getCatalogEntries()).toBe(previous.memory);
+ }
+
+ test("follows every page, advances by returned rows, and pins pages and plans", async () => {
+ const requests: Array<{
+ path: string;
+ offset: string | null;
+ limit: string | null;
+ revision: string | null;
+ revisionHeader: string | null;
+ }> = [];
+ const first = [catalogEntry("orion-7.4-future"), catalogEntry("qwen4.2-nebula")];
+ const second = [catalogEntry("claude-opus-6-future")];
+
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ requests.push({
+ path: url.pathname,
+ offset: url.searchParams.get("offset"),
+ limit: url.searchParams.get("limit"),
+ revision: url.searchParams.get("revision"),
+ revisionHeader: request.headers.get("revision"),
+ });
+ if (url.pathname === "/queryPlans") {
+ return json({ plans: [{ id: "future-plan" }] }, "revision-a");
+ }
+ if (url.searchParams.get("offset") === "0") {
+ return json(
+ { models: first, total: 3, offset: 0, limit: 1000, hasMore: true },
+ "revision-a"
+ );
+ }
+ return json(
+ { models: second, total: 3, offset: 2, limit: 1000, hasMore: false },
+ "revision-a"
+ );
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "refreshed",
+ modelCount: 3,
+ catalogRevision: "revision-a",
+ pages: 2,
+ });
+
+ expect(requests).toEqual([
+ {
+ path: "/queryModels",
+ offset: "0",
+ limit: "1000",
+ revision: null,
+ revisionHeader: null,
+ },
+ {
+ path: "/queryModels",
+ offset: "2",
+ limit: "1000",
+ revision: "revision-a",
+ revisionHeader: null,
+ },
+ {
+ path: "/queryPlans",
+ offset: null,
+ limit: null,
+ revision: "revision-a",
+ revisionHeader: null,
+ },
+ ]);
+ const cache = readAllModelsCache(cachePath);
+ expect(cache?.entries).toEqual([...first, ...second]);
+ expect(cache?.plans).toEqual([{ id: "future-plan" }]);
+ expect(cache?.catalogRevision).toBe("revision-a");
+ });
+
+ test("accepts the currently deployed one-page response when hasMore is omitted", async () => {
+ const onlyPage = [catalogEntry("orion-8.0-future")];
+ let modelRequests = 0;
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ if (url.pathname === "/queryPlans") return json({ plans: [] }, "revision-current");
+ modelRequests++;
+ return json({ models: onlyPage, total: 1, offset: 0, limit: 1000 }, "revision-current");
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "refreshed",
+ modelCount: 1,
+ catalogRevision: "revision-current",
+ pages: 1,
+ });
+ expect(modelRequests).toBe(1);
+ expect(readAllModelsCache(cachePath)?.entries).toEqual(onlyPage);
+ expect(readAllModelsCache(cachePath)?.catalogRevision).toBe("revision-current");
+ });
+
+ test("rejects a later page from another revision and preserves both caches byte-for-byte", async () => {
+ const previous = await seedPreviousGeneration();
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ if (url.searchParams.get("offset") === "0") {
+ return json({ models: [catalogEntry("new-page-one")], hasMore: true }, "revision-new");
+ }
+ expect(url.searchParams.get("revision")).toBe("revision-new");
+ return json({ models: [catalogEntry("new-page-two")], hasMore: false }, "revision-other");
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "fetch_failed",
+ reason: "revision_mismatch",
+ });
+ expectPreviousGenerationPreserved(previous);
+ });
+
+ test("rejects a later HTTP failure as incomplete and preserves both caches byte-for-byte", async () => {
+ const previous = await seedPreviousGeneration();
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ if (url.searchParams.get("offset") === "0") {
+ return json({ models: [catalogEntry("new-page-one")], hasMore: true }, "revision-new");
+ }
+ expect(url.searchParams.get("revision")).toBe("revision-new");
+ return new Response("later page failed", { status: 500 });
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "fetch_failed",
+ reason: "incomplete",
+ });
+ expectPreviousGenerationPreserved(previous);
+ });
+
+ test("rejects a later network failure as incomplete and preserves both caches byte-for-byte", async () => {
+ const previous = await seedPreviousGeneration();
+ const stopped = Bun.serve({ port: 0, fetch: () => new Response(null, { status: 204 }) });
+ const stoppedPort = stopped.port;
+ stopped.stop(true);
+
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ if (url.searchParams.get("offset") !== "0") {
+ return new Response("unexpected second request to live server", { status: 500 });
+ }
+ process.env.CLAUDISH_CATALOG_URL = `http://127.0.0.1:${stoppedPort}/queryModels?status=active&catalog=slim`;
+ return json({ models: [catalogEntry("new-page-one")], hasMore: true }, "revision-new");
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "fetch_failed",
+ reason: "incomplete",
+ });
+ expectPreviousGenerationPreserved(previous);
+ });
+
+ test("rejects hasMore with an empty page instead of looping or committing a prefix", async () => {
+ const previous = await seedPreviousGeneration();
+ let pageRequests = 0;
+ handleRequest = (request) => {
+ const url = new URL(request.url);
+ pageRequests++;
+ if (url.searchParams.get("offset") === "0") {
+ return json({ models: [catalogEntry("new-page-one")], hasMore: true }, "revision-new");
+ }
+ return json({ models: [], hasMore: true }, "revision-new");
+ };
+
+ expect(await refreshCatalog(1000, { cachePath })).toEqual({
+ kind: "fetch_failed",
+ reason: "incomplete",
+ });
+ expect(pageRequests).toBe(2);
+ expectPreviousGenerationPreserved(previous);
+ });
+});
+
describe("resolveTargetForCatalog", () => {
test("rewrites a changed explicit MiniMax spec and returns its resolution", () => {
const resolution = {
diff --git a/packages/cli/src/providers/catalog-client.ts b/packages/cli/src/providers/catalog-client.ts
index 4031e8de..885d86de 100644
--- a/packages/cli/src/providers/catalog-client.ts
+++ b/packages/cli/src/providers/catalog-client.ts
@@ -50,12 +50,27 @@ import {
* Chiefly useful for integration tests that point at a local server to force
* fetch failures.
*/
-const FIREBASE_CATALOG_URL =
- process.env.CLAUDISH_CATALOG_URL ??
- process.env.FIREBASE_CATALOG_URL ??
+const DEFAULT_CATALOG_URL =
"https://us-central1-claudish-6da10.cloudfunctions.net/queryModels?status=active&catalog=slim&limit=1000";
-const FIREBASE_PLANS_URL = process.env.CLAUDISH_PLANS_URL ?? derivePlansUrl(FIREBASE_CATALOG_URL);
+/**
+ * Resolved PER CALL rather than once at import.
+ *
+ * A module-level constant freezes whatever the environment held at the instant
+ * this file was first imported, which makes the documented override untestable:
+ * a test that points `CLAUDISH_CATALOG_URL` at a local server only takes effect
+ * if it happens to run before any other file imports this module. Reading the
+ * variable at call time makes the override mean what it says, and costs one
+ * property read per refresh.
+ */
+function catalogUrl(): string {
+ return process.env.CLAUDISH_CATALOG_URL ?? process.env.FIREBASE_CATALOG_URL ?? DEFAULT_CATALOG_URL;
+}
+
+/** The plans endpoint, derived from the catalog URL unless overridden. */
+function plansUrl(): string {
+ return process.env.CLAUDISH_PLANS_URL ?? derivePlansUrl(catalogUrl());
+}
function derivePlansUrl(catalogUrl: string): string {
try {
@@ -78,8 +93,24 @@ export type DiskCache = DiskCacheV2;
* ground truth so the launcher can make a policy decision.
*/
export type RefreshOutcome =
- | { kind: "refreshed"; modelCount: number }
- | { kind: "fetch_failed"; reason: "timeout" | "network" | "http_error" | "empty" | "disabled" };
+ // `catalogRevision` and `pages` are diagnostics, and OPTIONAL so that
+ // constructing a success outcome (which several callers and fakes do) does not
+ // require knowing them. Requiring them would buy no safety: no caller branches
+ // on either value.
+ | { kind: "refreshed"; modelCount: number; catalogRevision?: string; pages?: number }
+ | {
+ kind: "fetch_failed";
+ reason:
+ | "timeout"
+ | "network"
+ | "http_error"
+ | "empty"
+ | "disabled"
+ /** A later page came from a different catalog generation than page 1. */
+ | "revision_mismatch"
+ /** The server said `hasMore` but the pages could not be completed. */
+ | "incomplete";
+ };
/** Result of resolving a user-typed model name for a provider. */
export interface ModelResolutionResult {
@@ -418,7 +449,121 @@ function catalogWarmDisabled(): boolean {
return catalogWarmDisabledFor(process.env.CLAUDISH_DISABLE_CATALOG_WARM);
}
-export async function refreshCatalog(timeoutMs: number): Promise<RefreshOutcome> {
+// ---------------------------------------------------------------------------
+// Revision-pinned pagination
+// ---------------------------------------------------------------------------
+
+/**
+ * The header the catalog stamps every response with, naming the immutable
+ * generation that served it.
+ */
+const CATALOG_REVISION_HEADER = "x-catalog-revision";
+
+/**
+ * Hard ceiling on pages per refresh.
+ *
+ * A stop condition that does not depend on the server agreeing with itself.
+ * `hasMore` is the server's claim; this is ours. Without it, a server that
+ * always answers `hasMore: true` turns a warm into an unbounded fetch loop on
+ * the request path.
+ */
+const MAX_CATALOG_PAGES = 40;
+
+/**
+ * Page size requested per call.
+ *
+ * The backend clamps `limit` to 2000 (`query-handler.ts`, slim branch), so a
+ * single request can NOT be relied on to return the whole catalog however large
+ * a number is asked for. Paging is therefore mandatory, not an optimisation.
+ */
+const CATALOG_PAGE_LIMIT = 1000;
+
+/**
+ * Build one page request from the configured base URL.
+ *
+ * `offset`/`limit` are overwritten rather than appended, so a base URL that
+ * already carries them (the default does: `limit=1000`) pages correctly instead
+ * of sending the parameter twice. Every other parameter the user configured —
+ * `status`, `catalog`, and anything a test server needs — is preserved.
+ *
+ * `revision` pins the page to one immutable generation. It is a QUERY
+ * PARAMETER, not a request header: the backend reads `req.query.revision`.
+ * Sending it as a header would be silently ignored and every page would be
+ * served from whatever generation was current at that instant, which is exactly
+ * the torn read the pinning exists to prevent.
+ */
+export function buildCatalogPageUrl(
+ baseUrl: string,
+ offset: number,
+ limit: number,
+ revision?: string
+): string {
+ const url = new URL(baseUrl);
+ url.searchParams.set("offset", String(offset));
+ url.searchParams.set("limit", String(limit));
+ if (revision) url.searchParams.set("revision", revision);
+ return url.toString();
+}
+
+/** One slim page as the catalog returns it. */
+interface CatalogPage {
+ models: SlimModelEntry[];
+ total?: number;
+ offset?: number;
+ limit?: number;
+ hasMore?: boolean;
+}
+
+type PageResult =
+ | { ok: true; page: CatalogPage; revision?: string }
+ | { ok: false; reason: "timeout" | "network" | "http_error" };
+
+/** Fetch one page. Never throws; classifies its own failure. */
+async function fetchCatalogPage(url: string, timeoutMs: number): Promise<PageResult> {
+ let response: Response;
+ try {
+ response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+ } catch (err) {
+ const name = (err as { name?: string } | null | undefined)?.name;
+ const reason: "timeout" | "network" =
+ name === "TimeoutError" || name === "AbortError" ? "timeout" : "network";
+ return { ok: false, reason };
+ }
+
+ if (!response.ok) return { ok: false, reason: "http_error" };
+
+ let page: CatalogPage;
+ try {
+ page = (await response.json()) as CatalogPage;
+ } catch {
+ // Got a response but could not read it — network-class, distinct from "empty".
+ return { ok: false, reason: "network" };
+ }
+
+ const revision = response.headers.get(CATALOG_REVISION_HEADER) ?? undefined;
+ return { ok: true, page, revision };
+}
+
+/** Options for {@link refreshCatalog}. */
+export interface RefreshCatalogOptions {
+ /**
+ * Override the disk cache path.
+ *
+ * TESTS ONLY, and load-bearing for them. Without this seam a test that
+ * exercises a refresh writes the developer's real
+ * `~/.claudish/all-models.json` — which has happened: a suite seeded the live
+ * catalog because a refresh reached the default path, and the repo's
+ * guard-real-config list had to grow a second file afterwards. Coverage for
+ * pagination and revision mismatches inherently drives a refresh to
+ * completion, so that coverage cannot exist safely without this parameter.
+ */
+ cachePath?: string;
+}
+
+export async function refreshCatalog(
+ timeoutMs: number,
+ options: RefreshCatalogOptions = {}
+): Promise<RefreshOutcome> {
// `CLAUDISH_DISABLE_CATALOG_WARM=1` turns every refresh into a no-op, which is
// the same contract `CLAUDISH_DISABLE_KEYCHAIN` and `CLAUDISH_DISABLE_OP` give
// the other two shared resources a test must not reach.
@@ -443,51 +588,96 @@ export async function refreshCatalog(timeoutMs: number): Promise<RefreshOutcome>
return { kind: "fetch_failed", reason: "disabled" };
}
- const plansPromise = fetchSubscriptionPlans(timeoutMs);
- let response: Response;
- try {
- response = await fetch(FIREBASE_CATALOG_URL, { signal: AbortSignal.timeout(timeoutMs) });
- } catch (err) {
- const name = (err as { name?: string } | null | undefined)?.name;
- const reason: "timeout" | "network" =
- name === "TimeoutError" || name === "AbortError" ? "timeout" : "network";
- return { kind: "fetch_failed", reason };
- }
+ // ── Page the catalog, pinned to one generation ───────────────────────────
+ //
+ // NOTHING below touches `_memCache` or the disk file until every page AND the
+ // plans document have been read successfully from the SAME revision. A
+ // partial catalog is worse than a stale one: a model missing because its page
+ // never arrived is indistinguishable from a model the catalog does not serve,
+ // and the second reading silently drops a working route.
+ const entries: SlimModelEntry[] = [];
+ let revision: string | undefined;
+ let pages = 0;
+ let offset = 0;
+
+ for (;;) {
+ const url = buildCatalogPageUrl(catalogUrl(), offset, CATALOG_PAGE_LIMIT, revision);
+ const result = await fetchCatalogPage(url, timeoutMs);
+ if (!result.ok) {
+ // A first-page failure is the pre-existing "could not reach the catalog".
+ // A LATER page failing is a torn read, and reporting it as a plain network
+ // error would invite a caller to accept the partial pages already in hand.
+ return {
+ kind: "fetch_failed",
+ reason: pages === 0 ? result.reason : "incomplete",
+ };
+ }
- if (!response.ok) return { kind: "fetch_failed", reason: "http_error" };
+ const { page } = result;
+ if (!Array.isArray(page.models)) return { kind: "fetch_failed", reason: "empty" };
+
+ if (pages === 0) {
+ // Pin to whatever generation served page 1. When the deployment predates
+ // revision headers this stays undefined and the pages are simply
+ // unpinned — the previous behaviour, not a failure.
+ revision = result.revision;
+ if (page.models.length === 0) return { kind: "fetch_failed", reason: "empty" };
+ } else if (revision && result.revision && result.revision !== revision) {
+ // The generation rolled over mid-refresh. The pages in hand describe two
+ // different snapshots and must not be stitched together.
+ return { kind: "fetch_failed", reason: "revision_mismatch" };
+ }
- let data: { models: SlimModelEntry[]; total?: number };
- try {
- data = (await response.json()) as { models: SlimModelEntry[]; total?: number };
- } catch {
- // Got a response but could not read it — network-class, distinct from "empty".
- return { kind: "fetch_failed", reason: "network" };
- }
+ entries.push(...page.models);
+ pages++;
- if (!Array.isArray(data.models) || data.models.length === 0) {
- return { kind: "fetch_failed", reason: "empty" };
+ if (page.hasMore !== true) break;
+
+ // `hasMore` with an empty page cannot make progress. Believing the flag
+ // would spin until MAX_CATALOG_PAGES; believing the page would silently
+ // truncate. Neither is a catalog, so refuse both.
+ if (page.models.length === 0) return { kind: "fetch_failed", reason: "incomplete" };
+
+ offset += page.models.length;
+
+ if (pages >= MAX_CATALOG_PAGES) {
+ // Our own stop condition, reached while the server still claims more.
+ return { kind: "fetch_failed", reason: "incomplete" };
+ }
}
+ if (entries.length === 0) return { kind: "fetch_failed", reason: "empty" };
+
+ // Plans are read AFTER the models and pinned to the same generation, so the
+ // `modelDescriptions` map joins against the exact snapshot in `entries`.
+ // Fetching it concurrently (as this once did) cannot be pinned at all: the
+ // revision is only known once page 1 has answered.
+ const plans = await fetchSubscriptionPlans(timeoutMs, revision);
+
// Build the backward-compat models array BEFORE mutating shared state, so a
// throw below leaves _memCache and the disk file untouched.
const backwardCompatModels: Array<{ id: string }> = [];
- for (const entry of data.models) {
+ for (const entry of entries) {
const id = externalIdFor(entry, "openrouter");
if (id) backwardCompatModels.push({ id });
}
- _memCache = data.models;
- const plans = await plansPromise;
- writeAllModelsCache({
- entries: data.models,
- models: backwardCompatModels,
- ...(plans !== undefined ? { plans } : {}),
- });
+ // ── Commit ──────────────────────────────────────────────────────────────
+ _memCache = entries;
+ writeAllModelsCache(
+ {
+ entries,
+ models: backwardCompatModels,
+ ...(plans !== undefined ? { plans } : {}),
+ ...(revision !== undefined ? { catalogRevision: revision } : {}),
+ },
+ options.cachePath
+ );
// Short-circuit the proxy-server background warm.
_warmPromise = Promise.resolve();
- return { kind: "refreshed", modelCount: data.models.length };
+ return { kind: "refreshed", modelCount: entries.length, catalogRevision: revision, pages };
}
/**
@@ -495,10 +685,15 @@ export async function refreshCatalog(timeoutMs: number): Promise<RefreshOutcome>
* discard a valid model refresh or erase the last-known-good routing join.
*/
async function fetchSubscriptionPlans(
- timeoutMs: number
+ timeoutMs: number,
+ revision?: string
): Promise<CachedSubscriptionPlan[] | undefined> {
try {
- const response = await fetch(FIREBASE_PLANS_URL, {
+ const url = new URL(plansUrl());
+ // Same generation as the model pages, so `modelDescriptions` resolves
+ // against the rows actually in hand rather than a newer snapshot's.
+ if (revision) url.searchParams.set("revision", revision);
+ const response = await fetch(url.toString(), {
signal: AbortSignal.timeout(timeoutMs),
});
if (!response.ok) return undefined;