Skip to content

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

21.6 KB
Raw Blame
/**
 * Model metadata catalog — Firebase slim cache is the sole source of truth.
 *
 * All model facts (contextWindow, supportsVision) come from the slim catalog
 * at ~/.claudish/cloud-models-catalog-v3.json, populated at proxy startup by the OpenRouter
 * catalog resolver.
 *
 * Adapter-specific behavior (temperature ranges, tool name limits, max tool
 * counts) lives in the dialect/format classes themselves — those are CLI
 * constraints, not model metadata.
 */

import type { ReasoningModeCapabilities } from "../model-loader.js";
import {
  type CachedSubscriptionPlan,
  type ReasoningCapability,
  type RouteVariant,
  type SlimModelEntry,
  readAllModelsCache,
  reasoningStatusOf,
} from "../providers/all-models-cache.js";
import { catalogRouteMatchesProvider } from "../providers/catalog-route-bindings.js";
import { compareByReleaseDateDesc } from "../providers/model-ordering.js";

export type {
  ModelEndpoint,
  ReasoningCapability,
  ReasoningControl,
  RouteVariant,
} from "../providers/all-models-cache.js";
export type { ReasoningModeCapabilities } from "../model-loader.js";

export interface ModelEntry {
  /** Model ID as stored in the slim catalog (not lowercased) */
  modelId: string;
  /** Context window in tokens */
  contextWindow: number;
  /** Whether model supports vision/image input (may be undefined if Firebase didn't specify) */
  supportsVision?: boolean;
  /**
   * Curated release date (ISO `YYYY-MM-DD`), when Firebase has one. The
   * authoritative freshness signal — pickers prefer it over any date a provider
   * endpoint reports, which is a date-added timestamp, not a release.
   */
  releaseDate?: string;
}

/**
 * Look up model metadata from the Firebase slim catalog cache.
 *
 * Accepts:
 *   - Bare model IDs ("glm-5", "minimax-m2.7")
 *   - Vendor-prefixed IDs ("x-ai/grok-4")
 *
 * Throws if `modelId` contains "@" — callers must strip the provider prefix
 * before calling (contract enforcement).
 *
 * Returns undefined when:
 *   - The cache file doesn't exist (cold start)
 *   - modelId isn't in the cache
 *   - The entry exists but has no `contextWindow`
 *
 * @param cachePath Override cache path. Defaults to `~/.claudish/cloud-models-catalog-v3.json`.
 *                  Only tests should pass this.
 */
export function lookupModel(modelId: string, cachePath?: string): ModelEntry | undefined {
  const entry = findCacheEntry(modelId, cachePath);
  if (!entry || entry.contextWindow === undefined) return undefined;
  return {
    modelId: entry.modelId,
    contextWindow: entry.contextWindow,
    supportsVision: entry.supportsVision,
    releaseDate: entry.releaseDate,
  };
}

/**
 * Whether the catalog says this model accepts images: its `inputModalities`
 * when published (a list without "image" is a no), else `supportsVision`.
 * `undefined` when the catalog states neither — unknown, never false.
 */
export function lookupModelAcceptsImages(modelId: string, cachePath?: string): boolean | undefined {
  const entry = findCacheEntry(modelId, cachePath);
  if (!entry) return undefined;
  if (Array.isArray(entry.inputModalities) && entry.inputModalities.length > 0) {
    return entry.inputModalities.includes("image");
  }
  return typeof entry.supportsVision === "boolean" ? entry.supportsVision : undefined;
}

/**
 * Reasoning capability for a model, straight from the slim catalog.
 *
 * Separate from {@link lookupModel} on purpose: that one gates on
 * `contextWindow` being present (its callers want a window), whereas reasoning
 * metadata is useful on its own — a model can carry `reasoning` with no window.
 *
 * Returns undefined for a cold cache or an unknown model. Callers MUST treat
 * that as "no information" and keep their existing behaviour; it is never an
 * error, and it must never block a request.
 */
export function lookupModelReasoning(
  modelId: string,
  cachePath?: string
): ReasoningCapability | undefined {
  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;
}

/**
 * Preset-variant metadata — which family this model belongs to, and whether it
 * is that family's default on its provider.
 *
 * This is the sanctioned replacement for ranking variant suffixes client-side:
 * the catalog names the default (`isDefault`), so there is nothing to rank.
 */
export function lookupModelRouteVariant(
  modelId: string,
  cachePath?: string
): RouteVariant | undefined {
  return findCacheEntry(modelId, cachePath)?.routeVariant;
}

