Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

18.9 KB
Raw Blame
/**
 * catalogResponse.ts — the tail of the /v1/models build: the post-filter chain and
 * the response envelope.
 *
 * Extracted from catalog.ts so the full catalog build and the quota-exclusive
 * short-circuit share one implementation. Two paths emitting the same envelope by
 * copy would drift; the quota path in particular silently lost the discovery
 * mirrors the first time it was written as a duplicate.
 */

import { appendNoThinkingVariants } from "@omniroute/open-sse/utils/noThinkingAlias";
import { appendClaudeEffortVariants } from "@omniroute/open-sse/utils/claudeEffortVariants";
import { appendSyncedEffortVariants } from "@omniroute/open-sse/utils/syncedEffortVariants";
import { appendCcDiscoveryAliases } from "@omniroute/open-sse/utils/ccDiscoveryAliases";
import { isResolvableBuiltinAutoId } from "@omniroute/open-sse/services/autoCombo/builtinCatalog";
import {
  appendFunctionalGatewayMirrors,
  isFunctionalGatewayMirror,
} from "@omniroute/open-sse/utils/functionalGatewayMirrors";
import { isCcAliasGlobalEnabled, getCcAliasSettingsBulk } from "@/lib/db/ccDiscoveryAliases";
import { buildCcAliasPredicate } from "./ccAliasPredicate";
import {
  isFunctionalGatewayGlobalEnabled,
  getFunctionalGatewaySettingsBulk,
} from "@/lib/db/functionalGatewayMirrors";
import { buildFunctionalGatewayPredicate } from "./functionalGatewayPredicate";
import { getPassthroughProviders, REGISTRY } from "@omniroute/open-sse/config/providerRegistry";
import { hasEligibleConnectionForModel } from "@/domain/connectionModelRules";
import { getActiveSyncedCatalog } from "@/lib/db/models/activeSyncedCatalog";
import { getCustomModels } from "@/lib/db/models";
import { isProviderBlockedByIdOrAlias } from "@/shared/utils/noAuthProviders";
import { dedupeExactCatalogIds } from "./catalogDedupe";
import { sortCatalogModelsProviderGrouped } from "./catalogOrder";
import {
  disambiguateCatalogModelNames,
  enrichCatalogModelEntry,
  type CatalogEnrichmentSnapshot,
} from "@/lib/modelMetadataRegistry";
import { createModelCapabilityResolutionSnapshot } from "@/lib/modelCapabilityResolutionSnapshot";
import {
  isModelCatalogNamesEnabled,
  isNoThinkingAliasEnabled,
  isDisableThinkingLevelVariantsEnabled,
  isCatalogMirrorRefinementsEnabled,
} from "@/shared/utils/featureFlags";
import { extractApiKey } from "@/sse/services/auth";
import { maybeOmitCatalogModelName } from "./catalogHelpers";
import { applyCatalogPage, catalogJsonResponse, parseCatalogPage } from "./catalogPagination";
import { isCodexModelCatalogClient } from "./catalogRequest";

type CatalogVariantAuthorizer = (model: Record<string, any>) => boolean | Promise<boolean>;

async function resolveCatalogVariantAuthorizer(
  request: Request
): Promise<CatalogVariantAuthorizer | null> {
  const apiKey = extractApiKey(request);
  if (!apiKey) return null;

  const { getApiKeyMetadata, isModelAllowedForKey } = await import("@/lib/db/apiKeys");
  const keyMeta = await getApiKeyMetadata(apiKey);
  if (!keyMeta || keyMeta.id === "env-key" || keyMeta.allowedQuotas?.length) return null;

  const hasModelRestrictions =
    keyMeta.modelAccessMode === "restricted" ||
    Boolean(keyMeta.allowedModels?.length) ||
    Boolean(keyMeta.blockedModels?.length) ||
    keyMeta.disableNonPublicModels === true;
  if (!hasModelRestrictions) return null;

  return (model) => typeof model.id === "string" && isModelAllowedForKey(apiKey, model.id);
}

