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.tsindex 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 thediff --git a/packages/cli/src/adapters/catalog-contract-payload.test.ts b/packages/cli/src/adapters/catalog-contract-payload.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 outputconst 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.tsindex 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.tsindex 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): DiskCaconst 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): DiskCaentries,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.tsindex 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.tsindex 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;