Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
import { existsSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { writeFileAtomic } from "./fs-atomic.js";
import { log } from "./logger.js";
import {
type CachedSubscriptionPlan,
type SlimModelEntry,
readAllModelsCache,
} from "./providers/all-models-cache.js";
import { PROVIDER_TO_PREFIX } from "./providers/auto-route.js";
import { FIREBASE_CACHE_TTL_HOURS } from "./providers/cache-ttl.js";
import { ensureCatalogReady } from "./providers/catalog-client.js";
import {
catalogRouteMatchesProvider,
providerForCatalogRoute,
} from "./providers/catalog-route-bindings.js";
import {
CATALOG_V3_ACCEPT,
type CatalogV3Envelope,
parseCatalogV3Envelope,
} from "./providers/catalog-v3.js";
import type { ConnectionWire } from "./providers/connection-wire.js";
import { normaliseCatalogPayload } from "./providers/content-use.js";
import {
EFFORT_RECOMMENDATIONS_PATH,
writeEffortRecommendations,
} from "./providers/effort-recommendations.js";
import { compareByReleaseDateDesc } from "./providers/model-ordering.js";
import { nativeProviderForVendor } from "./providers/route-candidates.js";
import type { OpenRouterModel } from "./types.js";
// ─── Firebase Model Catalog Types ────────────────────────────────────────────
// These mirror `firebase/functions/src/schema.ts` but are defined locally so we
// don't cross the monorepo tsconfig boundary.
// ─── Recommendation tiers ────────────────────────────────────────────────────
/** One known recommendation tier and how listings present it. */
export interface RecommendationSectionDef {
/** The backend's `tier` value, verbatim. */
readonly recommendationTier: string;
readonly title: string;
readonly description?: string;
/** False keeps every model of this tier out of the Quick picks (R9: luxury is never automatic). */
readonly quickPickEligible: boolean;
}
/**
* The ONE ordered table of recommendation tiers this build knows. Section order,
* headings, descriptions and quick-pick eligibility are all read from here; no
* listing hardcodes a heading. The backend's tier set is OPEN: a `tier` value not
* in this table is skipped silently wherever it is read, so a new backend tier
* needs one row here and nothing else.
*/
export const RECOMMENDATION_SECTIONS = [
{ recommendationTier: "flagship", title: "Flagship", quickPickEligible: true },
{
recommendationTier: "cost_efficient",
title: "Cost-efficient",
description: "Best value: strong models at a much lower cost per task",
quickPickEligible: true,
},
{ recommendationTier: "lightweight", title: "Lightweight", quickPickEligible: true },
{
recommendationTier: "luxury",
title: "Luxury",
description: "Most capable, most expensive. Use for the hardest tasks",
quickPickEligible: false,
},
{ recommendationTier: "subscription", title: "Subscription", quickPickEligible: true },
] as const satisfies readonly RecommendationSectionDef[];
/** Exactly "flagship" | "cost_efficient" | "lightweight" | "luxury" | "subscription". */
export type RecommendationTier = (typeof RECOMMENDATION_SECTIONS)[number]["recommendationTier"];
const RECOMMENDATION_TIER_INDEX: ReadonlyMap<string, number> = new Map(
RECOMMENDATION_SECTIONS.map((section, index) => [section.recommendationTier, index])
);
function isRecommendationTier(value: unknown): value is RecommendationTier {
return typeof value === "string" && RECOMMENDATION_TIER_INDEX.has(value);
}
/**
* One row of the projected recommended-models list: one `(recommendationTier,
* model)` pair (subscription rows: one per route binding and plan). A model the
* backend lists in two tiers is two rows.
*/
export interface RecommendedModelEntry {
id: string;
name: string;
description: string;
provider: string;
/** The backend's recommendation tier, verbatim. */
recommendationTier: RecommendationTier;
/** Rank within `recommendationTier`, from 1. */
priority: number;
pricing: {
input: string;
output: string;
average: string;
};
context: string;
/**
* ISO release date, when the backend supplies one. Optional — the current
* `?catalog=recommended` payload omits it, in which case the freshness
* tiebreak in `groupRecommendedModels` degrades to version-parts-in-id.
*/
releaseDate?: string;
maxOutputTokens?: number | null;
modality?: string;
supportsTools?: boolean;
supportsReasoning?: boolean;
supportsVision?: boolean;
isModerated?: boolean;
recommended?: boolean;
/** Whether the model has a mapped connection on its vendor's native route. */
nativeRouteAvailable?: boolean;
subscription?: RecommendedSubscriptionRoute;
/**
* Every executable subscription route for this model, in preference order.
* Native Claude routes use a bare model command without a provider prefix.
*/
subscriptions?: RecommendedSubscriptionRoute[];
}
export type RecommendedRouteTier = "native" | "general" | "metered" | "aggregator";
/** A callable route projected from catalog v3 recommendations. */
export interface RecommendedSubscriptionRoute {
prefix?: string;
plan: string;
command: string;
planIds?: string[];
routingProvider?: string;
tier?: RecommendedRouteTier;
}
/**
* The recommended-models list projected from `?catalog=recommended`: what
* `--models-top --json` prints and what the disk cache holds.
*/
export interface RecommendedModelsDoc {
contractVersion?: 3;
generationId?: string;
/**
* claudish's own projection version ({@link RECOMMENDED_PROJECTION_VERSION}).
* A disk cache written by an older projection is rebuilt even within its
* generation: the `command` it holds may name a wire id the current rules
* would never choose.
*/
projectionVersion?: number;
version: string;
lastUpdated: string;
generatedAt?: string;
/**
* The recommendation tiers this build knows, in table order. On disk it is the
* WRITER's list: a reader that knows a tier missing from it refetches instead
* of showing a listing silently missing that section, and a reader that keeps
* the file replaces it with its own list (it drops rows of tiers it lacks).
*/
recommendationTiers?: string[];
source?: string;
models: RecommendedModelEntry[];
}
/**
* Confidence tier for source provenance — mirrors `ConfidenceTier` in
* models-index/functions/src/schema.ts.
*/
export type ConfidenceTier =
| "scrape_unverified"
| "scrape_verified"
| "aggregator_reported"
| "gateway_official"
| "api_official";
export type ReasoningModeCapabilities =
| {
status: "supported";
values: string[];
default?: string;
}
| {
status: "rejected" | "unknown";
};
export interface RouteReasoningCapabilities {
mode?: ReasoningModeCapabilities;
}
/**
* CLI-friendly aggregator entry — flattened view of `sources` keyed by the
* canonical CLI provider name. Mirrors `AggregatorEntry` in
* models-index/functions/src/schema.ts. Routing consults this to learn which
* aggregators (OpenRouter, Fireworks, etc.) serve a given model.
*/
export interface AggregatorEntry {
sourceProviderId: string;
sourceCollectorId: string;
confidence: ConfidenceTier;
routeStatus: "mapped" | "unmapped";
route?: { routeId: string; routeProfileId: string };
externalModelId?: string;
/**
* True per-aggregator price for this (provider, externalId), as served by the
* `?catalog=slim` endpoint. Present when the catalog knows this vendor's rate,
* omitted otherwise (so consumers show N/A rather than a wrong price). This is
* the gateway's actual rate, NOT the owner list price — an aggregator like
* OpenRouter/OpenCode Zen can charge differently from the model owner.
*/
pricing?: {
/** How to read the rest of this object. Absent means the price is unknown. */
type?: "flat" | "tiered" | "free" | "unavailable";
input?: number;
output?: number;
cachedRead?: number;
cachedWrite?: number;
imageInput?: number;
audioInput?: number;
batchDiscountPct?: number;
/**
* Ascending price bands by input size. The catalog guarantees the top-level
* `input`/`output` equal the first tier, verified on all 28 tiered
* connections of generations g-20260920154425586-418ad3dd and
* g-20260921062451697-f490edba (the latter being the first to carry the
* agreed `type` field name).
*/
tiers?: Array<{
maxInputTokens?: number;
input?: number;
output?: number;
cachedRead?: number;
cachedWrite?: number;
}>;
};
/**
* True per-aggregator context window (max input tokens) for this
* (provider, externalId), as served by the `?catalog=slim` endpoint. Present
* when a serving backend enforces a DIFFERENT window than the model's headline
* spec — e.g. the ChatGPT Codex OAuth backend (`openai-codex`) caps gpt-5.6-sol
* at ~372K while the OpenAI API serves the full 1.05M. Omitted when the
* aggregator matches the model default; consumers fall back to the top-level
* `contextWindow`.
*/
contextWindow?: number;
/** Reasoning behavior verified for this exact serving provider/model route. */
reasoning?: RouteReasoningCapabilities;
/**
* How to call this exact connection (catalog 3.7.0): API, output-limit field,
* reasoning encoding, mode and speed. Present on every mapped connection of a
* 3.7.0 generation; the only source of request decisions.
*/
wire?: ConnectionWire;
}
/**
* Per-vendor availability row. Distinguishes the model OWNER from the
* vendor that SERVES the model. Mirrors `VendorRecord` in
* models-index/functions/src/schema.ts. The Firestore `Timestamp` is
* degraded to `string | unknown` here so we don't pull firebase-admin into
* the CLI bundle.
*/
export interface VendorRecord {
vendor: string;
role: "owner" | "gateway" | "aggregator";
externalId: string;
confidence: ConfidenceTier;
lastSeen: string | unknown;
sourceUrl?: string;
pricing?: {
input?: number;
output?: number;
cachedRead?: number;
cachedWrite?: number;
imageInput?: number;
audioInput?: number;
batchDiscountPct?: number;
};
contextWindow?: number;
maxOutputTokens?: number;
}
/**
* Full model document from Firebase `?search=...` or `?provider=...`.
* Matches `ModelDoc` in models-index/functions/src/schema.ts.
*/
export interface ModelDoc {
modelId: string;
displayName?: string;
provider: string;
family?: string;
description?: string;
releaseDate?: string;
pricing?: {
input?: number;
output?: number;
inputCacheRead?: number;
inputCacheWrite?: number;
currency?: string;
unit?: string;
};
contextWindow?: number;
maxOutputTokens?: number;
/**
* IDs of subscription plans (e.g. "cognition-devin", "z-ai-glm-coding-plan")
* that include this model.
*
* NAME MATTERS: the backend sends `subscriptionPlanIds`. This field was declared
* as `availableInPlans` and read by nothing, so claudish was blind to it —
* which is how a subscription-only model with no published per-token rate came
* out as a bare "N/A" that reads as "unknown / not provisioned".
*/
subscriptionPlanIds?: string[];
/**
* Vendor's own prose explaining an ABSENT `pricing` — e.g. "Cognition does not
* publish standalone token pricing" / "Z.ai says the standalone API is coming
* soon". Missing pricing is usually a deliberate vendor fact, not a data gap,
* and this is the sentence that says which.
*/
pricingSummary?: string;
/** Upstream owner slug (e.g. "cognition", "z-ai"). Distinct from `provider`. */
owner?: string;
capabilities?: {
vision?: boolean;
thinking?: boolean;
tools?: boolean;
streaming?: boolean;
jsonMode?: boolean;
embedding?: boolean;
imageGeneration?: boolean;
audioInput?: boolean;
audioOutput?: boolean;
};
aliases?: string[];
status?: "active" | "deprecated" | "preview" | "unknown";
/**
* Multi-aggregator routing index. Optional, additive. Derived server-side
* from `sources` at merge time. Field is omitted when no aggregators
* contributed data for this model.
*/
aggregators?: AggregatorEntry[];
/**
* Per-vendor availability rows used by routing logic. Optional and
* additive — omitted when no vendor rows can be derived.
*/
vendors?: VendorRecord[];
}
// ─── Model metadata for --model flag resolution ──────────────────────────────
interface ModelMetadata {
name: string;
description: string;
priority: number;
provider: string;
}
// ─── Module caches ───────────────────────────────────────────────────────────
let _cachedModelInfo: Record<string, ModelMetadata> | null = null;
let _cachedModelIds: string[] | null = null;
let _cachedRecommendedModels: RecommendedModelsDoc | null = null;
// ─── Firebase config ─────────────────────────────────────────────────────────
const FIREBASE_BASE_URL = "https://us-central1-claudish-6da10.cloudfunctions.net/queryModels";
const FIREBASE_RECOMMENDED_URL = `${FIREBASE_BASE_URL}?catalog=recommended`;
/**
* Bumped when {@link projectRecommendations} would answer differently for the
* same generation. 1: content-use opt-in wire ids are never a `command`
* (`content-use.ts`); a projection written before that may hold one.
* 2: native shortcuts require a mapped connection on the vendor's native route.
*/
export const RECOMMENDED_PROJECTION_VERSION = 2;
/**
* The projected recommended-models list, on disk.
*
* `-v2`, not `recommended-models-cache.json`: the row shape changed (`category`
* removed, `recommendationTier` added). Older claudish builds sharing
* `~/.claudish` check only `contractVersion` and `generationId`, so they would
* accept a new-shape file under the old name and list every model as a fast
* variant. A new ROW SHAPE gets a new file; a new TIER does not (see
* `recommendationTiers`). This build never reads, writes or deletes the old file.
*/
export const RECOMMENDED_MODELS_CACHE_PATH = join(
homedir(),
".claudish",
"recommended-models-cache-v2.json"
);
const RECOMMENDED_FETCH_TIMEOUT_MS = 5000;
const SEARCH_FETCH_TIMEOUT_MS = 10000;
async function fetchCatalogPage<T>(
url: string,
timeoutMs: number,
generationId?: string
): Promise<CatalogV3Envelope<T>> {
const requestUrl = new URL(url);
if (generationId) requestUrl.searchParams.set("generationId", generationId);
const response = await fetch(requestUrl, {
headers: { Accept: CATALOG_V3_ACCEPT },
signal: AbortSignal.timeout(timeoutMs),
});
if (!response.ok) throw new Error(`Model catalog returned HTTP ${response.status}`);
const envelope = parseCatalogV3Envelope<T>(await response.json());
if (!envelope) throw new Error("Model catalog returned an invalid v3 response");
if (generationId && envelope.generationId !== generationId) {
throw new Error("Model catalog generation changed during the read");
}
// Every Firebase `ModelDoc` read passes through here, so this is where their
// content-use opt-in connections are set aside (`content-use.ts`).
return { ...envelope, data: normaliseCatalogPayload(envelope.data) };
}
async function fetchCatalogData<T>(
url: string,
timeoutMs: number,
generationId?: string
): Promise<T> {
return (await fetchCatalogPage<T>(url, timeoutMs, generationId)).data;
}
/**
* One element of `data.recommendations.entries`, as the backend sends it.
* `tier` is a plain string on purpose: the backend's tier set is open, and a
* value this build does not know is skipped, never rejected.
*/
export interface RecommendationWireEntry {
modelId: string;
tier: string;
/** Backend: `route` and `planId` are both present or both absent. */
route?: { routeId: string; routeProfileId: string };
planId?: string;
}
/** `data.recommendations` of `?catalog=recommended`. */
export interface RecommendationsWire {
contractVersion: number;
generationId: string;
/** Malformed elements are skipped; a non-array throws. */
entries: unknown[];
/**
* Recommended reasoning effort per model and task type. OPTIONAL and read only
* by `writeEffortRecommendations`, which tolerates any value: absent or
* malformed means no recommendations.
*/
efforts?: unknown;
}
/**
* The cloud models catalog of ONE generation, as far as the projection reads it:
* from each record `modelId`, `displayName`, `provider`, `contextWindow`,
* `releaseDate` and `aggregators[].route` / `.externalModelId`; from each plan `id`.
*/
export interface RecommendationCatalogSnapshot {
catalogGenerationId: string;
entries: SlimModelEntry[];
plans: CachedSubscriptionPlan[];
}
type KnownWireEntry = RecommendationWireEntry & { tier: RecommendationTier };
/** A usable wire entry, or null (not an object, no string modelId, or a tier this build does not know). */
function readWireEntry(value: unknown): KnownWireEntry | null {
if (!value || typeof value !== "object") return null;
const raw = value as Record<string, unknown>;
if (typeof raw.modelId !== "string" || !isRecommendationTier(raw.tier)) return null;
const rawRoute = raw.route as Record<string, unknown> | null | undefined;
const route =
rawRoute &&
typeof rawRoute === "object" &&
typeof rawRoute.routeId === "string" &&
typeof rawRoute.routeProfileId === "string"
? { routeId: rawRoute.routeId, routeProfileId: rawRoute.routeProfileId }
: undefined;
return {
modelId: raw.modelId,
tier: raw.tier,
...(route ? { route } : {}),
...(typeof raw.planId === "string" ? { planId: raw.planId } : {}),
};
}
/**
* Dedupe key of one entry: within a tier only, so a model listed in two tiers
* keeps a row in each. A subscription entry is one ROUTE BINDING under one PLAN,
* so two entries for one model on different routes, or on one route under two
* plans, are both kept.
*/
function recommendationDedupeKey(entry: KnownWireEntry): string {
return entry.tier === "subscription"
? JSON.stringify([
entry.tier,
entry.modelId,
entry.route?.routeId ?? null,
entry.route?.routeProfileId ?? null,
entry.planId ?? null,
])
: JSON.stringify([entry.tier, entry.modelId]);
}
/**
* Project `?catalog=recommended` onto the cloud models catalog of the same
* generation. Pure: reads no file and no network.
*
* Per entry, in API order: skip a malformed entry or a tier not in
* `RECOMMENDATION_SECTIONS` (silently: the tier set is open); skip a `modelId`
* absent from `catalog.entries` (every tier: an id the catalog does not know
* has no provider and no name); skip a repeated dedupe key; otherwise emit one
* row whose `recommendationTier` is the entry's tier, verbatim, and whose
* `priority` is its 1-based rank within that tier. Only a `subscription` entry
* whose route resolves to a command carries `subscription`/`subscriptions`.
*
* Throws on envelope faults only: `contractVersion !== 3`, `entries` not an
* array, or a catalog of a different generation.
*/
export function projectRecommendations(
recommendations: RecommendationsWire,
catalog: RecommendationCatalogSnapshot,
richModels: ModelDoc[] = [],
now: Date = new Date()
): RecommendedModelsDoc {
if (recommendations.contractVersion !== 3 || !Array.isArray(recommendations.entries)) {
throw new Error("Model catalog recommendations do not match v3");
}
// An empty catalog generation is the wrapper's "no slim cache" snapshot: never a match.
if (
!catalog.catalogGenerationId ||
catalog.catalogGenerationId !== recommendations.generationId
) {
throw new Error("Recommendation and model catalog generations differ");
}
const byId = new Map(catalog.entries.map((entry) => [entry.modelId, entry]));
const richById = new Map<string, ModelDoc>();
for (const model of richModels) {
if (!richById.has(model.modelId)) richById.set(model.modelId, model);
}
const seenKeys = new Set<string>();
const rankByTier = new Map<RecommendationTier, number>();
const models: RecommendedModelEntry[] = [];
for (const value of recommendations.entries) {
const recommended = readWireEntry(value);
if (!recommended) continue;
const model = byId.get(recommended.modelId);
if (!model) continue;
const key = recommendationDedupeKey(recommended);
if (seenKeys.has(key)) continue;
seenKeys.add(key);
const priority = (rankByTier.get(recommended.tier) ?? 0) + 1;
rankByTier.set(recommended.tier, priority);
const rich = richById.get(recommended.modelId);
const nativeProvider = nativeProviderForVendor(rich?.provider ?? model.provider ?? "");
const nativeRouteAvailable = Boolean(
nativeProvider &&
model.aggregators?.some(
(connection) =>
connection.routeStatus === "mapped" &&
catalogRouteMatchesProvider(connection.route, nativeProvider)
)
);
const subscription =
recommended.tier === "subscription"
? subscriptionRouteFor(recommended, model, catalog.plans)
: undefined;
models.push({
id: recommended.modelId,
name: rich?.displayName ?? model.displayName ?? recommended.modelId,
description: rich?.description ?? "",
provider: rich?.provider ?? model.provider ?? "",
nativeRouteAvailable,
recommendationTier: recommended.tier,
priority,
pricing: {
input: typeof rich?.pricing?.input === "number" ? `$${rich.pricing.input}/1M` : "N/A",
output: typeof rich?.pricing?.output === "number" ? `$${rich.pricing.output}/1M` : "N/A",
average:
typeof rich?.pricing?.input === "number" && typeof rich?.pricing?.output === "number"
? `$${((rich.pricing.input + rich.pricing.output) / 2).toFixed(2)}/1M`
: "N/A",
},
context: rich?.contextWindow
? String(rich.contextWindow)
: model.contextWindow
? String(model.contextWindow)
: "N/A",
releaseDate: model.releaseDate,
// Capabilities come from the slim entry of the same generation. A field the
// catalog does not publish stays absent: unknown is never written as false.
...(typeof model.supportsTools === "boolean" ? { supportsTools: model.supportsTools } : {}),
...(typeof model.reasoning?.supported === "boolean"
? { supportsReasoning: model.reasoning.supported }
: {}),
...(typeof model.supportsVision === "boolean"
? { supportsVision: model.supportsVision }
: {}),
...(subscription ? { subscription, subscriptions: [subscription] } : {}),
});
}
const stamp = now.toISOString();
return {
contractVersion: 3,
generationId: recommendations.generationId,
projectionVersion: RECOMMENDED_PROJECTION_VERSION,
version: recommendations.generationId,
lastUpdated: stamp,
generatedAt: stamp,
recommendationTiers: RECOMMENDATION_SECTIONS.map((section) => section.recommendationTier),
models,
};
}
/**
* The callable route of one subscription entry, or undefined when its route
* binding names no claudish provider or the model has no connection on it with
* a wire id. A subscription row without one is still a row.
*/
function subscriptionRouteFor(
recommended: KnownWireEntry,
model: SlimModelEntry,
plans: CachedSubscriptionPlan[]
): RecommendedSubscriptionRoute | undefined {
if (!recommended.route) return undefined;
const provider = providerForCatalogRoute(recommended.route);
if (!provider) return undefined;
const connection = model.aggregators?.find(
(candidate) =>
candidate.route?.routeId === recommended.route?.routeId &&
candidate.route?.routeProfileId === recommended.route?.routeProfileId
);
const prefix = PROVIDER_TO_PREFIX[provider] ?? provider;
if (!connection?.externalModelId) return undefined;
const command =
provider === "native-anthropic"
? connection.externalModelId
: `${prefix}@${connection.externalModelId}`;
const plan = plans.find((candidate) => candidate.id === recommended.planId);
return {
...(provider === "native-anthropic" ? {} : { prefix }),
plan: plan?.id ?? recommended.planId ?? provider,
command,
planIds: recommended.planId ? [recommended.planId] : [],
routingProvider: provider,
tier: provider === "native-anthropic" ? "native" : "general",
};
}
/**
* The production wrapper: the slim cache, then the projection. The envelope and
* generation checks live in `projectRecommendations` only; a missing cache is
* passed as an empty snapshot with no generation, which fails its generation
* check ("generations differ") after the envelope check, as before.
*/
function recommendationProjection(
recommendations: RecommendationsWire,
richModels: ModelDoc[] = []
): RecommendedModelsDoc {
const cache = readAllModelsCache();
return projectRecommendations(
recommendations,
cache
? {
catalogGenerationId: cache.catalogGenerationId,
entries: cache.entries,
plans: cache.plans,
}
: { catalogGenerationId: "", entries: [], plans: [] },
richModels
);
}
// ─── Disk-cache reader ───────────────────────────────────────────────────────
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
function isStringArray(value: unknown): value is string[] {
return Array.isArray(value) && value.every((item) => typeof item === "string");
}
function isRouteObject(value: unknown): value is RecommendedSubscriptionRoute {
return (
isRecord(value) &&
typeof value.plan === "string" &&
typeof value.command === "string" &&
(value.prefix === undefined || typeof value.prefix === "string") &&
(value.planIds === undefined || isStringArray(value.planIds))
);
}
/** A row every consumer can dereference without a TypeError, of a tier this build knows. */
function isUsableRow(value: unknown): value is RecommendedModelEntry {
if (!isRecord(value)) return false;
if (typeof value.id !== "string" || value.id.length === 0) return false;
if (!isRecommendationTier(value.recommendationTier)) return false;
if (typeof value.priority !== "number" || !Number.isFinite(value.priority)) return false;
if (
typeof value.name !== "string" ||
typeof value.description !== "string" ||
typeof value.provider !== "string" ||
typeof value.context !== "string"
) {
return false;
}
const pricing = value.pricing;
if (
!isRecord(pricing) ||
typeof pricing.input !== "string" ||
typeof pricing.output !== "string" ||
typeof pricing.average !== "string"
) {
return false;
}
if (value.releaseDate !== undefined && typeof value.releaseDate !== "string") return false;
if (value.subscription !== undefined && !isRouteObject(value.subscription)) return false;
if (
value.subscriptions !== undefined &&
!(Array.isArray(value.subscriptions) && value.subscriptions.every(isRouteObject))
) {
return false;
}
return true;
}
/**
* Read a parsed disk-cache value. Returns a NEW doc holding only usable rows, or
* null. Never throws; never mutates `value`.
*
* Doc level (failure → null, so the caller refetches): contract 3, string
* `generationId`/`version`/`lastUpdated`/`generatedAt`, array `models`, and a
* `recommendationTiers` that lists EVERY tier of this build's table. A file whose
* writer did not know one of this build's tiers may have dropped that tier's rows.
*
* Row level (failure → that row skipped): a row of a tier a NEWER build knows is
* skipped here, not fatal, and so is a row a consumer could not dereference.
* Zero rows left → null. The returned `recommendationTiers` is this build's
* table, so it names exactly the tiers its rows can carry.
*/
export function readProjectedRecommendationsDoc(value: unknown): RecommendedModelsDoc | null {
if (!isRecord(value)) return null;
if (value.contractVersion !== 3) return null;
if (
typeof value.generationId !== "string" ||
typeof value.version !== "string" ||
typeof value.lastUpdated !== "string" ||
typeof value.generatedAt !== "string" ||
!Array.isArray(value.models)
) {
return null;
}
const writerTiers = value.recommendationTiers;
if (!isStringArray(writerTiers)) return null;
if (!RECOMMENDATION_SECTIONS.every((section) => writerTiers.includes(section.recommendationTier)))
return null;
const models = value.models.filter(isUsableRow);
if (models.length === 0) return null;
// Report the tiers THIS build kept, not the writer's: a newer writer's extra
// tier had its rows dropped above, so its list would no longer match `models`.
return {
...(value as unknown as RecommendedModelsDoc),
recommendationTiers: RECOMMENDATION_SECTIONS.map((section) => section.recommendationTier),
models,
};
}
/**
* Steps 2-4 of the disk-cache read, shared by both read paths: absent file,
* unparsable file or unusable doc → null. The empty doc of
* `getRecommendedModelsSync` never reaches the reader: it is a return value,
* never written to disk.
*/
function readRecommendedModelsCacheFile(): RecommendedModelsDoc | null {
if (!existsSync(RECOMMENDED_MODELS_CACHE_PATH)) return null;
let parsed: unknown;
try {
parsed = JSON.parse(readFileSync(RECOMMENDED_MODELS_CACHE_PATH, "utf-8"));
} catch (err) {
log(
`[recommended] unreadable ${RECOMMENDED_MODELS_CACHE_PATH}: ${err instanceof Error ? err.message : String(err)}`
);
return null;
}
// A projection an older build wrote within this same generation may hold a
// `command` the current rules would never choose (a content-use opt-in wire
// id): rebuild it. Checked on the DISK copy only — the doc reader itself
// judges shape, and a freshly projected doc always carries this version.
if (!isRecord(parsed) || parsed.projectionVersion !== RECOMMENDED_PROJECTION_VERSION) {
// Another claudish build shares this file: its projection is not read, and the
// list_models fallback then has no list. Say which version was found.
log(
`[recommended] ${RECOMMENDED_MODELS_CACHE_PATH} has projection version ${isRecord(parsed) ? String(parsed.projectionVersion) : "none"}; this build reads ${RECOMMENDED_PROJECTION_VERSION}`
);
return null;
}
return readProjectedRecommendationsDoc(parsed);
}
/**
* The recommended list last written to disk, whatever its generation or age: the
* answer for a caller whose fetch failed (MCP `list_models`). It must say that the
* list is older; `generationId` names the generation it came from. Null when no
* usable file exists.
*/
export function readLastRecommendedModels(): RecommendedModelsDoc | null {
const doc = readRecommendedModelsCacheFile();
return doc && doc.models.length > 0 ? doc : null;
}
// ─── Recommended models grouping + formatting helpers ───────────────────────
/**
* One model in one section. `primary` is that model's row of the section's
* tier; `subscriptions` is every `recommendationTier: "subscription"` row with
* the same id anywhere in the doc, in doc order, so the model's subscription
* routes show on its via/Access line in whichever section it appears.
*/
export interface RecommendedModelGroup {
id: string;
primary: RecommendedModelEntry;
subscriptions: RecommendedModelEntry[];
}
/** One non-empty recommendation tier, ready to render. */
export interface RecommendedSection {
recommendationTier: RecommendationTier;
title: string;
description?: string;
/** Never empty; sorted by `primary.priority`. */
groups: RecommendedModelGroup[];
}
function sectionDefFor(tier: string): RecommendationSectionDef | undefined {
const index = RECOMMENDATION_TIER_INDEX.get(tier);
return index === undefined ? undefined : RECOMMENDATION_SECTIONS[index];
}
/**
* Sections in `RECOMMENDATION_SECTIONS` order, empty ones omitted. Does not
* mutate `entries`.
*
* **Ordering.** The backend's curated ranking stays PRIMARY; freshness is only
* the tiebreak (the repo-wide model-ordering rule). Within a section groups sort
* by `priority`, which is the rank within that tier, then
* `compareByReleaseDateDesc` on a genuine tie (never between rows of one
* projection, whose priorities are distinct per tier). A model listed in two
* tiers is a group in each of the two sections. Rows of a tier not in the table
* are ignored.
*/
export function groupRecommendedModels(
entries: readonly RecommendedModelEntry[]
): RecommendedSection[] {
const subscriptionRowsById = new Map<string, RecommendedModelEntry[]>();
for (const entry of entries) {
if (entry.recommendationTier !== "subscription") continue;
const list = subscriptionRowsById.get(entry.id);
if (list) list.push(entry);
else subscriptionRowsById.set(entry.id, [entry]);
}
const sections: RecommendedSection[] = [];
for (const def of RECOMMENDATION_SECTIONS) {
const primaryById = new Map<string, RecommendedModelEntry>();
for (const entry of entries) {
if (entry.recommendationTier !== def.recommendationTier) continue;
const current = primaryById.get(entry.id);
if (!current || entry.priority < current.priority) primaryById.set(entry.id, entry);
}
if (primaryById.size === 0) continue;
const groups: RecommendedModelGroup[] = [...primaryById.values()].map((primary) => ({
id: primary.id,
primary,
subscriptions: subscriptionRowsById.get(primary.id) ?? [],
}));
groups.sort(
(a, b) =>
a.primary.priority - b.primary.priority || compareByReleaseDateDesc(a.primary, b.primary)
);
const description: string | undefined = "description" in def ? def.description : undefined;
sections.push({
recommendationTier: def.recommendationTier,
title: def.title,
...(description ? { description } : {}),
groups,
});
}
return sections;
}
/**
* The Quick picks input: primaries of `quickPickEligible` sections, in section
* order then group order, unique by id (first kept), minus EVERY id that also
* appears in a non-eligible section. "Most capable" is the priciest candidate,
* so a luxury model let in through another section would be picked by
* construction. `computeQuickPicks` sorts stably, so a tie goes to the earlier
* candidate.
*/
export function quickPickCandidates(
sections: readonly RecommendedSection[]
): RecommendedModelEntry[] {
const excluded = new Set<string>();
for (const section of sections) {
if (sectionDefFor(section.recommendationTier)?.quickPickEligible === false) {
for (const group of section.groups) excluded.add(group.id);
}
}
const seen = new Set<string>();
const candidates: RecommendedModelEntry[] = [];
for (const section of sections) {
if (sectionDefFor(section.recommendationTier)?.quickPickEligible !== true) continue;
for (const group of section.groups) {
if (excluded.has(group.id) || seen.has(group.id)) continue;
seen.add(group.id);
candidates.push(group.primary);
}
}
return candidates;
}
/**
* One row per model id, in section order then priority, first row winning.
* For surfaces that list MODELS rather than sections (`--model` help, the
* picker's fallback list). Does not mutate `entries`.
*/
export function uniqueRecommendedModels(
entries: readonly RecommendedModelEntry[]
): RecommendedModelEntry[] {
const sectionIndex = (entry: RecommendedModelEntry): number =>
RECOMMENDATION_TIER_INDEX.get(entry.recommendationTier) ?? Number.MAX_SAFE_INTEGER;
const ordered = [...entries].sort(
(a, b) => sectionIndex(a) - sectionIndex(b) || a.priority - b.priority
);
const seen = new Set<string>();
const unique: RecommendedModelEntry[] = [];
for (const entry of ordered) {
if (seen.has(entry.id)) continue;
seen.add(entry.id);
unique.push(entry);
}
return unique;
}
/**
* Compute the ordered, deduped list of routing prefixes for a group:
* [native-provider-prefix, ...subscription-prefixes]
* Each prefix is bare (no `@`). `getNativePrefix` receives the lower-cased
* Firebase slug and returns the native shortcut or null if the provider is
* unknown / has no shortcut.
*/
export function collectRoutingPrefixes(
group: RecommendedModelGroup,
getNativePrefix: (firebaseSlug: string) => string | null
): string[] {
const slug = (group.primary.provider || "").toLowerCase();
const native = group.primary.nativeRouteAvailable === false ? null : getNativePrefix(slug);
const seen = new Set<string>();
const out: string[] = [];
if (native) {
out.push(native);
seen.add(native);
}
// `group.subscriptions` is ROWS (RecommendedModelEntry[], :282).
// `row.subscriptions` is ROUTES. Same word, different things — renamed here
// because reading one as the other reintroduces exactly the defect being fixed.
for (const subscriptionRow of group.subscriptions) {
// Plural first. An EMPTY plural is treated as an absent one: an empty array
// and a missing field are indistinguishable as intent, and falling back can
// only re-add a route the backend itself declared — it can never invent one.
// NOT `??`: that falls through only on null/undefined, so an empty plural
// would silently swallow a present singular.
const routes =
subscriptionRow.subscriptions && subscriptionRow.subscriptions.length > 0
? subscriptionRow.subscriptions
: subscriptionRow.subscription
? [subscriptionRow.subscription]
: [];
const orderedRoutes = [...routes].sort(compareRecommendedRoutes);
for (const route of orderedRoutes) {
// `route?.` and not `route.`: these are WIRE elements. TypeScript types the
// array as non-nullable objects (:59) so it will not warn, but a JSON `null`
// inside `subscriptions[]` would throw a TypeError out of this function and
// take down the entire list_models render (mcp-server.ts) and the CLI listing
// (cli.ts) instead of dropping one route. The code this replaced read
// `sub.subscription?.prefix`; that guard is not optional here. This whole
// change exists because the wire omits fields we assumed were present.
const p = route?.prefix;
// LOAD-BEARING. Four native Claude rows ship a subscription entry with no
// `prefix` at all; without this they emit `undefined@claude-opus-5`.
if (!p || seen.has(p)) continue;
seen.add(p);
out.push(p);
}
}
return out;
}
const RECOMMENDED_ROUTE_TIER_ORDER: Record<RecommendedRouteTier, number> = {
native: 0,
general: 1,
metered: 2,
aggregator: 3,
};
function compareRecommendedRoutes(
left: RecommendedSubscriptionRoute,
right: RecommendedSubscriptionRoute
): number {
const leftRank =
left?.tier && Object.hasOwn(RECOMMENDED_ROUTE_TIER_ORDER, left.tier)
? RECOMMENDED_ROUTE_TIER_ORDER[left.tier]
: Number.MAX_SAFE_INTEGER;
const rightRank =
right?.tier && Object.hasOwn(RECOMMENDED_ROUTE_TIER_ORDER, right.tier)
? RECOMMENDED_ROUTE_TIER_ORDER[right.tier]
: Number.MAX_SAFE_INTEGER;
return leftRank - rightRank;
}
/** Parse "$1.32/1M" → 1.32, "FREE" → 0, "N/A"/"varies"/undefined → Infinity */
export function parsePriceAvg(s?: string): number {
if (!s || s === "N/A") return Number.POSITIVE_INFINITY;
if (s === "FREE") return 0;
const m = s.match(/\$([\d.]+)/);
return m ? Number.parseFloat(m[1]) : Number.POSITIVE_INFINITY;
}
/** Parse "196K" → 196000, "1M" → 1000000, "1048K" → 1048000 */
export function parseCtx(s?: string): number {
if (!s || s === "N/A") return 0;
const upper = s.toUpperCase();
if (upper.includes("M")) return Number.parseFloat(upper) * 1_000_000;
if (upper.includes("K")) return Number.parseFloat(upper) * 1_000;
return Number.parseInt(s, 10) || 0;
}
/**
* Normalize a raw pricing string from Firebase to what the renderers display.
* - "$0.00/1M" or "FREE" → "FREE"
* - strings containing "-1000000" (legacy-bug pattern) → "varies"
* - otherwise returned unchanged (falling back to "N/A")
*/
export function normalizePricingDisplay(raw?: string): string {
const pricing = raw || "N/A";
if (pricing.includes("-1000000")) return "varies";
if (pricing === "$0.00/1M" || pricing === "FREE") return "FREE";
return pricing;
}
/**
* Render a model's price for a LISTING, using the model's access route to
* explain an absent rate instead of printing a bare "N/A".
*
* "N/A" is not a data gap for these models — it is the truthful answer, and the
* catalog says why per model ("Cognition does not publish standalone token
* pricing…", "Z.ai says the standalone API is coming soon…"). Both are
* subscription-only models with no published per-token rate. Printing the raw
* sentinel loses that entirely and reads as "unknown / never provisioned",
* which is exactly how `swe-1.7` was triaged as unroutable while `[email protected]`
* was serving 509-token replies.
*
* So when there is no rate AND the catalog names a subscription that includes
* the model, say `SUB` — the same label the picker already uses for a flat-rate
* provider (see `SUBSCRIPTION_PROVIDERS`) — qualified by the plan name. A model
* with neither a rate nor a subscription keeps "N/A", which now genuinely means
* "we don't know" rather than doubling as "subscription-only".
*
* Deliberately NOT a per-model cloud lookup: `subscription` already rides along
* on the recommended catalog. `catalog-client.ts` is explicit that re-querying
* the cloud one model at a time to fill gaps is not how this works.
*/
export function formatListingPrice(
entry: {
pricing?: { average?: string };
subscription?: { plan?: string };
},
opts?: { compact?: boolean }
): string {
const rate = normalizePricingDisplay(entry.pricing?.average);
if (rate !== "N/A") return rate;
const plan = entry.subscription?.plan;
if (!plan) return "N/A";
// `compact` exists for FIXED-WIDTH tables. Plan names are unbounded in
// practice — "Devin" is 5, "Claude Code" is 11, so `SUB (Claude Code)` is 17
// against a 10-wide column — and a price cell that overflows shoves every
// column after it out of alignment for that ONE row, which looks like a
// rendering bug rather than a longer name. Markdown surfaces have no column
// to break, so they get the plan.
return opts?.compact ? "SUB" : `SUB (${plan})`;
}
/**
* Pick highlights from a deduped list of primary entries. Any field that can't
* be computed is returned as null so callers can skip the line.
*/
export interface QuickPicks {
budget: RecommendedModelEntry | null;
largeContext: RecommendedModelEntry | null;
mostCapable: RecommendedModelEntry | null;
visionCoding: RecommendedModelEntry | null;
agentic: RecommendedModelEntry | null;
}
export function computeQuickPicks(primaries: RecommendedModelEntry[]): QuickPicks {
if (primaries.length === 0) {
return {
budget: null,
largeContext: null,
mostCapable: null,
visionCoding: null,
agentic: null,
};
}
// Budget: cheapest non-FREE (skip FREE because they're typically gateways)
const priced = primaries
.filter((m) => {
const p = parsePriceAvg(m.pricing?.average);
return p > 0 && p !== Number.POSITIVE_INFINITY;
})
.sort((a, b) => parsePriceAvg(a.pricing?.average) - parsePriceAvg(b.pricing?.average));
const budget = priced[0] ?? null;
// Large context: max parseCtx
const byCtx = [...primaries].sort((a, b) => parseCtx(b.context) - parseCtx(a.context));
const largeContext = byCtx[0] ?? null;
// Most capable: priciest
const byPrice = [...primaries].sort(
(a, b) => parsePriceAvg(b.pricing?.average) - parsePriceAvg(a.pricing?.average)
);
const mostCapable =
byPrice.find((m) => parsePriceAvg(m.pricing?.average) !== Number.POSITIVE_INFINITY) ?? null;
// Vision + code: first with vision, excluding budget/priciest
const visionCoding =
primaries.find(
(m) => m.supportsVision === true && m.id !== budget?.id && m.id !== mostCapable?.id
) ?? null;
// Agentic: first with reasoning, excluding priciest
const agentic =
primaries.find((m) => m.supportsReasoning === true && m.id !== mostCapable?.id) ?? null;
return { budget, largeContext, mostCapable, visionCoding, agentic };
}
// ─── Recommended models loader ───────────────────────────────────────────────
/**
* Load the recommended models doc asynchronously, with Firebase as the primary source.
*
* Resolution order:
* 1. In-memory cache (unless forceRefresh)
* 2. Disk cache at RECOMMENDED_MODELS_CACHE_PATH, read through
* `readProjectedRecommendationsDoc` (24h TTL via FIREBASE_CACHE_TTL_HOURS:
* claudish's own refetch interval, not the backend's evidence lifetime)
* 3. Firebase ?catalog=recommended (writes disk cache on success, and the
* efforts sidecar at `effortsPath` for the generation it read)
*
* Throws when all three tiers fail. The bundled fallback was removed in commit
* 5 of the model-catalog and routing redesign — Firebase is the single catalog
* source now (see plan §A and CLAUDE.md).
*/
export async function getRecommendedModels(
opts: { forceRefresh?: boolean; effortsPath?: string } = {}
): Promise<RecommendedModelsDoc> {
const { forceRefresh = false, effortsPath = EFFORT_RECOMMENDATIONS_PATH } = opts;
const cached = _cachedRecommendedModels;
// Tier 1: in-memory cache
if (
!forceRefresh &&
cached &&
cached.generationId === readAllModelsCache()?.catalogGenerationId
) {
return cached;
}
// Tier 2: disk cache (if fresh)
// Firebase-derived data — OK to cache locally per the catalog policy.
// TTL shared with all other Firebase caches via FIREBASE_CACHE_TTL_HOURS.
// An absent, unparsable or unusable file falls through to Firebase.
if (!forceRefresh) {
const cacheData = readRecommendedModelsCacheFile();
if (
cacheData &&
cacheData.generationId === readAllModelsCache()?.catalogGenerationId &&
isFreshEnough(cacheData)
) {
_cachedRecommendedModels = cacheData;
return cacheData;
}
}
// Tier 3: Firebase fetch
let fetchFailure: unknown;
try {
await ensureCatalogReady(20000);
const generationId = readAllModelsCache()?.catalogGenerationId;
if (!generationId) throw new Error("No complete v3 model and plan snapshot");
const response = await fetchCatalogData<{
mode: "recommended";
recommendations: Parameters<typeof recommendationProjection>[0];
}>(FIREBASE_RECOMMENDED_URL, RECOMMENDED_FETCH_TIMEOUT_MS, generationId);
if (response.mode !== "recommended") throw new Error("Unexpected recommendation mode");
if (response.recommendations.generationId !== generationId) {
throw new Error("Recommendation and model catalog generations differ");
}
// Before the top100 fetch, so a top100 failure cannot cost the efforts of a
// generation already read. Written even when the field is absent: the
// generation then says "none" (`efforts: {}`).
try {
writeEffortRecommendations(generationId, response.recommendations.efforts, effortsPath);
} catch (err) {
// A sidecar write failure does not invalidate the fetched recommendations,
// but it is logged: otherwise it reads only as `no-sidecar` later.
log(
`[effort] sidecar write failed for generation ${generationId}: ${err instanceof Error ? err.message : String(err)}`
);
}
const top100 = await fetchCatalogData<{ mode: "top100"; models: ModelDoc[] }>(
`${FIREBASE_BASE_URL}?catalog=top100`,
RECOMMENDED_FETCH_TIMEOUT_MS,
generationId
);
const data = recommendationProjection(response.recommendations, top100.models);
if (data.models.length > 0) {
_cachedRecommendedModels = data;
try {
writeFileAtomic(RECOMMENDED_MODELS_CACHE_PATH, JSON.stringify(data));
} catch (err) {
// A disk write failure does not invalidate the fetched result, but the
// next process then refetches, and only this line says why.
log(
`[recommended] cache write failed: ${err instanceof Error ? err.message : String(err)}`
);
}
return data;
}
} catch (error) {
fetchFailure = error;
}
throw new Error(
`Unable to load v3 recommended models: ${fetchFailure instanceof Error ? fetchFailure.message : "empty recommendation projection"}`
);
}
/**
* Synchronous accessor for the recommended models doc.
*
* Tiers (no network):
* 1. In-memory cache
* 2. Disk cache, read through `readProjectedRecommendationsDoc`, same
* generation and freshness checks as the async path
*
* Sync access is best-effort; bundled fallback removed per the Firebase-only
* catalog rule. Help text degrades to an empty doc if Firebase has never been
* reached. Callers (`loadModelInfo()`, `getAvailableModels()` for `--model`
* flag help) handle empty data.
*/
export function getRecommendedModelsSync(): RecommendedModelsDoc {
const generationId = readAllModelsCache()?.catalogGenerationId;
const cached = _cachedRecommendedModels;
if (cached && cached.generationId === generationId) return cached;
// An absent, unparsable or unusable file gives the empty doc. The empty doc is
// a RETURN value only: it is never written to disk, so it is never read back.
const cacheData = readRecommendedModelsCacheFile();
if (cacheData && cacheData.generationId === generationId && isFreshEnough(cacheData)) {
_cachedRecommendedModels = cacheData;
return cacheData;
}
return { version: "0", lastUpdated: "", models: [] };
}
/**
* Fetches the current recommendation projection — fetches the Firebase catalog and warms caches.
* Used by proxy-server.ts to kick off the background warm on startup.
*/
export async function warmRecommendedModels(): Promise<RecommendedModelsDoc | null> {
try {
return await getRecommendedModels({ forceRefresh: true });
} catch (err) {
log(`[recommended] warm failed: ${err instanceof Error ? err.message : String(err)}`);
return null;
}
}
function isFreshEnough(doc: RecommendedModelsDoc): boolean {
const generatedAt = doc.generatedAt;
if (!generatedAt) return false;
const ageHours = (Date.now() - new Date(generatedAt).getTime()) / (1000 * 60 * 60);
return ageHours <= FIREBASE_CACHE_TTL_HOURS;
}
// ─── On-demand Firebase search API ───────────────────────────────────────────
/**
* Substring search across Firebase's model catalog (modelId, displayName, aliases).
* Network-only — no local caching. Callers handle error UX.
*/
export async function searchModels(query: string, limit = 50): Promise<ModelDoc[]> {
const url = `${FIREBASE_BASE_URL}?search=${encodeURIComponent(
query
)}&limit=${limit}&status=active`;
const data = await fetchCatalogData<{ models?: ModelDoc[]; total?: number }>(
url,
SEARCH_FETCH_TIMEOUT_MS
);
return data.models ?? [];
}
/**
* Provider-scoped substring search across Firebase's model catalog.
* Uses the same queryModels endpoint but narrows results to one provider slug.
*/
export async function searchModelsByProvider(
provider: string,
query: string,
limit = 50
): Promise<ModelDoc[]> {
const url = `${FIREBASE_BASE_URL}?provider=${encodeURIComponent(
provider
)}&search=${encodeURIComponent(query)}&limit=${limit}&status=active`;
const data = await fetchCatalogData<{ models?: ModelDoc[]; total?: number }>(
url,
SEARCH_FETCH_TIMEOUT_MS
);
return data.models ?? [];
}
/**
* Look up a single model by its canonical ID (or alias) via Firebase search.
* Returns null if not found, throws on network error.
*/
export async function getModelByIdFromFirebase(modelId: string): Promise<ModelDoc | null> {
const url = `${FIREBASE_BASE_URL}?modelId=${encodeURIComponent(modelId)}`;
const data = await fetchCatalogData<{ mode: "exact"; model: ModelDoc | null }>(
url,
SEARCH_FETCH_TIMEOUT_MS
);
return data.mode === "exact" ? data.model : null;
}
/**
* A ranked entry from `?catalog=top100` — a full `ModelDoc` augmented with
* a 1-indexed `rank` and composite `score`. Shape mirrors the JSON response
* emitted by `firebase/functions/src/query-handler.ts`.
*/
export interface Top100Entry extends ModelDoc {
rank: number;
score: number;
/** Populated only when `?includeScores=1` is passed. */
scoreBreakdown?: {
total: number;
popularity: number;
recency: number;
generation: number;
capabilities: number;
context: number;
confidence: number;
};
}
/**
* Full response envelope for `?catalog=top100`. Unlike the
* `?catalog=recommended` endpoint this is a flat ranked list of raw
* `ModelDoc`s — it is NOT compatible with `RecommendedModelsDoc` or the
* grouping helpers (groupRecommendedModels, collectRoutingPrefixes,
* computeQuickPicks) which all expect `RecommendedModelEntry`.
*/
export interface Top100Response {
models: Top100Entry[];
total: number;
poolSize: number;
scoring: {
weights: {
popularity: number;
recency: number;
generation: number;
capabilities: number;
context: number;
confidence: number;
};
};
}
/**
* Fetch the top-100 ranked models from Firebase. Network-only — meant to be
* fresh on every `--models` call; response is small (~50KB) so no disk
* cache is maintained.
*/
export async function getTop100Models(): Promise<Top100Response> {
const url = `${FIREBASE_BASE_URL}?catalog=top100`;
const data = await fetchCatalogData<Top100Response>(url, SEARCH_FETCH_TIMEOUT_MS);
return data;
}
/**
* Response from Firebase `?catalog=providers`. Each entry is a provider
* slug and the number of active models attributed to that provider.
* Sorted by count desc.
*/
export interface ProviderListEntry {
slug: string;
count: number;
}
/**
* Fetch the list of active providers and their model counts.
* Powers the CLI `--providers` command.
*/
export async function getProviderList(): Promise<ProviderListEntry[]> {
const url = `${FIREBASE_BASE_URL}?catalog=providers`;
const data = await fetchCatalogData<{ providers?: ProviderListEntry[] }>(
url,
SEARCH_FETCH_TIMEOUT_MS
);
return data.providers ?? [];
}
/** Fetch every active model for a provider from one pinned generation. */
export async function getModelsByProvider(provider: string, pageSize = 200): Promise<ModelDoc[]> {
const base = `${FIREBASE_BASE_URL}?provider=${encodeURIComponent(provider)}&status=active&limit=${pageSize}`;
return fetchPinnedModelDocs(base, "provider catalog");
}
/**
* Every row of one cursor-paginated `queryModels` read, pinned to ONE generation.
*
* Shared by {@link getModelsByProvider} and {@link getAllModelDocs} because the
* checks are the subtle part and must not drift between two copies: the total
* may not change mid-read, a cursor may not repeat, and the rows collected must
* match the total with no id twice. `label` only names the read in the errors.
*/
async function fetchPinnedModelDocs(base: string, label: string): Promise<ModelDoc[]> {
const Label = label.charAt(0).toUpperCase() + label.slice(1);
const models: ModelDoc[] = [];
const seenCursors = new Set<string>();
let cursor: string | undefined;
let generationId: string | undefined;
let expectedTotal: number | undefined;
for (let page = 0; page < 40; page++) {
const url = new URL(base);
if (cursor) url.searchParams.set("cursor", cursor);
const envelope = await fetchCatalogPage<{
models: ModelDoc[];
total: number;
nextCursor?: string;
}>(url.toString(), SEARCH_FETCH_TIMEOUT_MS, generationId);
if (!Array.isArray(envelope.data.models) || !Number.isSafeInteger(envelope.data.total)) {
throw new Error(`Incomplete ${label} response`);
}
generationId = envelope.generationId;
expectedTotal ??= envelope.data.total;
if (envelope.data.total !== expectedTotal)
throw new Error(`${Label} total changed during pagination`);
models.push(...envelope.data.models);
const nextCursor = envelope.data.nextCursor;
if (!nextCursor) {
if (
models.length !== expectedTotal ||
new Set(models.map((model) => model.modelId)).size !== models.length
) {
throw new Error(`Incomplete ${label} snapshot`);
}
return models;
}
if (seenCursors.has(nextCursor)) throw new Error(`${Label} cursor repeated`);
seenCursors.add(nextCursor);
cursor = nextCursor;
}
throw new Error(`${Label} exceeded the pagination limit`);
}
/**
* Every active model the cloud models catalog knows, in as few pages as it allows.
*
* WHY A BULK READ RATHER THAN N QUERIES. The picker needs one editorial fact per
* model — the description — for every row it can draw. The slim catalog
* (`?catalog=slim`, the file behind `all-models.json`) deliberately carries none:
* `model-catalog.ts:servedByVendor` says so in its own doc comment. Asking per
* model, or per provider, is the fan-out this picker already measured at
* 10 018 ms.
*
* A v3 read like every other query here: the contract `Accept` header, cursor
* pages pinned to one generation (via {@link fetchPinnedModelDocs}). A bare
* `fetch` with no `Accept` is refused outright — measured 2026-09-18, HTTP 426
* `catalog_client_upgrade_required`. MEASURED 2026-09-23 against the live v3
* endpoint with this exact query: the rich projection serves at most 200 rows a
* page (`limit=1000` returned 200 of 1267, plus a `nextCursor`), so this is about
* seven pages. The caller caches the projection it needs on disk under the
* shared TTL, so this runs at most once a day and never blocks a first paint.
*/
export async function getAllModelDocs(pageSize = 200): Promise<ModelDoc[]> {
const base = `${FIREBASE_BASE_URL}?status=active&limit=${pageSize}`;
return fetchPinnedModelDocs(base, "model catalog");
}
// ─── Model loaders for cli.ts --model flag validation ────────────────────────
/**
* Load ModelMetadata keyed by model ID for the --model flag help text.
* Backed by the same sync recommended-models doc.
*/
export function loadModelInfo(): Record<OpenRouterModel, ModelMetadata> {
if (_cachedModelInfo) {
return _cachedModelInfo as Record<OpenRouterModel, ModelMetadata>;
}
const data = getRecommendedModelsSync();
const modelInfo: Record<string, ModelMetadata> = {};
// One key per model: a model in two recommendation tiers keeps the metadata of
// its first-listed row.
for (const model of uniqueRecommendedModels(data.models)) {
modelInfo[model.id] = {
name: model.name,
description: model.description,
priority: model.priority,
provider: model.provider,
};
}
// Custom option for the interactive picker
modelInfo.custom = {
name: "Custom Model",
description: "Enter any model ID manually",
priority: 999,
provider: "Custom",
};
_cachedModelInfo = modelInfo;
return modelInfo as Record<OpenRouterModel, ModelMetadata>;
}
/**
* Get list of available model IDs from the recommended doc: one per model, in
* section order then priority (`uniqueRecommendedModels`), then "custom".
* Never sorts the shared cached doc in place: `--models-top --json` prints it.
*/
export function getAvailableModels(): OpenRouterModel[] {
if (_cachedModelIds) {
return _cachedModelIds as OpenRouterModel[];
}
const data = getRecommendedModelsSync();
const modelIds = uniqueRecommendedModels(data.models).map((m) => m.id);
const result = [...modelIds, "custom"];
_cachedModelIds = result;
return result as OpenRouterModel[];
}