Skip to content

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

22.5 KB
Raw Blame
import { log } from "../logger.js";
import {
  type CachedSubscriptionPlan,
  type DiskCacheV3,
  type SlimModelEntry,
  isCachedSubscriptionPlan,
  isSlimModelEntry,
  readAllModelsCache,
  wiresMatchRegistry,
  writeAllModelsCache,
  writeRouteRegistry,
} from "./all-models-cache.js";
import { catalogRouteMatchesProvider } from "./catalog-route-bindings.js";
import { CATALOG_V3_ACCEPT, type CatalogV3Envelope, parseCatalogV3Envelope } from "./catalog-v3.js";
import {
  type CachedRouteRegistry,
  type RouteRegistry,
  isRouteRegistry,
} from "./connection-wire.js";
import { allConnections, splitOptInConnections } from "./content-use.js";
import { _clearChatCapabilityIndex } from "./transport/probe-discovery.js";

const DEFAULT_CATALOG_URL =
  "https://us-central1-claudish-6da10.cloudfunctions.net/queryModels?status=all&catalog=slim&includeRouteVariants=true&limit=1000";
const MAX_CATALOG_PAGES = 40;
const CATALOG_PAGE_LIMIT = 1000;

function catalogUrl(): string {
  return process.env.CLAUDISH_CATALOG_URL ?? DEFAULT_CATALOG_URL;
}

function derivePlansUrl(modelsUrl: string): string {
  try {
    const url = new URL(modelsUrl);
    url.pathname = url.pathname.replace(/\/queryModels$/, "/queryPlans");
    url.search = "";
    return url.toString();
  } catch {
    return "https://us-central1-claudish-6da10.cloudfunctions.net/queryPlans";
  }
}

function plansUrl(): string {
  return process.env.CLAUDISH_PLANS_URL ?? derivePlansUrl(catalogUrl());
}

/** `queryModels?catalog=routes&generationId=<id>` on the same host as the model list. */
export function buildRoutesUrl(modelsUrl: string, generationId: string): string {
  const url = new URL(modelsUrl);
  url.search = "";
  url.searchParams.set("catalog", "routes");
  url.searchParams.set("generationId", generationId);
  return url.toString();
}

export type DiskCache = DiskCacheV3;

export type RefreshOutcome =
  | { kind: "refreshed"; modelCount: number; catalogGenerationId?: string; pages?: number }
  | {
      kind: "fetch_failed";
      reason:
        | "timeout"
        | "network"
        | "http_error"
        | "empty"
        | "disabled"
        | "generation_mismatch"
        | "incomplete";
    }
  | { kind: "incompatible"; serverContractVersion: number | null };

export interface ModelResolutionResult {
  resolvedId: string;
  wasResolved: boolean;
  sourceLabel: string;
}

let _memCache: SlimModelEntry[] | null = null;
let _catalogEntriesForTest: SlimModelEntry[] | null | undefined;
let _warmPromise: Promise<void> | null = null;

export function getCatalogEntries(): SlimModelEntry[] | null {
  if (_catalogEntriesForTest !== undefined) return _catalogEntriesForTest;
  if (_memCache) return _memCache;

  const cache = readAllModelsCache();
  if (!cache || cache.entries.length === 0) return null;
  _memCache = cache.entries;
  return _memCache;
}

export function latestOpusModelId(): string | null {
  return latestAnthropicTierModelId("opus");
}

export function latestAnthropicTierModelId(tier: "opus" | "sonnet" | "haiku"): string | null {
  const entries = getCatalogEntries();
  if (!entries) return null;
  const family = new RegExp(`^claude-${tier}-`, "i");
  const matches = entries.filter((entry) => family.test(entry.modelId));
  if (matches.length === 0) return null;
  matches.sort((a, b) => {
    const byDate = (b.releaseDate ?? "").localeCompare(a.releaseDate ?? "");
    if (byDate !== 0) return byDate;
    const aFast = /-fast$/i.test(a.modelId) ? 1 : 0;
    const bFast = /-fast$/i.test(b.modelId) ? 1 : 0;
    if (aFast !== bFast) return aFast - bFast;
    return b.modelId.localeCompare(a.modelId);
  });
  return matches[0].modelId;
}