/**
 * `reasoning.mode` support for the exact route selected by `provider`.
 *
 * The same base model can support the parameter on one host, reject it on a
 * second, and remain unverified on a third. Never fall back to model-level
 * reasoning metadata or another aggregator row.
 */
export function lookupRouteReasoningMode(
  modelId: string,
  provider: string,
  cachePath?: string
): ReasoningModeCapabilities | undefined {
  return findCacheEntry(modelId, cachePath)?.aggregators?.find((aggregator) =>
    catalogRouteMatchesProvider(aggregator.route, provider)
  )?.reasoning?.mode;
}

/**
 * The default preset variant for a family on a given provider, if the catalog
 * knows one.
 *
 * Answers "the user typed `gemini-3.6-flash`, which id do we actually send to
 * Antigravity?" by scanning for the family's `isDefault` variant. Returns
 * undefined when the cache is cold or the family has no marked default, and the
 * caller then falls back to its own resolution.
 */
export function lookupFamilyDefaultVariant(
  familyId: string,
  provider: string,
  cachePath?: string
): string | undefined {
  const cache = readAllModelsCache(cachePath);
  if (!cache) return undefined;
  for (const entry of cache.entries) {
    const rv = entry.routeVariant;
    if (!rv?.isDefault) continue;
    if (rv.provider !== provider) continue;
    if (rv.familyId === familyId || rv.baseModelId === familyId) return entry.modelId;
  }
  return undefined;
}

/**
 * Every catalog variant whose preset expands `baseModelId`, optionally narrowed
 * to one serving provider.
 *
 * The inverse of {@link lookupModelRouteVariant}: that answers "which model is
 * this variant a preset OF?", this answers "which presets exist FOR this
 * model?".
 *
 * This is the sanctioned replacement for a name regex that asks "does this
 * model support capability X?". The catalog records BOTH halves of the fact —
 * which base model a preset applies to (`baseModelId`) and what the preset
 * actually sets (`preset`, in `--model-params` `k=v` syntax) — so the caller
 * carries neither a model list nor a hardcoded payload. Feed `preset` to
 * `parseModelParams()` to get the params the provider would have applied.
 *
 * Returns [] for a cold cache or a model with no variants. Callers MUST treat
 * that as "no information" and keep their existing behaviour; absence is never
 * an error and must never block a request.
 *
 * @param provider Only return variants recorded on this serving provider. A
 *   preset is an observation about ONE provider's model list, not a portable fact
 *   about the model — the same parameter may not exist on another host — so a
 *   caller that cannot verify the parameter independently should pass the
 *   provider it is actually routing to.
 */
export function lookupVariantPresets(
  baseModelId: string,
  provider?: string,
  cachePath?: string
): { modelId: string; preset: string; provider?: string }[] {
  const cache = readAllModelsCache(cachePath);
  if (!cache) return [];
  // Same key rule as findCacheEntry — the caller passes a BARE name, and on the
  // OpenRouter route a bare name still carries the vendor prefix
  // ("openai/gpt-5.6-sol") because OpenRouter's API requires it. Comparing raw
  // strings here matched nothing on precisely the provider whose presets the
  // catalog records, i.e. the feature was dead where it was meant to work.
  const wanted = stripVendorPrefix(baseModelId.toLowerCase());
  const found: { modelId: string; preset: string; provider?: string }[] = [];
  for (const entry of cache.entries) {
    const rv = entry.routeVariant;
    if (!rv?.preset || !rv.baseModelId) continue;
    if (stripVendorPrefix(rv.baseModelId.toLowerCase()) !== wanted) continue;
    if (provider !== undefined && rv.provider !== provider) continue;
    found.push({ modelId: entry.modelId, preset: rv.preset, provider: rv.provider });
  }
  return found;
}

/**
 * Coarse capability flags straight from the catalog. Each is undefined when the
 * catalog has no opinion — never defaulted to false, because "unknown" and "no"
 * lead to different behaviour (dropping tools from a request that needs them is
 * worse than sending them to a model that ignores them).
 */
export function lookupModelCapabilities(
  modelId: string,
  cachePath?: string
): { supportsTools?: boolean; supportsThinking?: boolean } | undefined {
  const entry = findCacheEntry(modelId, cachePath);
  if (!entry) return undefined;
  return { supportsTools: entry.supportsTools, supportsThinking: entry.supportsThinking };
}

/**
 * Provider-aware context window lookup.
 *
 * The same model id can enforce DIFFERENT windows on different serving backends
 * (e.g. gpt-5.6-sol = 1.05M on the OpenAI API but ~372K on the ChatGPT Codex
 * OAuth backend). The slim catalog carries the per-provider window on each
 * `aggregators[]` entry; this returns the window for `provider` if present,
 * else the model's top-level `contextWindow`.
 *
 * @param provider The resolved CLI provider name (e.g. "openai-codex").
 * @returns The provider-specific window, the top-level window, or undefined if
 *          the model isn't in the catalog at all.
 */
