Skip to content

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

4.0 KB
Raw Blame
/**
 * Every token a BUILTIN provider already answers to.
 *
 * ── Why this is its own module ──────────────────────────────────────────────
 *
 * It started inside `predefined-endpoints.ts`, guarding the BUNDLED catalog
 * only. That left user-authored `customEndpoints` unguarded, and #191 is what
 * that cost: `credentials.registerApiKeyProvider` is a plain `Map.set`, so an
 * entry keyed `openrouter` landed in a split state — `getProviderByName` still
 * answered with the builtin (so `baseUrl` stayed `https://openrouter.ai`), the
 * profile still resolved to the builtin, and only the CREDENTIAL flipped. Real
 * requests to openrouter.ai were signed with `CUSTOM_OPENROUTER_KEY`.
 *
 * The failure is quiet in both directions. The user does not get their endpoint
 * (the definition is shadowed) AND loses the builtin's credential, while the
 * config, the definition and `--probe` all show a consistent "builtin" picture.
 *
 * `custom-endpoints-loader` cannot import from `predefined-endpoints` (that
 * dependency runs the other way), so the guard lives here and both halves
 * import it. One definition means the two can never disagree about what is
 * reserved.
 *
 * ── What the collision actually breaks, measured ────────────────────────────
 *
 * Not what it looks like. `parseModelSpec` resolves `@` prefixes against
 * `PROVIDER_SHORTCUTS`, a MODULE-LOAD-TIME snapshot (`model-parser.ts`), so a
 * runtime registration never reaches routing at all and the "custom endpoint
 * hijacks `mistral@`" story is wrong. The real defect is snapshot-vs-live
 * desync, and it runs the OTHER way: the builtin keeps the prefix while
 * `getShortcuts()` — rebuilt live, runtime-last — reports the runtime row owns
 * it. The user loses the prefix they typed and the two tables disagree about
 * who answers.
 *
 * The guard is correct under either story, and the reasoning is written down
 * accurately because a wrong justification is how a correct guard gets deleted.
 */

import { PROVIDER_FILTER_ALIAS_EXTRA } from "./picker-alias-extra.js";
import { BUILTIN_PROVIDERS } from "./provider-definitions.js";

/**
 * Map of reserved token (lowercased) → the builtin provider that owns it.
 *
 * Built from `BUILTIN_PROVIDERS` at CALL TIME. Never a cached constant and
 * never a hand-written list: builtins get added, and a list that has to be kept
 * in sync is a list that will be out of sync exactly when it matters.
 *
 * `PROVIDER_FILTER_ALIAS_EXTRA` is included because it is part of the same
 * user-facing namespace — `@zen` and `@gem` resolve to builtins in the picker
 * even though no definition declares them — and it is a plain const the check
 * can import. Leaving it to a CI assertion would mean a row named `zen`
 * degrades correctly in CI and incorrectly in the field.
 */
export function reservedNamespace(): Map<string, string> {
  const reserved = new Map<string, string>();
  for (const def of BUILTIN_PROVIDERS) {
    reserved.set(def.name.toLowerCase(), def.name);
    for (const shortcut of def.shortcuts) {
      reserved.set(shortcut.toLowerCase(), def.name);
    }
    for (const legacy of def.legacyPrefixes) {
      reserved.set(legacy.prefix.replace(/[/:]+$/, "").toLowerCase(), def.name);
    }
  }
  for (const [alias, owner] of Object.entries(PROVIDER_FILTER_ALIAS_EXTRA)) {
    reserved.set(alias.toLowerCase(), owner);
  }
  return reserved;
}

/**
 * The builtin that owns `name`, or `undefined` if the name is free.
 *
 * Rebuilds the map per call, which is the same cost `reservedNamespace()`
 * already paid at each of its call sites. Registration runs once per process
 * behind a latch, so this is not on any hot path, and a cached map is exactly
 * the staleness the doc above argues against.
 */
export function reservedNamespaceOwner(name: string): string | undefined {
  return reservedNamespace().get(name.toLowerCase());
}