export function isCatalogWarm(): boolean {
  return _memCache !== null && _memCache.length > 0;
}

export function _setCatalogEntriesForTest(entries: SlimModelEntry[] | null): void {
  // The same normalisation as every other way entries reach memory, so a test
  // seeds exactly what production reads (`content-use.ts`).
  _catalogEntriesForTest = entries ? entries.map(splitOptInConnections) : entries;
}

export function _resetCatalogClient(): void {
  _catalogEntriesForTest = undefined;
  _memCache = null;
  _warmPromise = null;
}

/** Every wire id the entry publishes, opt-in included: an exact reverse lookup. */
function allExternalIds(entry: SlimModelEntry): string[] {
  return allConnections(entry).flatMap((connection) =>
    typeof connection.externalModelId === "string" ? [connection.externalModelId] : []
  );
}

/**
 * A wire id that redirects over time, e.g. OpenRouter's `~moonshotai/kimi-latest`
 * ("always redirects to the latest model in the Kimi family"). Today it may land on
 * the same model as the exact id; the day the vendor ships a successor it lands
 * somewhere else, silently.
 */
export function isMovingPointer(wireId: string): boolean {
  const lastSegment = wireId.split("/").pop() ?? wireId;
  return wireId.startsWith("~") || /(^|-)latest$/i.test(lastSegment);
}

/**
 * The wire id to send `provider` for a catalog model.
 *
 * The catalog can publish several connections to one provider for one model: the
 * exact id and a moving pointer. A user who asked for a pinned model gets the EXACT
 * id — never a pointer claudish chose for them, because a pointer is the vendor's
 * alias, not the model they named. Taking the first matching row, as this once did,
 * sent `~moonshotai/kimi-latest` for `kimi-k3` because the catalog happened to list
 * the pointer first. With no exact id the answer is null, not the pointer.
 *
 * A model whose own canonical id is pointer-shaped (`chatgpt-4o-latest`) is the one
 * case where a pointer-shaped wire id is exactly what was asked for.
 */
export function externalIdFor(entry: SlimModelEntry, provider: string): string | null {
  const wireIds = (entry.aggregators ?? []).flatMap((candidate) =>
    candidate.routeStatus === "mapped" &&
    catalogRouteMatchesProvider(candidate.route, provider) &&
    typeof candidate.externalModelId === "string"
      ? [candidate.externalModelId]
      : []
  );
  if (wireIds.length === 0) return null;
  if (isMovingPointer(entry.modelId)) return wireIds[0] ?? null;
  return wireIds.find((wireId) => !isMovingPointer(wireId)) ?? null;
}

/** Whether `entry` maps `wireId` exactly on a route bound to `provider`, opt-in rows included. */
function publishesWireIdFor(entry: SlimModelEntry, provider: string, wireId: string): boolean {
  return allConnections(entry).some(
    (connection) =>
      connection.routeStatus === "mapped" &&
      connection.externalModelId === wireId &&
      catalogRouteMatchesProvider(connection.route, provider)
  );
}

export function resolveExternalId(
  userInput: string,
  provider: string,
  cachePath?: string
): string | null {
  const entries = cachePath ? readAllModelsCache(cachePath)?.entries : getCatalogEntries();

  if (userInput.includes("/")) {
    if (entries?.some((entry) => allExternalIds(entry).includes(userInput))) return userInput;
    return userInput;
  }
  if (!entries) return null;

  // An id this provider publishes, typed exactly, is its own answer — opt-in
  // rows included. This is how `[email protected]` is sent
  // verbatim: every step below CHOOSES a wire id, and a chosen one is never a
  // content-use opt-in (`content-use.ts`).
  if (entries.some((entry) => publishesWireIdFor(entry, provider, userInput))) return userInput;

  const byModelId = entries.find((entry) => entry.modelId === userInput);
  if (byModelId) return externalIdFor(byModelId, provider);

  const byAlias = entries.find((entry) => entry.aliases.includes(userInput));
  if (byAlias) {
    const resolved = externalIdFor(byAlias, provider);
    if (resolved) return resolved;
  }

  for (const entry of entries) {
    if (allExternalIds(entry).includes(userInput)) {
      const resolved = externalIdFor(entry, provider);
      if (resolved) return resolved;
    }
  }

  const suffix = `/${userInput}`;
  for (const entry of entries) {
    const resolved = externalIdFor(entry, provider);
    if (resolved?.endsWith(suffix)) return resolved;
  }

  const lowerSuffix = suffix.toLowerCase();
  for (const entry of entries) {
    const resolved = externalIdFor(entry, provider);
    if (resolved?.toLowerCase().endsWith(lowerSuffix)) return resolved;
  }
  return null;
}