export function lookupModelForProvider(
  modelId: string,
  provider: string,
  cachePath?: string
): number | undefined {
  const entry = findCacheEntry(modelId, cachePath);
  if (!entry) return undefined;
  return (
    entry.aggregators?.find((a) => catalogRouteMatchesProvider(a.route, provider))?.contextWindow ??
    entry.contextWindow
  );
}

/** A subscription route's catalog answer for one model. */
export type SubscriptionRouting =
  | { kind: "serves"; externalId: string }
  | { kind: "not-served" }
  | { kind: "unknown" };

export function resolveSubscriptionRouting(
  modelId: string,
  provider: string,
  cachePath?: string
): SubscriptionRouting {
  const cache = readAllModelsCache(cachePath);
  const entry = findCacheEntry(modelId, cachePath);
  if (!cache || !entry) return { kind: "unknown" };

  const plans = cache.plans.filter(
    (plan) => plan.routeStatus === "supported" && catalogRouteMatchesProvider(plan.route, provider)
  );
  if (plans.length === 0) return { kind: "unknown" };

  const memberships = entry.subscriptionPlanIds ?? [];
  const included = plans.filter((plan) => memberships.includes(plan.id));
  if (included.length > 0) {
    if (included.length !== plans.length) return { kind: "unknown" };
    const connection = entry.aggregators?.find(
      (candidate) =>
        candidate.routeStatus === "mapped" && catalogRouteMatchesProvider(candidate.route, provider)
    );
    return connection?.externalModelId
      ? { kind: "serves", externalId: connection.externalModelId }
      : { kind: "unknown" };
  }

  // Client-selected and hybrid memberships are decided by the user's live session.
  if (plans.some((plan) => plan.modelDiscovery !== "catalog")) return { kind: "unknown" };
  const ids = new Set(plans.map((plan) => plan.id));
  const hasMembership = cache.entries.some((candidate) =>
    candidate.subscriptionPlanIds?.some((planId) => ids.has(planId))
  );
  return hasMembership ? { kind: "not-served" } : { kind: "unknown" };
}

/**
 * Find the slim catalog entry for a model id (bare or vendor-prefixed), matching
 * on modelId or aliases. Shared by lookupModel / lookupModelForProvider.
 * Throws if `modelId` contains "@" — callers must strip the provider prefix.
 */
/**
 * The catalog's matching key for a model id: lowercased, vendor prefix dropped.
 *
 * `openai/gpt-5.6-sol` and `gpt-5.6-sol` are the SAME model — the prefix is
 * aggregator routing vocabulary, and OpenRouter's route keeps it on the bare
 * name (see the vendor-prefix note in proxy-server's getOpenRouterHandler).
 * Every catalog lookup must apply this rule or it silently misses exactly the
 * models reached through an aggregator.
 */
function stripVendorPrefix(lowerId: string): string {
  return lowerId.includes("/") ? lowerId.substring(lowerId.lastIndexOf("/") + 1) : lowerId;
}

function findCacheEntry(modelId: string, cachePath?: string): SlimModelEntry | undefined {
  if (modelId.includes("@")) {
    throw new Error(
      `model-catalog lookup received provider-routed ID "${modelId}" — callers must strip the "@" prefix before calling`
    );
  }

  const cache = readAllModelsCache(cachePath);
  if (!cache || cache.entries.length === 0) return undefined;

  const lower = modelId.toLowerCase();
  const unprefixed = stripVendorPrefix(lower);

  for (const entry of cache.entries) {
    const entryId = entry.modelId.toLowerCase();

    const exactMatch = entryId === unprefixed || entryId === lower;
    const aliasMatch = entry.aliases?.some(
      (a) => a.toLowerCase() === unprefixed || a.toLowerCase() === lower
    );

    if (exactMatch || aliasMatch) {
      return entry;
    }
  }

  // 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 an exact wire id in a plan's membership 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 inclusion = plan.inclusions?.find((item) => item.externalModelId === wireId);
    if (inclusion?.resolution?.status === "mapped") return inclusion.resolution.modelId;
  }
  return undefined;
}

/** Default context window when no catalog match (0 = unknown, shows N/A in status line) */
export const DEFAULT_CONTEXT_WINDOW = 0;

/** Default vision support when no catalog match */
export const DEFAULT_SUPPORTS_VISION = true;

