Skip to content

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

12.3 KB
Raw Blame
import { existsSync, readFileSync, statSync } 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 { AggregatorEntry } from "../model-loader.js";
import {
  type CachedRouteRegistry,
  WIRE_REGISTRY_VERSION,
  isConnectionWire,
  isRouteRegistry,
  registryVersionAtLeast,
  routeProfile,
} from "./connection-wire.js";
import { allConnections, splitOptInConnections } from "./content-use.js";

export type ReasoningControl = "toggle" | "effort" | "adaptive" | "budget" | "none";

export interface ReasoningCapability {
  supported: boolean;
  control?: ReasoningControl;
  mandatory?: boolean;
  efforts?: string[];
  defaultEffort?: string;
  supportsBudgetTokens?: boolean;
}

export interface RouteVariant {
  kind: string;
  baseModelId?: string;
  familyId?: string;
  provider?: string;
  preset?: string;
  isDefault?: boolean;
}

export interface ModelEndpoint {
  api?: string;
  toolsWithReasoning?: string;
}

export interface SlimModelEntry {
  contractVersion?: 3;
  modelId: string;
  displayName?: string;
  provider?: string;
  aliases: string[];
  status?: string;
  releaseDate?: string;
  contextWindow?: number;
  maxOutputTokens?: number;
  reasoningStatus?: "known" | "unknown";
  reasoning?: ReasoningCapability;
  supportsVision?: boolean;
  supportsTools?: boolean;
  supportsThinking?: boolean;
  videoInput?: boolean;
  videoOutput?: boolean;
  /** What the model accepts, from the cloud models catalog. Absent, null or [] means unknown. */
  inputModalities?: string[] | null;
  /** What the model produces. Absent, null or [] means unknown; a list without "text" is not a chat model. */
  outputModalities?: string[] | null;
  aggregators?: AggregatorEntry[];
  /**
   * Connections whose wire id opts content into the vendor's product
   * improvement, moved out of `aggregators` when the catalog is read into memory
   * (`splitOptInConnections`, `content-use.ts`). Never written to disk. Only an
   * exact-id reader looks here (`allConnections`); nothing chooses one for a user.
   */
  optInConnections?: AggregatorEntry[];
  subscriptionPlanIds?: string[];
  tokenParam?: string;
  routeVariant?: RouteVariant;
  endpoints?: Record<string, ModelEndpoint>;
}

export function reasoningStatusOf(entry: SlimModelEntry): "known" | "unknown" {
  if (entry.reasoningStatus === "known" || entry.reasoningStatus === "unknown") {
    return entry.reasoningStatus;
  }
  return entry.reasoning !== undefined ? "known" : "unknown";
}

export type SubscriptionModelDiscovery = "catalog" | "client" | "hybrid";

export interface CachedPlanInclusion {
  kind: string;
  sourceText?: string;
  provider?: string;
  externalModelId?: string;
  resolution?: { status: "mapped"; modelId: string } | { status: "missing" | "ambiguous" };
}

export interface CachedSubscriptionPlan {
  contractVersion?: 3;
  id: string;
  provider?: string;
  modelDiscovery?: SubscriptionModelDiscovery;
  routeStatus: "supported" | "unsupported" | "unknown";
  route?: { routeId: string; routeProfileId: string };
  routeReason?: string;
  inclusions?: CachedPlanInclusion[];
}

export interface DiskCacheV3 {
  version: 3;
  lastUpdated: string;
  entries: SlimModelEntry[];
  models: Array<{ id: string }>;
  plans: CachedSubscriptionPlan[];
  catalogGenerationId: string;
  /**
   * The route registry of the SAME generation (`catalog=routes&generationId=`).
   * Absent in a cache written before claudish read wires; the request path then
   * refreshes the catalog instead of building a request without one.
   */
  routeRegistry?: CachedRouteRegistry;
}

/**
 * The cloud models catalog cache: contract-3 data, in a file of its own.
 *
 * NOT `all-models.json`. That name belongs to older claudish builds, which read
 * it as a v2 catalog; a v3 cache written there crashed them on every bare-name
 * route (`TypeError … entry.sources["openrouter-api"]`, measured 2026-09-19),
 * and it was ALSO the file the MCP server overwrote with an OpenRouter model dump.
 * A contract change gets a new file, so no build ever reads a shape it cannot
 * parse. `all-models.json` is left untouched for the builds that still read it.
 */