export function resolveModelNameSync(
  userInput: string,
  targetProvider: string
): ModelResolutionResult {
  if (targetProvider !== "openrouter" && userInput.includes("/")) {
    return { resolvedId: userInput, wasResolved: false, sourceLabel: "passthrough" };
  }
  const resolved = resolveExternalId(userInput, targetProvider);
  if (!resolved || resolved === userInput) {
    return { resolvedId: userInput, wasResolved: false, sourceLabel: "passthrough" };
  }
  return { resolvedId: resolved, wasResolved: true, sourceLabel: `${targetProvider} catalog` };
}

export function resolveTargetForCatalog(
  target: string,
  isExplicitProvider: boolean,
  model: string,
  provider: string,
  resolve: (model: string, provider: string) => ModelResolutionResult = resolveModelNameSync
): { target: string; resolution: ModelResolutionResult | null } {
  if (!isExplicitProvider) return { target, resolution: null };
  const resolution = resolve(model, provider);
  return {
    target: resolution.wasResolved ? `${provider}@${resolution.resolvedId}` : target,
    resolution,
  };
}

export function logResolution(
  userInput: string,
  result: ModelResolutionResult,
  quiet = false
): void {
  if (result.wasResolved && !quiet) {
    process.stderr.write(
      `[Model] Resolved "${userInput}" → "${result.resolvedId}" (${result.sourceLabel})\n`
    );
  }
}

export function catalogWarmDisabledFor(value: string | undefined): boolean {
  return value === "1";
}

function catalogWarmDisabled(): boolean {
  return catalogWarmDisabledFor(process.env.CLAUDISH_DISABLE_CATALOG_WARM);
}

export function buildCatalogPageUrl(
  baseUrl: string,
  cursor: string | undefined,
  limit: number,
  generationId?: string
): string {
  const url = new URL(baseUrl);
  url.searchParams.delete("offset");
  url.searchParams.delete("revision");
  // Plan membership points at deprecated models and at route variants, and the
  // backend returns neither unless asked. Without these two, `kimi-code`'s member
  // `kimi-k3-256k` (a context=256k route variant) had no model row at all. Set here,
  // not only in the default URL, so a CLAUDISH_CATALOG_URL override cannot drop them.
  url.searchParams.set("status", "all");
  url.searchParams.set("includeRouteVariants", "true");
  url.searchParams.set("limit", String(limit));
  if (cursor) url.searchParams.set("cursor", cursor);
  else url.searchParams.delete("cursor");
  if (generationId) url.searchParams.set("generationId", generationId);
  else url.searchParams.delete("generationId");
  return url.toString();
}

interface ModelsPageData {
  mode: "slim";
  models: SlimModelEntry[];
  total: number;
  nextCursor?: string;
}

interface PlansPageData {
  plans: CachedSubscriptionPlan[];
  total: number;
  nextCursor?: string;
}

type FetchFailure =
  | { ok: false; reason: "timeout" | "network" | "http_error" }
  | { ok: false; reason: "incompatible"; serverContractVersion: number | null };

