Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
import { catalogRouteMatchesProvider, providerForCatalogRoute } from "./catalog-route-bindings.js";
/**
* CatalogClient — single entry point for all Firebase-backed model catalog
* questions. Replaces the three independent slug maps and per-provider
* catalog calls with one interface over `model-loader.ts`.
*
* Caching policy: only Firebase responses go to disk; all caches share
* `FIREBASE_CACHE_TTL_HOURS` from `cache-ttl.ts`. Direct-provider catalog
* calls (Zen, LiteLLM `/model_group/info`) are removed in commit 5.
*
* See `ai-docs/sessions/dev-arch-20260427-140813-663f2981/architecture.md`
* (plan §A) and `firebase-reality-check.md` for the data shape we read.
*/
import {
type AggregatorEntry,
type ModelDoc,
getModelByIdFromFirebase,
getModelsByProvider,
searchModels as searchModelsFromFirebase,
} from "../model-loader.js";
import { type SlimModelEntry, readAllModelsCache, reasoningStatusOf } from "./all-models-cache.js";
import { FIREBASE_CACHE_TTL_MS } from "./cache-ttl.js";
// ─── Public types ────────────────────────────────────────────────────────────
/**
* Catalog-shaped model record used by picker, routing-rules, and search UX.
* A subset of `ModelDoc` chosen so callers don't depend on the full Firebase
* schema — fields are added here as new picker/routing surfaces need them.
*/
export interface CatalogModel {
modelId: string;
displayName: string;
/**
* Owner provider (e.g. "anthropic", "openai"). Optional because the slim
* catalog (used by aggregator-vendor queries) does not carry the owner
* field — only `aggregators[]`. Callers that need the owner should query
* via `modelsByVendor(<owner-slug>)` which uses the rich provider query.
*/
provider?: string;
description?: string;
aggregators?: AggregatorEntry[];
contextWindow?: number;
supportsVision?: boolean;
pricing?: ModelDoc["pricing"];
releaseDate?: string;
capabilities?: ModelDoc["capabilities"];
}
/**
* The `CatalogClient` interface. Implemented by `createCatalogClient()`.
*
* Three operations, all backed by Firebase. Each is intentionally small so
* the picker and routing layer can replace their hardcoded slug tables
* with a single dependency.
*/
export interface CatalogClient {
/**
* All models a vendor SERVES. `vendorSlug` is a Firebase aggregator
* provider name (e.g. "opencode-zen", "openrouter", "anthropic", "google").
*
* For owner-providers (e.g. "anthropic"): returns the rich provider query
* `getModelsByProvider(slug)`.
*
* For aggregator/gateway providers (e.g. "opencode-zen", "openrouter"):
* returns models whose `aggregators[]` lists this vendor. Reads from the
* slim catalog cache at ~/.claudish/cloud-models-catalog-v3.json (24h TTL).
*
* For LiteLLM, Ollama, LM Studio: returns []. These have no Firebase
* catalog by design — callers handle this with a free-text input prompt.
*/
modelsByVendor(vendorSlug: string): Promise<CatalogModel[]>;
/**
* Aggregators that serve a given model. Reads from slim catalog cache.
* Returns null if the model isn't in the catalog (caller decides whether
* to error or attempt the request anyway).
*/
vendorsForModel(modelId: string): Promise<AggregatorEntry[] | null>;
/**
* Cross-vendor search. Delegates to Firebase `?search=...` for live results.
*/
searchModels(term: string, limit?: number): Promise<CatalogModel[]>;
/**
* Every model the slim catalog says this vendor SERVES — synchronous, local,
* no network, for EVERY slug rather than only the aggregator ones.
*
* WHY IT EXISTS SEPARATELY FROM `modelsByVendor`. The picker draws ONE flat
* cross-provider list, so it asks this question about ~31 providers at once.
* `modelsByVendor` answers it for an owner slug with a live `?provider=` query,
* and 22 of those fired together took 10 s and returned nothing (measured:
* every one aborted on its shared timeout, while the same query alone takes
* ~1.1 s). A picker cannot spend that, and it must not degrade to "this
* provider has no models", which is the exact complaint this feature exists to
* remove.
*
* IT IS NOT A SECOND AUTHORITY. Each `aggregators[]` row's route binding is
* already the served-by index — `modelsByVendor`'s own owner branch filters its
* rich lineage list THROUGH it (`filterToServedByProvider`) precisely because
* lineage is not service. This applies the same rule to the same question and
* skips the lineage query, so its membership is the served-by set exactly. The
* cost is per-model richness: `description` and the owner slug are absent from
* the slim payload, so a row's blurb is derived rather than editorial.
*/
servedByVendor(vendorSlug: string): CatalogModel[];
}
// ─── Slug classification ─────────────────────────────────────────────────────
/**
* Vendors that OWN models — these are values that appear in the Firebase
* `provider` field and answer the rich `?provider=...` query well. When a
* slug is in this set we prefer `getModelsByProvider()` which returns the
* full ModelDoc shape.
*
* Note: a slug can be BOTH an owner and a name bound to a route. "anthropic"
* owns Claude models AND names Anthropic's native API route
* (`anthropic/direct-api`, a lookup-only binding in `catalog-route-bindings.ts`:
* no claudish provider calls it). The owner path wins because it returns more
* complete data.
*/
const OWNER_PROVIDER_SLUGS = new Set<string>([
"anthropic",
"openai",
"google",
"x-ai",
"z-ai",
"deepseek",
"minimax",
"moonshotai",
"qwen",
"sakana",
]);
/**
* Cold-start seed for the aggregator set. NOT the list itself — see
* {@link aggregatorProviderSlugs}, which derives the real one from the catalog.
*
* Used only when the slim cache is empty (first run, before the first fetch),
* where an empty set would make `modelsByVendor()` return nothing for everyone.
*
* Each seed is a claudish provider name, the spelling `modelsByVendor()` is asked
* in and the one the derived set holds. `together`, not the catalog's `routeId`
* `together-ai`: no caller asks for `together-ai`, so that seed matched nothing
* and a cold `modelsByVendor("together")` fell through to the owner query.
*/
const AGGREGATOR_SLUG_SEED = new Set<string>([
"openrouter",
"opencode-zen",
"opencode-zen-go",
"fireworks",
"together",
]);
/**
* Which providers SERVE other owners' models, derived from the catalog itself.
*
* `aggregators[].provider` IS this set — every provider that serves anything
* appears there by construction. Hardcoding it meant the list went stale the
* moment the backend added a provider, silently: `modelsByVendor()` fell
* through and returned nothing, and the picker papered over the empty list by
* aliasing to a DIFFERENT provider's catalog (`antigravity` → `google`), so
* users were shown the direct Gemini API's models under the Antigravity
* subscription. Measured against the live catalog, the hardcoded set of 5
* missed 4 real providers: antigravity (20 models), mistralai (19),
* kimi-coding (4), openai-codex (1).
*
* Recomputed per call from the passed-in cache reader — the cache is already
* memoized upstream, and the set must track a refresh without a restart.
*/
function aggregatorProviderSlugs(
readSlimCache: () => { entries: SlimModelEntry[] } | null
): Set<string> {
const cache = readSlimCache();
if (!cache || cache.entries.length === 0) return AGGREGATOR_SLUG_SEED;
const slugs = new Set<string>();
for (const entry of cache.entries) {
for (const agg of entry.aggregators ?? []) {
if (agg.routeStatus === "mapped") {
const provider = providerForCatalogRoute(agg.route!);
if (provider) slugs.add(provider.toLowerCase());
}
}
}
// Union with the seed: a provider claudish knows how to reach should not
// vanish from the picker just because the current catalog snapshot happens
// to carry no models for it.
for (const seed of AGGREGATOR_SLUG_SEED) slugs.add(seed);
return slugs;
}
/**
* Local-only / undocumented-catalog vendors. These have no Firebase catalog
* by design; the picker shows a free-text input instead of a model list.
* claudish provider names only: LM Studio is `lmstudio`.
*/
const NO_CATALOG_VENDOR_SLUGS = new Set<string>(["litellm", "ollama", "lmstudio"]);
// ─── Internal helpers ────────────────────────────────────────────────────────
function modelDocToCatalogModel(doc: ModelDoc): CatalogModel {
return {
modelId: doc.modelId,
displayName: doc.displayName ?? doc.modelId,
provider: doc.provider,
description: doc.description,
aggregators: doc.aggregators,
contextWindow: doc.contextWindow,
supportsVision: doc.capabilities?.vision,
pricing: doc.pricing,
releaseDate: doc.releaseDate,
capabilities: doc.capabilities,
};
}
/**
* Filter an owner-lineage model list down to the models the slim catalog's
* served-by index (`aggregators[].provider`) confirms THIS provider actually
* serves, and graft the matched served-by aggregators onto each kept model (the
* owner query returns `aggregators: null`, so the picker's downstream pricing /
* externalId resolution needs them attached here).
*
* The backend emits the owner's canonical slug in the served-by index for
* first-party serving, so this is a plain exact-match — no slug translation.
*
* Safety: if the slim cache is empty/unavailable (cold start), DON'T filter —
* return the full list so the picker isn't blanked. A model present in the owner
* list but absent from the slim cache is excluded (conservative: better to hide
* a possibly-unservable model than to offer one that 404s).
*/
function filterToServedByProvider(
models: CatalogModel[],
slug: string,
reader: () => ReturnType<typeof readAllModelsCache>
): CatalogModel[] {
const { entries } = readSlimCacheWithFreshness(reader);
if (entries.length === 0) return models; // cold start — don't blank the picker
// Index slim entries by modelId AND every alias, so an owner doc whose id is
// an alias in the slim catalog still matches.
const byId = new Map<string, SlimModelEntry>();
for (const entry of entries) {
byId.set(entry.modelId.toLowerCase(), entry);
for (const alias of entry.aliases) byId.set(alias.toLowerCase(), entry);
}
const kept: CatalogModel[] = [];
for (const model of models) {
const slim = byId.get(model.modelId.toLowerCase());
const served = slim?.aggregators?.some((agg) => catalogRouteMatchesProvider(agg.route, slug));
if (served) {
kept.push({ ...model, aggregators: slim?.aggregators ?? model.aggregators });
}
}
return kept;
}
export function slimEntryToCatalogModel(entry: SlimModelEntry): CatalogModel {
return {
modelId: entry.modelId,
displayName: entry.modelId,
// `provider` (owner) is intentionally omitted — the slim catalog doesn't
// carry it. Aggregator queries are about "who serves this model", not
// "who owns this model"; callers don't need owner here.
aggregators: entry.aggregators,
contextWindow: entry.contextWindow,
supportsVision: entry.supportsVision,
releaseDate: entry.releaseDate,
// THE TWO CAPABILITY FLAGS THE SLIM CACHE ACTUALLY CARRIES, forwarded in the
// shape every renderer reads. They were dropped here: `supportsVision` above
// goes into a field only the probe path reads, and `reasoning` was not mapped
// at all — so every aggregator-served list (OpenRouter's 349 models, and it is
// the default provider) rendered its capability column entirely dead while the
// data sat in the cache. Visible the moment a row carries a capability column.
//
// `supportsTools` IS carried by the slim payload (~97% of models, per its own
// field doc) and was left unmapped here, so every aggregator-served row showed
// a dead tools flag while the answer sat one property away. It is forwarded
// ONLY when present — `undefined` stays `undefined` rather than becoming
// `false`, because "the catalog does not say" and "this model cannot take
// tools" are different claims and only the second one disqualifies a model.
capabilities: {
...(entry.supportsVision === undefined ? {} : { vision: entry.supportsVision }),
// v3 `reasoning` is an OBJECT, `{ supported: false }` included — reading its
// mere presence as "thinks" flagged 469 of 1137 non-reasoning entries as
// reasoning models. Same rule as the adapters: an UNKNOWN status says nothing.
...(entry.reasoning === undefined || reasoningStatusOf(entry) === "unknown"
? {}
: { thinking: entry.reasoning.supported }),
...(entry.supportsTools === undefined ? {} : { tools: entry.supportsTools }),
},
};
}
/**
* Read the slim cache fresh-or-stale, plus a flag indicating whether it's
* past the shared TTL. Callers use the flag to decide whether to try a live
* Firebase fetch as a fallback.
*
* Firebase-derived data — OK to cache locally per the catalog policy.
* TTL shared with all other Firebase caches via FIREBASE_CACHE_TTL_HOURS.
*/
function readSlimCacheWithFreshness(reader: () => ReturnType<typeof readAllModelsCache>): {
entries: SlimModelEntry[];
stale: boolean;
} {
const cache = reader();
if (!cache) return { entries: [], stale: true };
const lastUpdatedMs = new Date(cache.lastUpdated).getTime();
const ageMs = Date.now() - lastUpdatedMs;
const stale = !Number.isFinite(lastUpdatedMs) || ageMs > FIREBASE_CACHE_TTL_MS;
return { entries: cache.entries ?? [], stale };
}
// ─── Dependency injection ────────────────────────────────────────────────────
/**
* Optional dependency overrides for testing. Production callers pass nothing
* and get the real `model-loader.ts` + `all-models-cache.ts` wiring.
*/
export interface CatalogClientDeps {
getModelsByProvider?: typeof getModelsByProvider;
getModelByIdFromFirebase?: typeof getModelByIdFromFirebase;
searchModels?: typeof searchModelsFromFirebase;
/** Returns the parsed slim cache or null. Default reads ~/.claudish/cloud-models-catalog-v3.json. */
readSlimCache?: () => ReturnType<typeof readAllModelsCache>;
}
// ─── Factory ─────────────────────────────────────────────────────────────────
/**
* Construct a `CatalogClient`. Pass `deps` only in tests — real callers omit
* the argument and get the production wiring.
*/
export function createCatalogClient(deps: CatalogClientDeps = {}): CatalogClient {
const _getModelsByProvider = deps.getModelsByProvider ?? getModelsByProvider;
const _getModelByIdFromFirebase = deps.getModelByIdFromFirebase ?? getModelByIdFromFirebase;
const _searchModels = deps.searchModels ?? searchModelsFromFirebase;
const _readSlimCache = deps.readSlimCache ?? readAllModelsCache;
return {
async modelsByVendor(vendorSlug: string): Promise<CatalogModel[]> {
const slug = vendorSlug.toLowerCase();
// No-catalog vendors short-circuit without I/O. Picker is expected to
// detect [] and switch to the free-text input path.
if (NO_CATALOG_VENDOR_SLUGS.has(slug)) return [];
// Owners → rich provider query (returns full ModelDoc).
//
// The `?provider=` query returns every model the provider OWNS by lineage,
// but a provider can only SERVE the subset its API actually exposes (e.g.
// `gpt-latest` is OpenAI-owned but only OpenRouter serves it → calling it
// via oai@ 404s). The slim catalog's `aggregators[].provider` is the
// served-by index; since the backend now emits the owner's canonical slug
// there for first-party serving, we keep only models whose slim entry lists
// THIS provider as a server, and graft the served-by aggregators (pricing /
// externalId) onto the kept models. The picker selects a provider exactly
// to see what that provider can run — lineage is not service.
if (OWNER_PROVIDER_SLUGS.has(slug)) {
const docs = await _getModelsByProvider(slug);
return filterToServedByProvider(docs.map(modelDocToCatalogModel), slug, _readSlimCache);
}
// Aggregators → filter slim cache by aggregators[].provider. The set of
// aggregator slugs is DERIVED from that same field, so a provider the
// backend starts serving shows up here without a code change.
if (aggregatorProviderSlugs(_readSlimCache).has(slug)) {
const { entries } = readSlimCacheWithFreshness(_readSlimCache);
const matches = entries.filter((entry) =>
entry.aggregators?.some((agg) => catalogRouteMatchesProvider(agg.route, slug))
);
return matches.map(slimEntryToCatalogModel);
}
// Unknown slug — fall through to the rich provider query. Firebase
// returns [] for genuinely unknown providers; this preserves the
// owner-path completeness for any new owner slug we haven't enumerated
// here yet.
const docs = await _getModelsByProvider(slug);
return docs.map(modelDocToCatalogModel);
},
async vendorsForModel(modelId: string): Promise<AggregatorEntry[] | null> {
// Firebase-derived data — OK to cache locally per the catalog policy.
// TTL shared with all other Firebase caches via FIREBASE_CACHE_TTL_HOURS.
const { entries, stale } = readSlimCacheWithFreshness(_readSlimCache);
// Try the in-cache lookup first regardless of staleness — even a stale
// cache is better than a network round-trip if the model is present.
for (const entry of entries) {
if (entry.modelId === modelId || entry.aliases.includes(modelId)) {
return entry.aggregators ?? [];
}
}
// Cache miss. If the cache is fresh and the model wasn't there, treat
// the catalog as authoritative for this question and return null.
if (!stale) return null;
// Stale (or empty) cache + cache miss: fall back to live Firebase to
// give the caller a definitive answer. We don't refresh the slim cache
// here — that's a separate code path (openrouter resolver) and adding
// a fire-and-forget refresh from the catalog read site has historically
// caused interleaved-write bugs.
const doc = await _getModelByIdFromFirebase(modelId);
if (!doc) return null;
return doc.aggregators ?? [];
},
async searchModels(term: string, limit = 50): Promise<CatalogModel[]> {
const docs = await _searchModels(term, limit);
return docs.map(modelDocToCatalogModel);
},
servedByVendor(vendorSlug: string): CatalogModel[] {
const slug = vendorSlug.toLowerCase();
// Local-only vendors are absent from the catalog BY DESIGN, so an empty
// answer here is a fact, not a miss. Their dynamic models catalogs come from their own
// daemons through `modelDiscovery`.
if (NO_CATALOG_VENDOR_SLUGS.has(slug)) return [];
const { entries } = readSlimCacheWithFreshness(_readSlimCache);
const out: CatalogModel[] = [];
for (const entry of entries) {
// The same rule `filterToServedByProvider` applies, so the two answers
// cannot drift: a v3 row names who serves it by its route binding.
if (entry.aggregators?.some((agg) => catalogRouteMatchesProvider(agg.route, slug))) {
out.push(slimEntryToCatalogModel(entry));
}
}
return out;
},
};
}