export const ALL_MODELS_CACHE_PATH = join(homedir(), ".claudish", "cloud-models-catalog-v3.json");

function hasRoute(value: unknown): value is { routeId: string; routeProfileId: string } {
  if (!value || typeof value !== "object") return false;
  const route = value as Record<string, unknown>;
  return typeof route.routeId === "string" && typeof route.routeProfileId === "string";
}

export function isSlimModelEntry(value: unknown): value is SlimModelEntry {
  if (!value || typeof value !== "object") return false;
  const entry = value as Record<string, unknown>;
  if (
    typeof entry.modelId !== "string" ||
    !Array.isArray(entry.aliases) ||
    !entry.aliases.every((alias) => typeof alias === "string")
  )
    return false;
  if (
    entry.subscriptionPlanIds !== undefined &&
    (!Array.isArray(entry.subscriptionPlanIds) ||
      !entry.subscriptionPlanIds.every((id) => typeof id === "string"))
  )
    return false;
  if (entry.aggregators === undefined) return true;
  if (!Array.isArray(entry.aggregators)) return false;
  return entry.aggregators.every((candidate: unknown) => {
    if (!candidate || typeof candidate !== "object") return false;
    const connection = candidate as Record<string, unknown>;
    return connection.routeStatus === "mapped"
      ? hasRoute(connection.route) &&
          typeof connection.externalModelId === "string" &&
          connection.externalModelId.length > 0
      : connection.routeStatus === "unknown" || connection.routeStatus === "unsupported";
  });
}

export function isCachedSubscriptionPlan(value: unknown): value is CachedSubscriptionPlan {
  if (!value || typeof value !== "object") return false;
  const plan = value as Record<string, unknown>;
  return (
    typeof plan.id === "string" &&
    plan.id.length > 0 &&
    (plan.routeStatus === "supported"
      ? hasRoute(plan.route)
      : plan.routeStatus === "unsupported" || plan.routeStatus === "unknown") &&
    (plan.modelDiscovery === undefined ||
      ["catalog", "client", "hybrid"].includes(String(plan.modelDiscovery)))
  );
}

/**
 * A cached registry must belong to the model list's generation, and from 3.7.0
 * every mapped connection must carry a `wire` whose route profile exists and,
 * when known, publishes a base URL for its `api`. One bad connection rejects the
 * whole cache: a partial wire table would send some requests from data and the
 * rest from nothing.
 */
export function wiresMatchRegistry(
  entries: SlimModelEntry[],
  routeRegistry: CachedRouteRegistry,
  catalogGenerationId: string
): boolean {
  if (routeRegistry.generationId !== catalogGenerationId) return false;
  const { registry } = routeRegistry;
  if (!registryVersionAtLeast(registry.registryVersion, WIRE_REGISTRY_VERSION)) return true;
  // Every row, opt-in included: an explicit contributor request builds from its
  // own connection's wire, so that wire is validated like any other.
  return entries.every((entry) =>
    allConnections(entry).every((connection) => {
      if (connection.routeStatus !== "mapped") return true;
      if (!connection.route || !isConnectionWire(connection.wire)) return false;
      const profile = routeProfile(registry, connection.route);
      if (!profile) return false;
      return connection.wire.status !== "known" || !!profile.apis[connection.wire.api]?.baseUrl;
    })
  );
}

function parseAllModelsCache(raw: unknown): DiskCacheV3 | null {
  if (!raw || typeof raw !== "object") return null;
  const data = raw as Record<string, unknown>;
  if (
    data.version !== 3 ||
    typeof data.lastUpdated !== "string" ||
    typeof data.catalogGenerationId !== "string" ||
    data.catalogGenerationId.length === 0 ||
    !Array.isArray(data.entries) ||
    !data.entries.every(isSlimModelEntry) ||
    !Array.isArray(data.models) ||
    !Array.isArray(data.plans) ||
    !data.plans.every(isCachedSubscriptionPlan)
  ) {
    return null;
  }
  if (data.routeRegistry !== undefined) {
    const cached = data.routeRegistry as Record<string, unknown> | null;
    if (
      !cached ||
      typeof cached.generationId !== "string" ||
      !isRouteRegistry(cached.registry) ||
      !wiresMatchRegistry(
        data.entries as SlimModelEntry[],
        cached as unknown as CachedRouteRegistry,
        data.catalogGenerationId
      )
    ) {
      return null;
    }
  }
  return data as unknown as DiskCacheV3;
}