/**
 * One catalog hit for a free-text model search.
 *
 * `modelId` is the BARE name routing accepts. `aliases` is the load-bearing
 * field: subscription endpoints speak their own wire ids (`k3` for `kimi-k3`,
 * `kimi-for-coding` for `kimi-k2.7-code`), and those ids exist in NO
 * aggregator's namespace. A search that consults only an aggregator listing
 * therefore reports them as nonexistent, which reads as "unroutable" and sends
 * the caller to a metered route instead.
 */
export interface CatalogSearchMatch {
  /** Bare catalog identity — the name to hand to routing. */
  modelId: string;
  aliases: string[];
  /** Subscription plans that include this model, verbatim from the catalog. */
  subscriptionPlanIds: string[];
  /** Set when the query matched an alias rather than the model id itself. */
  matchedAlias?: string;
}

/**
 * How one catalog entry matches a query, or undefined when it does not.
 *
 * Split out of {@link searchCatalogModels} so the matching RULE reads on its
 * own: an id hit and an alias hit are different answers, and only the alias
 * branch can resolve a subscription wire id to its catalog identity.
 */
function classifyCatalogHit(
  entry: SlimModelEntry,
  q: string
): { bucket: "exact" | "id" | "alias"; matchedAlias?: string } | undefined {
  const id = entry.modelId.toLowerCase();
  if (id === q || stripVendorPrefix(id) === q) return { bucket: "exact" };

  const aliases = entry.aliases ?? [];
  const exactAlias = aliases.find(
    (a) => a.toLowerCase() === q || stripVendorPrefix(a.toLowerCase()) === q
  );
  if (exactAlias) return { bucket: "exact", matchedAlias: exactAlias };

  if (id.includes(q)) return { bucket: "id" };

  const partialAlias = aliases.find((a) => a.toLowerCase().includes(q));
  return partialAlias ? { bucket: "alias", matchedAlias: partialAlias } : undefined;
}

/**
 * Search the local catalog cache by model id or alias.
 *
 * Deliberately separate from the aggregator-listing search in the MCP server:
 * that one answers "what does OpenRouter sell", this one answers "what name
 * does claudish know". Only the second can resolve a subscription wire id.
 *
 * Ranking is exact-match first (an exact alias hit is the whole point — it is
 * how `k3` resolves to `kimi-k3`), then substring hits on the id, then
 * substring hits on an alias.
 *
 * Returns [] for a cold or missing cache. Callers MUST treat that as "no
 * information" rather than "no such model".
 */
export function searchCatalogModels(
  query: string,
  limit = 10,
  cachePath?: string
): CatalogSearchMatch[] {
  const q = query.trim().toLowerCase();
  if (!q) return [];

  const cache = readAllModelsCache(cachePath);
  if (!cache || cache.entries.length === 0) return [];

  type Ranked = { match: CatalogSearchMatch; entry: SlimModelEntry };
  const exact: Ranked[] = [];
  const idPartial: Ranked[] = [];
  const aliasPartial: Ranked[] = [];

  for (const entry of cache.entries) {
    const hit = classifyCatalogHit(entry, q);
    if (!hit) continue;
    const ranked: Ranked = {
      entry,
      match: {
        modelId: entry.modelId,
        aliases: entry.aliases ?? [],
        subscriptionPlanIds: entry.subscriptionPlanIds ?? [],
        ...(hit.matchedAlias ? { matchedAlias: hit.matchedAlias } : {}),
      },
    };
    if (hit.bucket === "exact") exact.push(ranked);
    else if (hit.bucket === "id") idPartial.push(ranked);
    else aliasPartial.push(ranked);
  }

  // Partial hits arrive in cache order, which buries the canonical model under
  // every superseded sibling sharing its family name: "kimi" returned five K2
  // variants and cut off K3 entirely.
  //
  // Rank by SPECIFICITY first, freshness second. Freshness alone is wrong here
  // because release dates are sparse — `kimi-k3` carries none while its own
  // derivative `kimi-k3-256k` is dated 2026-07-16, and compareByReleaseDateDesc
  // reads a missing date as the epoch, so the parent sorts below its variant.
  // The shortest id containing the query is the one with the least extra
  // material bolted on, which is what someone typing a family name means.
  const byRelevance = (a: Ranked, b: Ranked) => {
    const lengthDelta = a.entry.modelId.length - b.entry.modelId.length;
    if (lengthDelta !== 0) return lengthDelta;
    return compareByReleaseDateDesc(a.entry, b.entry);
  };
  idPartial.sort(byRelevance);
  aliasPartial.sort(byRelevance);

  return [...exact, ...idPartial, ...aliasPartial].slice(0, limit).map((r) => r.match);
}