async function filterUnauthorizedAppendedVariants(
  baseModels: Array<Record<string, any>>,
  modelsWithVariants: Array<Record<string, any>>,
  authorize: CatalogVariantAuthorizer | null
): Promise<Array<Record<string, any>>> {
  if (!authorize || modelsWithVariants.length <= baseModels.length) return modelsWithVariants;

  const retained = modelsWithVariants.slice(0, baseModels.length);
  for (const variant of modelsWithVariants.slice(baseModels.length)) {
    if (await authorize(variant)) retained.push(variant);
  }
  return retained;
}

/**
 * CATALOG_MIRROR_REFINEMENTS_ENABLED only (refined functional-gateway mirrors).
 *
 * A gateway whose live catalog is authoritative rejects any model outside it at
 * request time ("not available in the active live catalog"), so a mirror for such
 * a model is advertised-but-dead. Match the request path (lookupModelMeta), which
 * receives the mirrored id verbatim: an exact synced id or a custom model
 * (case-insensitive). Deliberately NOT catalogContainsModel — its after-the-slash
 * fallback accepts `dva/claude-sonnet-4-6` because `claude-sonnet-4-6` is listed,
 * yet dispatch rejects it. No authoritative catalog = fail open, as there.
 */
async function buildGatewayLiveCatalogCheck(
  gatewayProviderIds: string[],
  connections: Array<{ provider?: unknown }>
): Promise<(provider: string, modelId: string) => boolean> {
  const gatewayLiveIds = new Map<string, { synced: Set<string>; custom: Set<string> }>();
  for (const provider of gatewayProviderIds) {
    if (!connections.some((c) => c.provider === provider)) continue;
    const catalog = await getActiveSyncedCatalog(provider);
    if (!catalog.authoritative) continue;
    const custom: unknown = await getCustomModels(provider);
    gatewayLiveIds.set(provider, {
      synced: new Set(catalog.models.map((model) => model.id)),
      custom: new Set(
        (Array.isArray(custom) ? custom : []).flatMap((model: { id?: unknown }) =>
          typeof model?.id === "string" ? [model.id.toLowerCase()] : []
        )
      ),
    });
  }
  return (provider, modelId) => {
    const ids = gatewayLiveIds.get(provider);
    return !ids || ids.synced.has(modelId) || ids.custom.has(modelId.toLowerCase());
  };
}

/**
 * Post-filter chain applied AFTER the API-key filter, so variants and mirrors are
 * only derived from models the caller may actually see.
 *
 * Shared by the full build and by the quota-exclusive short-circuit: the quota path
 * returns early, but it still owes the caller these steps — the discovery mirrors in
 * particular are what let Claude Code see a quota pool's models at all.
 */