async function fetchEnvelope<T>(
  url: string,
  timeoutMs: number
): Promise<{ ok: true; envelope: CatalogV3Envelope<T> } | FetchFailure> {
  let response: Response;
  try {
    response = await fetch(url, {
      headers: { Accept: CATALOG_V3_ACCEPT },
      signal: AbortSignal.timeout(timeoutMs),
    });
  } catch (error) {
    const name = (error as { name?: string } | null)?.name;
    return {
      ok: false,
      reason: name === "TimeoutError" || name === "AbortError" ? "timeout" : "network",
    };
  }

  let body: unknown;
  try {
    body = await response.json();
  } catch {
    if (response.status === 426) {
      return { ok: false, reason: "incompatible", serverContractVersion: null };
    }
    return { ok: false, reason: response.ok ? "network" : "http_error" };
  }

  const statedVersion =
    body &&
    typeof body === "object" &&
    typeof (body as { contractVersion?: unknown }).contractVersion === "number"
      ? ((body as { contractVersion: number }).contractVersion ?? null)
      : null;
  if (response.status === 426 || (statedVersion !== null && statedVersion !== 3)) {
    return { ok: false, reason: "incompatible", serverContractVersion: statedVersion };
  }
  if (!response.ok) return { ok: false, reason: "http_error" };

  const envelope = parseCatalogV3Envelope<T>(body);
  if (!envelope) return { ok: false, reason: "network" };
  return { ok: true, envelope };
}

export interface RefreshCatalogOptions {
  cachePath?: string;
}

export async function refreshCatalog(
  timeoutMs: number,
  options: RefreshCatalogOptions = {}
): Promise<RefreshOutcome> {
  if (catalogWarmDisabled()) return { kind: "fetch_failed", reason: "disabled" };
  // A generation can activate between the model pages and the registry read.
  // Never mix two: start over once, then report the mismatch.
  const first = await refreshCatalogOnce(timeoutMs, options);
  if (first.kind === "fetch_failed" && first.reason === "generation_mismatch") {
    return refreshCatalogOnce(timeoutMs, options);
  }
  return first;
}