/**
 * Where the route registry for the cache at `path` is kept: a SIDECAR file
 * next to it (`cloud-models-catalog-v3.routes.json`).
 *
 * Its own file because claudish releases before 10.5.0 rewrite the models
 * cache on every refresh and know nothing of the registry: measured
 * 2026-10-14, an installed 10.4.1 in another session replaced the cache with
 * a newer generation and no `routeRegistry`, so the new reader refreshed
 * everything (9.3 s) and the old one erased it again. A sidecar survives them;
 * when its generation no longer matches, only the routes of the cache's
 * generation are fetched (`ensureRouteRegistryReady`).
 */
export function routeRegistryPathFor(path: string): string {
  return path.endsWith(".json") ? `${path.slice(0, -5)}.routes.json` : `${path}.routes.json`;
}

function readSidecarRegistry(path: string): CachedRouteRegistry | null {
  try {
    const raw = JSON.parse(readFileSync(routeRegistryPathFor(path), "utf-8")) as Record<
      string,
      unknown
    >;
    return typeof raw.generationId === "string" && isRouteRegistry(raw.registry)
      ? (raw as unknown as CachedRouteRegistry)
      : null;
  } catch (err) {
    if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
      log(
        `[catalog] unreadable route registry for ${path}: ${err instanceof Error ? err.message : String(err)}`
      );
    }
    return null;
  }
}

function statOrNull(path: string): { mtimeMs: number; size: number } | null {
  try {
    const { mtimeMs, size } = statSync(path);
    return { mtimeMs, size };
  } catch {
    return null;
  }
}

// The request path reads the cache on every request, and the file is several
// MB. Parsed results are memoized per path, keyed by the mtime and size of the
// cache AND its registry sidecar, so a write to either is seen on the next read.
const _readMemo = new Map<string, { key: string; cache: DiskCacheV3 | null }>();

export function _clearAllModelsCacheMemo(): void {
  _readMemo.clear();
}

export function readAllModelsCache(path: string = ALL_MODELS_CACHE_PATH): DiskCacheV3 | null {
  if (!existsSync(path)) return null;
  const main = statOrNull(path);
  if (!main) return null;
  const side = statOrNull(routeRegistryPathFor(path));
  const key = `${main.mtimeMs}:${main.size}|${side ? `${side.mtimeMs}:${side.size}` : "-"}`;
  const memo = _readMemo.get(path);
  if (memo && memo.key === key) return memo.cache;

  let cache: DiskCacheV3 | null;
  try {
    cache = parseAllModelsCache(JSON.parse(readFileSync(path, "utf-8")));
  } catch (err) {
    // Memoized under this mtime and size, so logged once per version of the file.
    log(`[catalog] unreadable ${path}: ${err instanceof Error ? err.message : String(err)}`);
    cache = null;
  }
  if (cache && !cache.routeRegistry && side) {
    const registry = readSidecarRegistry(path);
    if (registry && wiresMatchRegistry(cache.entries, registry, cache.catalogGenerationId)) {
      cache = { ...cache, routeRegistry: registry };
    }
  }
  // Validated RAW above (the parse and the sidecar attach both see every row),
  // then split here, before any reader can see it. This is the choke point that
  // keeps a content-use opt-in wire id from being chosen for a user
  // (`content-use.ts`).
  if (cache) cache = { ...cache, entries: cache.entries.map(splitOptInConnections) };
  _readMemo.set(path, { key, cache });
  return cache;
}

/** Write the registry sidecar for the cache at `path`. */
export function writeRouteRegistry(
  routeRegistry: CachedRouteRegistry,
  path: string = ALL_MODELS_CACHE_PATH
): void {
  writeFileAtomic(routeRegistryPathFor(path), JSON.stringify(routeRegistry));
  _readMemo.delete(path);
}

export function writeAllModelsCache(data: DiskCacheV3, path: string = ALL_MODELS_CACHE_PATH): void {
  writeFileAtomic(path, JSON.stringify(data));
  if (data.routeRegistry) {
    writeFileAtomic(routeRegistryPathFor(path), JSON.stringify(data.routeRegistry));
  }
  _readMemo.delete(path);
}