Skip to content

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

8.2 KB
Raw Blame
/**
 * Resolve the ONE catalog connection a request goes to, with its `wire` and its
 * route profile from the registry of the same generation.
 *
 * A connection is the claudish provider's exact route binding plus the exact
 * wire id. Nothing is matched by family, sibling id or model-level field: when
 * the catalog does not publish this provider for this model, the answer says so
 * and the caller decides, rather than borrowing another connection's wire.
 */
import type { AggregatorEntry } from "../model-loader.js";
import {
  ALL_MODELS_CACHE_PATH,
  type SlimModelEntry,
  readAllModelsCache,
} from "./all-models-cache.js";
import { isMovingPointer } from "./catalog-client.js";
import { type CatalogRouteBinding, catalogRouteForProvider } from "./catalog-route-bindings.js";
import {
  type ConnectionWire,
  type KnownWire,
  type RouteProfile,
  type RouteRegistry,
  type WireApi,
  routeProfile,
  wireRequestUrl,
} from "./connection-wire.js";
import { allConnections } from "./content-use.js";

export interface ResolvedConnection {
  /** The claudish provider the request is for. */
  provider: string;
  /** The catalog record's canonical model id. */
  modelId: string;
  /**
   * The model's vendor (the catalog's `provider` field), when published. Data,
   * not a name match: what a gateway needs to know about the upstream family
   * (Gemini thought signatures, Grok tool-call format) is read from here.
   */
  vendor?: string;
  route: CatalogRouteBinding;
  /** The exact id sent to the provider. */
  externalModelId: string;
  wire: ConnectionWire;
  profile: RouteProfile;
  generationId: string;
  /**
   * The catalog's published output ceiling for this model, when it has one.
   * The slim catalog publishes it per model, not per connection. Absent means
   * unknown, never zero and never unlimited.
   */
  maxOutputTokens?: number;
  /**
   * The known wire of the model OWNER's own direct connection (the `direct`
   * profile whose `nativeModelProviders` names the model's vendor), when the
   * catalog publishes one and it is not this connection. Used only to TRY a
   * sub-field this connection publishes as `unknown`, on the same API.
   */
  ownerWire?: KnownWire;
}

export type ConnectionResolution =
  | { ok: true; connection: ResolvedConnection }
  | {
      ok: false;
      /**
       * - `not-catalog-routed`: the provider has no route binding (local, custom
       *   endpoint, LiteLLM); its requests are not built from catalog wires.
       * - `no-catalog`: no readable cache.
       * - `no-registry`: a cache written before wires were read; refresh it.
       * - `no-connection`: the catalog does not map this model to this provider.
       */
      reason: "not-catalog-routed" | "no-catalog" | "no-registry" | "no-connection";
    };

function lower(value: string): string {
  return value.toLowerCase();
}

function stripVendorPrefix(id: string): string {
  return id.includes("/") ? id.substring(id.lastIndexOf("/") + 1) : id;
}

function mappedOnRoute(
  connections: AggregatorEntry[],
  route: CatalogRouteBinding
): AggregatorEntry[] {
  return connections.filter(
    (connection) =>
      connection.routeStatus === "mapped" &&
      connection.route?.routeId === route.routeId &&
      connection.route?.routeProfileId === route.routeProfileId &&
      typeof connection.externalModelId === "string"
  );
}

/**
 * The connection for `modelName` on `route`.
 *
 * 1. A connection whose wire id IS the name: an explicit spec is rewritten to
 *    the provider's wire id before it gets here (`kc@k3`, `or@openai/gpt-6.1-sol`).
 *    Opt-in rows included, so an explicit `[email protected]`
 *    gets ITS connection and wire (`content-use.ts`).
 * 2. The record whose canonical id or alias is the name (vendor prefix
 *    dropped), then its exact wire id on that route — never a moving pointer
 *    unless the model's own id is one (same rule as `externalIdFor`), and never
 *    a content-use opt-in id, since this step chooses one.
 */