async function refreshCatalogOnce(
  timeoutMs: number,
  options: RefreshCatalogOptions
): Promise<RefreshOutcome> {
  const entries: SlimModelEntry[] = [];
  let generationId: string | undefined;
  let generatedAt: string | undefined;
  let cursor: string | undefined;
  let pages = 0;
  const seenCursors = new Set<string>();
  let expectedTotal: number | undefined;

  for (;;) {
    const result = await fetchEnvelope<ModelsPageData>(
      buildCatalogPageUrl(catalogUrl(), cursor, CATALOG_PAGE_LIMIT, generationId),
      timeoutMs
    );
    if (!result.ok) {
      if (result.reason === "incompatible") {
        return { kind: "incompatible", serverContractVersion: result.serverContractVersion };
      }
      return { kind: "fetch_failed", reason: pages === 0 ? result.reason : "incomplete" };
    }

    const { envelope } = result;
    if (generationId === undefined) {
      generationId = envelope.generationId;
      generatedAt = envelope.generatedAt;
    } else if (envelope.generationId !== generationId) {
      return { kind: "fetch_failed", reason: "generation_mismatch" };
    }
    if (
      envelope.data.mode !== "slim" ||
      !Array.isArray(envelope.data.models) ||
      !envelope.data.models.every(isSlimModelEntry)
    ) {
      return { kind: "fetch_failed", reason: pages === 0 ? "empty" : "incomplete" };
    }
    if (!Number.isSafeInteger(envelope.data.total) || envelope.data.total < 0) {
      return { kind: "fetch_failed", reason: "incomplete" };
    }
    if (expectedTotal === undefined) expectedTotal = envelope.data.total;
    else if (envelope.data.total !== expectedTotal) {
      return { kind: "fetch_failed", reason: "incomplete" };
    }

    entries.push(...envelope.data.models);
    pages++;
    const nextCursor = envelope.data.nextCursor;
    if (!nextCursor) break;
    if (seenCursors.has(nextCursor) || pages >= MAX_CATALOG_PAGES) {
      return { kind: "fetch_failed", reason: "incomplete" };
    }
    seenCursors.add(nextCursor);
    cursor = nextCursor;
  }

  if (!generationId || !generatedAt || entries.length === 0) {
    return { kind: "fetch_failed", reason: "empty" };
  }
  if (
    entries.length !== expectedTotal ||
    new Set(entries.map((entry) => entry.modelId)).size !== entries.length
  ) {
    return { kind: "fetch_failed", reason: "incomplete" };
  }

  const planResult = await fetchSubscriptionPlans(timeoutMs, generationId);
  if (!planResult.ok) {
    if (planResult.reason === "incompatible") {
      return { kind: "incompatible", serverContractVersion: planResult.serverContractVersion };
    }
    return { kind: "fetch_failed", reason: planResult.reason };
  }

  const registryResult = await fetchRouteRegistry(timeoutMs, generationId);
  if (!registryResult.ok) {
    if (registryResult.reason === "incompatible") {
      return { kind: "incompatible", serverContractVersion: registryResult.serverContractVersion };
    }
    return { kind: "fetch_failed", reason: registryResult.reason };
  }
  const routeRegistry: CachedRouteRegistry = { generationId, registry: registryResult.registry };
  if (!wiresMatchRegistry(entries, routeRegistry, generationId)) {
    return { kind: "fetch_failed", reason: "incomplete" };
  }

  // The disk keeps the RAW rows (validated above, and what older builds read);
  // memory gets them split, exactly as `readAllModelsCache` hands them out.
  const normalised = entries.map(splitOptInConnections);
  const models = normalised.flatMap((entry) => {
    const id = externalIdFor(entry, "openrouter");
    return id ? [{ id }] : [];
  });
  const cache: DiskCacheV3 = {
    version: 3,
    lastUpdated: generatedAt,
    entries,
    models,
    plans: planResult.plans,
    catalogGenerationId: generationId,
    routeRegistry,
  };

  writeAllModelsCache(cache, options.cachePath);
  // The chat-capability projection is memoized for 60s and keyed by cache path,
  // so without this a refresh leaves it serving the PREVIOUS generation for up
  // to a minute. That was survivable while an unrecognised model was offered
  // anyway; now that admission requires positive evidence, a stale projection
  // withholds models the refresh just described. Its doc comment already said
  // "after a catalog refresh" — nothing had ever called it.
  _clearChatCapabilityIndex();
  _memCache = normalised;
  _warmPromise = Promise.resolve();
  return {
    kind: "refreshed",
    modelCount: entries.length,
    catalogGenerationId: generationId,
    pages,
  };
}

async function fetchSubscriptionPlans(
  timeoutMs: number,
  generationId: string
): Promise<
  | { ok: true; plans: CachedSubscriptionPlan[] }
  | FetchFailure
  | { ok: false; reason: "empty" | "generation_mismatch" | "incomplete" }
> {
  const plans: CachedSubscriptionPlan[] = [];
  let cursor: string | undefined;
  let pages = 0;
  const seenCursors = new Set<string>();
  let expectedTotal: number | undefined;

  for (;;) {
    const result = await fetchEnvelope<PlansPageData>(
      buildCatalogPageUrl(plansUrl(), cursor, 100, generationId),
      timeoutMs
    );
    if (!result.ok) return result;
    if (result.envelope.generationId !== generationId) {
      return { ok: false, reason: "generation_mismatch" };
    }
    if (
      !Array.isArray(result.envelope.data.plans) ||
      !result.envelope.data.plans.every(isCachedSubscriptionPlan)
    ) {
      return { ok: false, reason: plans.length === 0 ? "empty" : "incomplete" };
    }
    if (!Number.isSafeInteger(result.envelope.data.total) || result.envelope.data.total < 0) {
      return { ok: false, reason: "incomplete" };
    }
    if (expectedTotal === undefined) expectedTotal = result.envelope.data.total;
    else if (result.envelope.data.total !== expectedTotal) {
      return { ok: false, reason: "incomplete" };
    }
    plans.push(...result.envelope.data.plans);
    pages++;
    const nextCursor = result.envelope.data.nextCursor;
    if (!nextCursor) break;
    if (seenCursors.has(nextCursor) || pages >= MAX_CATALOG_PAGES) {
      return { ok: false, reason: "incomplete" };
    }
    seenCursors.add(nextCursor);
    cursor = nextCursor;
  }

  if (plans.length === 0) return { ok: false, reason: "empty" };
  if (
    plans.length !== expectedTotal ||
    new Set(plans.map((plan) => plan.id)).size !== plans.length
  ) {
    return { ok: false, reason: "incomplete" };
  }
  return { ok: true, plans };
}