export async function applyCatalogPostFilters(
  request: Request,
  models: Array<Record<string, any>>,
  ctx: {
    connections: any;
    prefixMode: string;
    aliasToProviderId: Record<string, string>;
    hideNoThinkVariants?: boolean;
    /** Raw settings.blockedProviders; blocked gateways never carry mirrors. */
    blockedProviders?: unknown;
    authorizeSyntheticModel?: CatalogVariantAuthorizer;
  }
): Promise<Array<Record<string, any>>> {
  const yieldTurn = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
  let finalModels = models;
  const authorizeSyntheticModel =
    ctx.authorizeSyntheticModel ?? (await resolveCatalogVariantAuthorizer(request));

  // variants are only generated for surviving models.
  if (new URL(request.url).searchParams.get("configuredOnly") === "true") {
    finalModels = finalModels.filter((m) => {
      if (!m.root) return true;
      return hasEligibleConnectionForModel(ctx.connections, m.root);
    });
  }

  // #9147: the variant-append passes each walk the full model list (O(n) per pass),
  // so a catalog-scale build must not run all of them in one synchronous stretch.
  // Yield once between the expensive passes to let the event loop breathe.
  await yieldTurn();

  // Advertise Claude reasoning-effort variants (claude/<model>-{low,medium,high[,xhigh]}).
  // Derived from the already key-filtered list so a variant only appears when its real
  // model is permitted. Runs before the no-thinking pass: the gateway already routes these
  // suffixed ids (claudeEffortVariant.ts), this just makes them selectable in catalog-only
  // clients (OpenCode) that can't set a reasoning_effort config the way VS Code does.
  // Gated like the synced-effort pass below: OMNIROUTE_DISABLE_THINKING_LEVEL_VARIANTS suppresses -low/-medium/-high catalog variants.
  if (!isDisableThinkingLevelVariantsEnabled()) {
    const beforeClaudeEffortVariants = finalModels;
    finalModels = await filterUnauthorizedAppendedVariants(
      beforeClaudeEffortVariants,
      appendClaudeEffortVariants(
        beforeClaudeEffortVariants,
        ctx.prefixMode === "canonical" ? ctx.aliasToProviderId : undefined
      ),
      authorizeSyntheticModel
    );
  }

  // Advertise no-thinking gateway variants (Fase 8.1). Derived from the already
  // key-filtered list, so a variant only appears when its real model is permitted.
  // #9418: skip when hideNoThinkVariants is on — the ids are still routable when
  // sent explicitly, just not advertised in the catalog. The NO_THINKING_ALIAS_ENABLED
  // feature flag is the stronger switch: it also stops the ids from routing (see
  // src/sse/handlers/chat.ts), so nothing is advertised when it is off. Resolved once
  // here and injected, keeping the open-sse helper I/O-free (one flag read per catalog
  // build, not one per model).
  if (!ctx.hideNoThinkVariants) {
    const beforeNoThinkingVariants = finalModels;
    finalModels = await filterUnauthorizedAppendedVariants(
      beforeNoThinkingVariants,
      appendNoThinkingVariants(
        beforeNoThinkingVariants,
        ctx.prefixMode === "canonical" ? ctx.aliasToProviderId : undefined,
        { featureEnabled: isNoThinkingAliasEnabled() }
      ),
      authorizeSyntheticModel
    );
  }

  // Advertise `claude/<id>` discovery-mirror aliases so Claude Code's gateway
  // model discovery (which only lists `claude`/`anthropic`-prefixed ids) can see
  // every model this gate allows. Gated 3 levels deep (global > provider > model,
  // see ccDiscoveryAliases.ts) and default-off. Deliberately NOT filtered by model
  // `type` here — non-chat entries (embedding/image/etc.) get a mirror too; the
  // gate itself (default-off + explicit opt-in) is the operator's filter, not a
  // hardcoded type allowlist.
  // CATALOG_MIRROR_REFINEMENTS_ENABLED (default off): resolved once per build. Off keeps
  // both mirror passes exactly as before; on mirrors claude/ effort variants, drops
  // mirrors that cannot resolve, and checks gateways against what they will receive.
  const mirrorRefinements = isCatalogMirrorRefinementsEnabled();
  const ccAliasGlobal = isCcAliasGlobalEnabled();
  const ccAliasSettings = getCcAliasSettingsBulk();
  if (ccAliasGlobal || ccAliasSettings.providers.size > 0 || ccAliasSettings.models.size > 0) {
    finalModels = appendCcDiscoveryAliases(
      finalModels,
      buildCcAliasPredicate({
        global: ccAliasGlobal,
        providers: ccAliasSettings.providers,
        models: ccAliasSettings.models,
      }),
      { refined: mirrorRefinements, isResolvableAutoId: isResolvableBuiltinAutoId }
    );
  }

  // Advertise `<gateway-alias>/<id>` functional-gateway mirrors so discovery
  // clients surface the route that actually has a credential, even when the
  // canonical owner provider has none (e.g. `deepseek/deepseek-v4-flash` fails
  // 404 but `agentrouter/deepseek/deepseek-v4-flash` returns 200). Gated 3
  // levels deep (global > provider > model, see db/functionalGatewayMirrors.ts)
  // and default-off. Only emits a mirror when the canonical owner has no
  // eligible connection for the model AND a passthrough gateway with an active
  // credential covers it.
  const fgGlobal = isFunctionalGatewayGlobalEnabled();
  const fgSettings = getFunctionalGatewaySettingsBulk();
  if (fgGlobal || fgSettings.providers.size > 0 || fgSettings.models.size > 0) {
    const gatewayProviderIds = mirrorRefinements
      ? [...getPassthroughProviders()].filter(
          (provider) => !isProviderBlockedByIdOrAlias(provider, ctx.blockedProviders)
        )
      : [...getPassthroughProviders()];
    const gatewayServes = mirrorRefinements
      ? await buildGatewayLiveCatalogCheck(gatewayProviderIds, ctx.connections)
      : () => true;
    finalModels = appendFunctionalGatewayMirrors(finalModels, {
      gatewayProviderIds,
      isGateway: (provider) => getPassthroughProviders().has(provider),
      gatewayAlias: (provider) => REGISTRY[provider]?.alias || provider,
      gatewayCovers: (provider, modelId) =>
        hasEligibleConnectionForModel(
          ctx.connections.filter((c) => c.provider === provider),
          modelId
        ) && gatewayServes(provider, modelId),
      gatewayHasConnection: (provider) => ctx.connections.some((c) => c.provider === provider),
      canonicalOwnerHasConnection: (owner) =>
        hasEligibleConnectionForModel(
          ctx.connections.filter((c) => c.provider === owner),
          owner
        ),
      refined: mirrorRefinements,
    });
    finalModels = finalModels.filter((m) =>
      buildFunctionalGatewayPredicate({ global: fgGlobal, ...fgSettings })(m)
    );
  }

  await yieldTurn();

  // #7694: advertise `<provider>/<model>-<tier>` variants for synced models that
  // captured `reasoning.supported_efforts` at sync time (capabilities.effort_tiers).
  // Derived from the already key-filtered list; skips codex/kimi (own suffix mechanism).
  if (!isDisableThinkingLevelVariantsEnabled()) {
    const beforeSyncedEffortVariants = finalModels;
    finalModels = await filterUnauthorizedAppendedVariants(
      beforeSyncedEffortVariants,
      appendSyncedEffortVariants(beforeSyncedEffortVariants),
      authorizeSyntheticModel
    );
  }

  await yieldTurn();

  // #4424 follow-up — drop exact-duplicate ids that slip through the per-source push
  // guards (e.g. `codex/gpt-5.5`, `veo-free/seedance` listed twice). Keyed by listing
  // identity (id, type, subtype) so the intentional same-id audio transcription/speech
  // pair survives. Independent of MODELS_CATALOG_PREFIX_MODE; runs as the final guard.
  finalModels = dedupeExactCatalogIds(finalModels);

  return finalModels;
}