function findConnection(
  entries: SlimModelEntry[],
  route: CatalogRouteBinding,
  modelName: string
): { entry: SlimModelEntry; connection: AggregatorEntry } | undefined {
  for (const entry of entries) {
    const connection = mappedOnRoute(allConnections(entry), route).find(
      (c) => c.externalModelId === modelName
    );
    if (connection) return { entry, connection };
  }

  const name = lower(modelName);
  const bare = stripVendorPrefix(name);
  const entry = entries.find(
    (candidate) =>
      lower(candidate.modelId) === name ||
      lower(candidate.modelId) === bare ||
      candidate.aliases.some((alias) => lower(alias) === name || lower(alias) === bare)
  );
  if (!entry) return undefined;
  const connections = mappedOnRoute(entry.aggregators ?? [], route);
  const connection = isMovingPointer(entry.modelId)
    ? connections[0]
    : connections.find((c) => !isMovingPointer(c.externalModelId as string));
  return connection ? { entry, connection } : undefined;
}

export function resolveConnection(
  provider: string,
  modelName: string,
  cachePath: string = ALL_MODELS_CACHE_PATH
): ConnectionResolution {
  const route = catalogRouteForProvider(provider);
  if (!route) return { ok: false, reason: "not-catalog-routed" };

  const cache = readAllModelsCache(cachePath);
  if (!cache || cache.entries.length === 0) return { ok: false, reason: "no-catalog" };
  if (!cache.routeRegistry) return { ok: false, reason: "no-registry" };

  const found = findConnection(cache.entries, route, modelName);
  if (!found?.connection.wire) return { ok: false, reason: "no-connection" };
  const profile = routeProfile(cache.routeRegistry.registry, route);
  if (!profile) return { ok: false, reason: "no-connection" };

  const ownerWire = findOwnerWire(found.entry, cache.routeRegistry.registry, found.connection);
  return {
    ok: true,
    connection: {
      provider,
      modelId: found.entry.modelId,
      ...(found.entry.provider ? { vendor: found.entry.provider } : {}),
      route,
      externalModelId: found.connection.externalModelId as string,
      wire: found.connection.wire,
      profile,
      generationId: cache.routeRegistry.generationId,
      ...(typeof found.entry.maxOutputTokens === "number" && found.entry.maxOutputTokens > 0
        ? { maxOutputTokens: found.entry.maxOutputTokens }
        : {}),
      ...(ownerWire ? { ownerWire } : {}),
    },
  };
}

function findOwnerWire(
  entry: SlimModelEntry,
  registry: RouteRegistry,
  self: AggregatorEntry
): KnownWire | undefined {
  const vendor = entry.provider;
  if (!vendor) return undefined;
  const owner = (entry.aggregators ?? []).find((connection) => {
    if (connection === self || connection.routeStatus !== "mapped" || !connection.route)
      return false;
    const profile = routeProfile(registry, connection.route);
    return profile?.kind === "direct" && (profile.nativeModelProviders ?? []).includes(vendor);
  });
  return owner?.wire?.status === "known" ? owner.wire : undefined;
}

/**
 * The route profile a provider is bound to, for a model the catalog does not
 * publish on it: which APIs the host serves, so they can be tried in turn.
 */
export function resolveRouteProfile(
  provider: string,
  cachePath: string = ALL_MODELS_CACHE_PATH
): { route: CatalogRouteBinding; profile: RouteProfile; generationId: string } | undefined {
  const route = catalogRouteForProvider(provider);
  if (!route) return undefined;
  const cache = readAllModelsCache(cachePath);
  if (!cache?.routeRegistry) return undefined;
  const profile = routeProfile(cache.routeRegistry.registry, route);
  return profile ? { route, profile, generationId: cache.routeRegistry.generationId } : undefined;
}

/** The registry base URL for `api` on this connection's profile, if published. */
export function connectionBaseUrl(
  connection: ResolvedConnection,
  api: WireApi
): string | undefined {
  return connection.profile.apis[api]?.baseUrl;
}

/** The full request URL for `api` on this connection, if its profile publishes a base URL. */
export function connectionRequestUrl(
  connection: ResolvedConnection,
  api: WireApi,
  stream = true
): string | undefined {
  const baseUrl = connectionBaseUrl(connection, api);
  return baseUrl ? wireRequestUrl(baseUrl, api, connection.externalModelId, stream) : undefined;
}