async function fetchRouteRegistry(
  timeoutMs: number,
  generationId: string
): Promise<
  | { ok: true; registry: RouteRegistry }
  | FetchFailure
  | { ok: false; reason: "empty" | "generation_mismatch" }
> {
  const result = await fetchEnvelope<{ mode?: string; registry?: unknown }>(
    buildRoutesUrl(catalogUrl(), generationId),
    timeoutMs
  );
  if (!result.ok) return result;
  if (result.envelope.generationId !== generationId) {
    return { ok: false, reason: "generation_mismatch" };
  }
  const { registry } = result.envelope.data;
  if (result.envelope.data.mode !== "routes" || !isRouteRegistry(registry)) {
    return { ok: false, reason: "empty" };
  }
  return { ok: true, registry };
}

function startCatalogWarm(): Promise<void> {
  if (_warmPromise) return _warmPromise;
  const promise = refreshCatalog(8000).then(
    (result) => {
      if (result.kind === "refreshed") return;
      // Without this line the reason is lost: callers only see "no snapshot".
      log(
        `[catalog] refresh failed: ${result.kind === "fetch_failed" ? result.reason : `incompatible contract ${result.serverContractVersion ?? "unknown"}`}`
      );
      if (_warmPromise === promise) _warmPromise = null;
    },
    (err: unknown) => {
      // A throw (a cache write refused, a bad CLAUDISH_CATALOG_URL) must not stay
      // the answer for the life of the process: the next caller tries again.
      log(`[catalog] refresh threw: ${err instanceof Error ? err.message : String(err)}`);
      if (_warmPromise === promise) _warmPromise = null;
    }
  );
  _warmPromise = promise;
  return promise;
}

export async function warmCatalog(): Promise<void> {
  await startCatalogWarm();
}

export async function ensureCatalogReady(timeoutMs = 5000): Promise<void> {
  if (isCatalogWarm() || (readAllModelsCache()?.entries.length ?? 0) > 0) return;
  await waitForCatalogWarm(timeoutMs);
}

/**
 * Like {@link ensureCatalogReady}, for the request path: a cache written before
 * claudish read wires has models but no route registry, and no request may be
 * built from it. Such a cache is refreshed rather than accepted.
 */
export async function ensureRouteRegistryReady(timeoutMs = 5000): Promise<void> {
  const cache = readAllModelsCache();
  if (cache?.routeRegistry) return;
  // Models cached, registry missing or of another generation (an older claudish
  // rewrote the models): fetch only the routes of THIS generation — one small
  // request instead of the whole refresh.
  if (cache && !catalogWarmDisabled()) {
    const result = await fetchRouteRegistry(timeoutMs, cache.catalogGenerationId);
    if (result.ok) {
      const routeRegistry = { generationId: cache.catalogGenerationId, registry: result.registry };
      if (wiresMatchRegistry(cache.entries, routeRegistry, cache.catalogGenerationId)) {
        writeRouteRegistry(routeRegistry);
        return;
      }
    }
  }
  await waitForCatalogWarm(timeoutMs);
}

async function waitForCatalogWarm(timeoutMs: number): Promise<void> {
  let timedOut = false;
  await Promise.race([
    startCatalogWarm(),
    new Promise<void>((resolve) =>
      setTimeout(() => {
        timedOut = true;
        resolve();
      }, timeoutMs)
    ),
  ]);
  if (timedOut)
    log(`[catalog] still refreshing after ${timeoutMs} ms; the caller goes on without it`);
}