/**
 * Functional-gateway mirrors remain gateway-prefixed through request-time policy
 * enforcement, so they must authorize that final public ID. Other synthetic IDs
 * are normalized back to their base model before policy enforcement and keep the
 * base model's permission by design.
 */
export async function filterUnauthorizedFunctionalGatewayMirrors(
  models: Array<Record<string, unknown>>,
  apiKey: string,
  isModelAllowed: (key: string, modelId: string) => Promise<boolean>
): Promise<Array<Record<string, unknown>>> {
  const filtered: Array<Record<string, unknown>> = [];
  for (const model of models) {
    if (!isFunctionalGatewayMirror(model)) {
      filtered.push(model);
      continue;
    }

    if (typeof model.id === "string" && (await isModelAllowed(apiKey, model.id))) {
      filtered.push(model);
    }
  }
  return filtered;
}

/**
 * Enrich the selected models and serialise the catalog response.
 *
 * Shared by the full build and by the quota-exclusive short-circuit so both emit a
 * byte-identical envelope. `getContextFallback` supplies the registry default
 * context length for non-combo entries; the quota path passes a no-op because its
 * entries are all `owned_by: "combo"`, which skips enrichment entirely.
 */
export async function finalizeCatalogResponse(
  request: Request,
  finalModels: Array<Record<string, unknown>>,
  getContextFallback: (model: Record<string, unknown>) => number | undefined,
  headers: Record<string, string>,
  enrichmentSnapshot?: CatalogEnrichmentSnapshot
): Promise<Response> {
  const apiKey = extractApiKey(request);
  if (apiKey) {
    const { getApiKeyMetadata, isModelAllowedForKey } = await import("@/lib/db/apiKeys");
    const keyMeta = await getApiKeyMetadata(apiKey);
    if (keyMeta && keyMeta.id !== "env-key" && !keyMeta.allowedQuotas?.length) {
      finalModels = await filterUnauthorizedFunctionalGatewayMirrors(
        finalModels,
        apiKey,
        isModelAllowedForKey
      );
    }
  }

  const includeModelNames = isModelCatalogNamesEnabled();
  // #9147: enrichment is the most expensive single stage of the catalog build —
  // per-entry provider/model resolution plus pricing + token/context override
  // lookups. Two fixes so a large catalog cannot pin the Node.js thread here:
  //  (1) bulk-load the synced-capability + override tables ONCE into an in-memory
  //      snapshot (#9199 machinery) so per-entry enrichment never hits SQLite;
  //  (2) yield to the event loop every `YIELD_EVERY` entries so even the remaining
  //      per-entry work is interleaved with other callers / the dashboard WS.
  const yieldTurn = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
  await yieldTurn();
  const capabilityResolutionSnapshot =
    enrichmentSnapshot?.capabilityResolutionSnapshot ?? createModelCapabilityResolutionSnapshot();
  const enriched: Array<Record<string, unknown>> = [];
  const catYIELD_EVERY = 5;
  let catEnrichCount = 0;
  for (const model of finalModels) {
    let listedModel: Record<string, unknown>;
    if (model.owned_by === "combo") {
      listedModel = maybeOmitCatalogModelName(model, includeModelNames);
    } else {
      const entry = enrichCatalogModelEntry(model, undefined, {
        ...enrichmentSnapshot,
        capabilityResolutionSnapshot,
      });
      const fallbackContextLength = getContextFallback(entry);
      listedModel = fallbackContextLength
        ? { ...entry, context_length: fallbackContextLength }
        : entry;
      listedModel = maybeOmitCatalogModelName(listedModel, includeModelNames);
    }
    enriched.push(listedModel);
    catEnrichCount++;
    if (catEnrichCount % catYIELD_EVERY === 0) {
      await yieldTurn();
    }
  }
  await yieldTurn();
  const enrichedModels = disambiguateCatalogModelNames(enriched);
  await yieldTurn();
  const orderedModels = sortCatalogModelsProviderGrouped(enrichedModels);
  await yieldTurn();
  // Codex CLI compatibility: its model-catalog refresh (codex_models_manager) does
  // GET /v1/models?client_version=<v> and decodes a JSON object with a TOP-LEVEL
  // `models` array, so the OpenAI-standard `{object,data}` shape makes it fail with
  // "missing field `models`" and log "failed to refresh available models" on every
  // startup. For codex clients only (detected by the codex originator/user-agent) we add
  // an EMPTY `models: []` so the decode succeeds and the error disappears. Every other
  // OpenAI consumer keeps the byte-identical `{object,data}` response.
  //
  // We deliberately keep it EMPTY rather than mirroring the catalog: codex replaces its
  // built-in per-model agent prompt (`base_instructions`, ~21k chars) with whatever a
  // populated entry carries for the selected model, so emitting our models with an
  // empty/foreign `base_instructions` would drop codex's agent prompt to nothing and
  // break its agent behavior (verified empirically against codex 0.137). An empty array
  // keeps codex on its built-in model info — same inference as today, minus the error.
  const page = parseCatalogPage(request);
  const paged = applyCatalogPage(orderedModels, page);
  const responseBody: Record<string, unknown> = {
    object: "list",
    data: paged.models,
  };
  if (page.limit != null || page.after) {
    responseBody.has_more = paged.hasMore;
    if (paged.lastId) responseBody.last_id = paged.lastId;
  }
  if (isCodexModelCatalogClient(request)) {
    responseBody.models = [];
  }

  return catalogJsonResponse(responseBody, headers);
}