Skip to content

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

21.6 KB
Raw Blame
/**
 * Activation for the BUNDLED endpoint catalog.
 *
 * A catalog row is compiled into exactly the `CustomEndpointComplex` object a
 * user would have hand-written and handed to `registerEndpoint()` — the same
 * validate → definition → profile → register×3 sequence user config travels. So
 * there is no new request path here, no new transport, no new
 * `PROVIDER_PROFILES` entry, and nothing that can silently mis-route. What this
 * module owns is only the four questions the loader cannot answer for itself:
 * may this row register at all, should it, where does its key come from, and
 * where does it point.
 *
 * ── The activation predicate, and why it is ordered the way it is ───────────
 *
 * A row registers iff:
 *
 *     NOT globally disabled          (config `enabled: false`, or
 *                                     CLAUDISH_NO_PREDEFINED_ENDPOINTS=1)
 *  AND NOT a duplicate of an earlier row
 *  AND NOT colliding with a builtin name/shortcut/legacy prefix or picker alias
 *  AND NOT already registered at run time
 *  AND NOT replaced by a user `customEndpoints` entry of the same name
 *  AND NOT individually disabled
 *  AND (a locally-present credential OR an explicit `enable` entry)
 *  AND its base URL resolves
 *
 * REFUSALS come before PERMISSIONS. A user may opt IN to a vendor they have no
 * key for; a user may not opt in to shadowing a builtin, because the thing the
 * collision check prevents is not an inconvenience to them — it is one
 * provider quietly answering in another's namespace, which is this project's
 * worst documented failure class.
 *
 * The base-URL check is the one refusal placed AFTER the permission gate, and
 * deliberately: it is scoped to rows that would otherwise activate, so a stray
 * `*_BASE_URL` belonging to a vendor the user has no key for produces silence
 * rather than a warning about a provider they never asked for.
 *
 * ── Why registration itself is what gets gated ──────────────────────────────
 *
 * There is no "registered but hidden" state: `buildProviderDefinition` sets
 * `shortcuts: [name]`, and both the picker's provider list (`isPickableProvider`) and
 * the `@prefix` alias table are DERIVED from that. The picker's own list is
 * credential-filtered, but `getProviderFilterAliases()` is not — so registering
 * every bundled vendor unconditionally would pollute the `@prefix` namespace
 * and its partial-match resolver with vendors that cannot serve a request, and
 * would cost one async credential resolution per row per picker open, each able
 * to open a 1Password handshake on a machine where concurrent handshakes are
 * arbitrated globally.
 *
 * Which is why the credential question is asked with `hasLocalApiKey()` — env →
 * aliases → `config.apiKeys`, and SYNCHRONOUS, which is the whole guarantee:
 * the 1Password SDK sits behind an `await` inside the authority's async
 * `resolveKey`, so a path that cannot await cannot reach it. Note that this is
 * sync-ness, NOT import-graph isolation — `op-source` and `@1password/sdk` are
 * in this module's static import closure via `custom-endpoints-loader` →
 * `authority` → `api-key-credential`, so an `await` added anywhere on the
 * registration path would re-open the door without changing a signature.
 * `hasLocalApiKey` is used and NOT `credentials.isAvailable()`: a bundled row
 * is not in the authority's map until `registerEndpoint` puts it there, so that
 * call answers `false` for every row and the catalog would never activate at all.
 *
 * Consequence, stated plainly: a key that lives ONLY behind an `op://`
 * reference cannot activate a row, because activation is sync and 1Password is
 * async. Once a row IS active its op:// key resolves through the normal
 * authority path with no special-casing (the compiled entry carries
 * `apiKey: "${VENDOR_API_KEY}"`, so the declared-key step returns `undefined`
 * when the var is unset and the async step runs). The escape hatches are
 * `predefinedEndpoints.enable`, or exporting the variable.
 *
 * Everything here is NON-FATAL: warn to stderr, skip the row, continue. There
 * is no `process.exit` in this feature, on the precedent that a bad import must
 * never lock a user out of `claudish config`.
 */

import { keychainHasAnyOf } from "../auth/credentials/keychain-source.js";
import { hasLocalApiKey } from "../auth/credentials/local-api-key.js";
import {
  type CustomEndpointComplex,
  type PredefinedEndpointsConfig,
  PredefinedEndpointsConfigSchema,
} from "../config-schema.js";
import type { ClaudishProfileConfig } from "../profile-config.js";
import {
  type EndpointDefinitionOverrides,
  classifyEndpointBaseUrl,
  describeBadBaseUrlOverride,
  registerEndpoint,
} from "./custom-endpoints-loader.js";
import { recordEndpointUnavailable } from "./endpoint-diagnostics.js";
import { customEndpointKeyEnvVar } from "./endpoint-key-env.js";
import { PREDEFINED_ENDPOINTS } from "./predefined-catalog.js";
import type { PredefinedEndpoint } from "./predefined-endpoint-schema.js";
// The reserved-namespace guard is SHARED with the user-authored customEndpoints
// path (see #191) — one definition so the two halves cannot disagree about
// which names a builtin already owns.
import { reservedNamespace } from "./reserved-namespace.js";
import { getRuntimeProviders } from "./runtime-providers.js";

/** Env kill switch, mirroring `CLAUDISH_DISABLE_OP` / `CLAUDISH_NO_OP_HANDSHAKE_LOCK`. */
const KILL_SWITCH_ENV = "CLAUDISH_NO_PREDEFINED_ENDPOINTS";

export interface PredefinedLoadResult {
  /** Names registered by this call, in catalog order. */
  registered: string[];
  /** Names deliberately not registered, with the reason (for diagnostics/tests). */
  skipped: Array<{ name: string; reason: string }>;
}

// ── Warn-once ───────────────────────────────────────────────────────────────
// `ensureEndpointsRegistered()` is called from six sites and re-runnable on
// demand, so an un-deduplicated warning becomes a wall. Same shape as
// `op-source.ts`'s warnOnce, deliberately: keyed on the rendered message, so
// two different collisions still both print.

const warnedMessages = new Set<string>();

function warnOnce(message: string): void {
  if (warnedMessages.has(message)) return;
  warnedMessages.add(message);
  console.error(message);
}

/**
 * Names THIS module registered, so a re-evaluation can tell its own previous
 * work from a foreign registration.
 *
 * Without it, the config TUI's forced re-run (a 1Password key imported without
 * a restart) sees every row it registered a moment ago sitting in the runtime
 * registry and reports each as "a provider of that name is already registered"
 * — a warning about itself, naming a conflict that does not exist. Membership
 * is only trusted while the runtime registry still holds the name, so a cleared
 * registry falls back to the ordinary path.
 */
const ownRegistrations = new Set<string>();

/** Test-only: forget emitted warnings and prior registrations. */
export function __resetPredefinedStateForTests(): void {
  warnedMessages.clear();
  ownRegistrations.clear();
}

// ── Catalog seam ────────────────────────────────────────────────────────────

let catalogOverride: readonly PredefinedEndpoint[] | null = null;

/**
 * Test-only: replace the shipped catalog (pass `null` to restore it).
 *
 * Activation behaviour has to be provable against rows chosen for the case
 * under test — a collision row, a duplicate pair, a row with a base-URL
 * override — and pinning those tests to whichever vendors happen to ship would
 * make the shipped catalog un-editable without breaking them.
 */
export function __setPredefinedCatalogForTests(rows: readonly PredefinedEndpoint[] | null): void {
  catalogOverride = rows;
}

function activeCatalog(): readonly PredefinedEndpoint[] {
  return catalogOverride ?? PREDEFINED_ENDPOINTS;
}

// ── Opt-out config (R5) ─────────────────────────────────────────────────────

interface OptOut {
  /** The whole catalog is off. */
  disabled: boolean;
  /** Lowercased names the user opted OUT of. */
  disable: Set<string>;
  /** Lowercased names the user opted IN to regardless of credential. */
  enable: Set<string>;
}

/**
 * Read `config.predefinedEndpoints` plus the env kill switch.
 *
 * An invalid block warns once and is treated as ABSENT rather than as "off":
 * a typo in an opt-out section must not silently remove providers the user is
 * relying on, and it must never be fatal.
 */
function readOptOut(config: ClaudishProfileConfig | undefined): OptOut {
  const off: OptOut = { disabled: true, disable: new Set(), enable: new Set() };
  if (process.env[KILL_SWITCH_ENV] === "1") return off;

  const raw = config?.predefinedEndpoints;
  let parsed: PredefinedEndpointsConfig = {};
  if (raw !== undefined) {
    const result = PredefinedEndpointsConfigSchema.safeParse(raw);
    if (result.success) {
      parsed = result.data;
    } else {
      warnOnce(
        "[claudish] config 'predefinedEndpoints' is not valid and was ignored: " +
          result.error.issues.map((i) => `${i.path.join(".") || "(root)"} ${i.message}`).join(", ")
      );
    }
  }

  return {
    disabled: parsed.enabled === false,
    disable: new Set((parsed.disable ?? []).map((n) => n.trim().toLowerCase())),
    // `disable` beats `enable`, so a name in both is simply never permitted.
    enable: new Set((parsed.enable ?? []).map((n) => n.trim().toLowerCase())),
  };
}

// ── Compilation ─────────────────────────────────────────────────────────────

/**
 * A catalog row as the `CustomEndpointComplex` a user would have written.
 *
 * `kind: "complex"` ALWAYS — `buildSimpleHandler` hardcodes
 * `apiPath: "/chat/completions"`, and rows whose vendor does not use
 * `/v1/chat/completions` are precisely the ones a bundled catalog exists to
 * save people from getting wrong.
 *
 * `apiKey: "${VENDOR_API_KEY}"` is the small trick that makes the whole feature
 * reuse existing code rather than adding a key path: `resolveCustomEndpointApiKey`
 * expands it, `resolveDeclaredEndpointKey` returns `undefined` when the var is
 * unset (so the async op:// step still runs at REQUEST time), and `realValue()`
 * drops it if the placeholder never expands.
 */
function compileToCustomEndpoint(entry: PredefinedEndpoint): CustomEndpointComplex {
  return {
    kind: "complex",
    displayName: entry.displayName,
    transport: entry.format,
    baseUrl: entry.baseUrl,
    apiPath: entry.apiPath,
    apiKey: `\${${entry.apiKeyEnvVar}}`,
    authScheme: entry.authScheme,
    headers: entry.headers,
    modelPrefix: entry.modelPrefix,
  };
}

/**
 * The credential env vars a row answers to, primary first.
 *
 * `CUSTOM_<NAME>_KEY` is appended as an ALIAS, never as the primary: the
 * missing-key error, the config TUI and the sign-time header all name the
 * primary, and naming a synthesized variable the vendor's own docs never
 * mention would invert the reason the row carries a conventional name at all.
 * The sanctioned way to OVERRIDE a bundled row is a `customEndpoints` entry —
 * one mechanism for overriding, not two.
 */
function credentialEnvVars(entry: PredefinedEndpoint): { envVar: string; aliases: string[] } {
  return {
    envVar: entry.apiKeyEnvVar,
    aliases: [...(entry.apiKeyAliases ?? []), customEndpointKeyEnvVar(entry.name)],
  };
}

function overridesFor(entry: PredefinedEndpoint): EndpointDefinitionOverrides {
  const { envVar, aliases } = credentialEnvVars(entry);
  return {
    apiKeyEnvVar: envVar,
    apiKeyAliases: aliases,
    baseUrlEnvVars: entry.baseUrlEnvVars,
    apiKeyUrl: entry.apiKeyUrl ?? "",
    apiKeyDescription: `${entry.displayName} (${envVar})`,
    description: entry.description ?? `${entry.displayName} (bundled endpoint)`,
  };
}

// ── The loader ──────────────────────────────────────────────────────────────

/**
 * Register every bundled endpoint the activation predicate admits.
 *
 * `config` MUST be the same object the user-endpoint half reads. That is not
 * stylistic: the suppression set (R4) is `Object.keys(config.customEndpoints)`,
 * and if it were built from a WIDER config scope than `loadCustomEndpoints`
 * reads, a project-scoped `customEndpoints.groq` would suppress the bundled row
 * while its replacement — loaded from global config only — never registers, and
 * `groq@` would become an unknown provider for a vendor the user had just
 * configured. `ensureEndpointsRegistered()` reads `loadConfig()` ONCE and hands
 * the same object to both halves, which is what makes that impossible rather
 * than merely unlikely.
 *
 * Idempotent: the runtime registry is a Map keyed on name, warnings are
 * deduplicated, and re-running with the same inputs produces the same registry.
 */
export function loadPredefinedEndpoints(
  config: ClaudishProfileConfig | undefined,
  opts: { catalog?: readonly PredefinedEndpoint[] } = {}
): PredefinedLoadResult {
  const result: PredefinedLoadResult = { registered: [], skipped: [] };
  const optOut = readOptOut(config);
  const catalog = opts.catalog ?? activeCatalog();
  const runtime = getRuntimeProviders();

  /**
   * Skip a row that THIS process previously registered.
   *
   * Re-evaluation only ADDS — `registerRuntimeProvider` is a `Map.set` with no
   * removal, and the same name is also live in the credential authority, the
   * derived `@prefix` alias table and any handler cache built since. So a user
   * who disables a vendor in the config TUI (or whose key stops resolving)
   * keeps `groq@` answering for the rest of the process.
   *
   * De-registration was considered and NOT built: its only consumer is a config
   * edit made mid-session, and a partial removal — definition gone, credential
   * or cached handler still present — is a worse failure than a stale provider,
   * because it produces a provider that half-exists. What was missing is that
   * the user had no way to know, so "I turned it off and it kept answering"
   * read as a bug rather than as a restart requirement. Now it says so.
   */
  const noteStale = (entry: PredefinedEndpoint, name: string, reason: string) => {
    if (!ownRegistrations.has(name) || !runtime.has(entry.name)) return;
    warnOnce(
      `[claudish] predefined endpoint '${entry.name}' is no longer eligible (${reason}) but stays ` +
        "registered for the rest of this process — runtime provider registration cannot be " +
        "undone. Restart claudish to apply the change."
    );
  };

  if (optOut.disabled) {
    for (const entry of catalog) {
      result.skipped.push({ name: entry.name, reason: "catalog off" });
      noteStale(entry, entry.name.toLowerCase(), "catalog off");
    }
    return result;
  }

  const reserved = reservedNamespace();
  const userEndpoints = new Set(
    Object.keys(config?.customEndpoints ?? {}).map((n) => n.toLowerCase())
  );
  const seen = new Set<string>();

  for (const entry of catalog) {
    const name = entry.name.toLowerCase();
    const skip = (reason: string) => result.skipped.push({ name: entry.name, reason });
    // For the refusals that can only follow a PRIOR successful registration by
    // this module. Deliberately not applied to "duplicate row" (where
    // `ownRegistrations` legitimately holds the name from the FIRST row of the
    // same name, so a uniform hook would warn about a row that is working
    // correctly), nor to "collides with builtin" / "already registered", which
    // can never have registered in the first place.
    const skipStale = (reason: string) => {
      skip(reason);
      noteStale(entry, name, reason);
    };

    // ── refusals ────────────────────────────────────────────────────────────

    // Edge case 2: first row wins, deterministically, because array order is
    // stable data. The second is a maintainer error, so it is loud.
    if (seen.has(name)) {
      warnOnce(
        `[claudish] predefined endpoint '${entry.name}' appears more than once in the bundled ` +
          "catalog. The first row wins; the later one is ignored."
      );
      skip("duplicate row");
      continue;
    }
    seen.add(name);

    const owner = reserved.get(name);
    if (owner) {
      const reason =
        `'${entry.name}' is already claimed by builtin provider '${owner}' ` +
        "(as its name, a shortcut, or a legacy prefix)";
      warnOnce(
        `[claudish] predefined endpoint '${entry.name}' skipped: ${reason}. ` +
          "The builtin wins; the bundled entry is inactive."
      );
      recordEndpointUnavailable(entry.name, `bundled endpoint was skipped because ${reason}`);
      skip("collides with builtin");
      continue;
    }

    if (runtime.has(entry.name) && !ownRegistrations.has(name)) {
      // Not necessarily an error — a user endpoint registered first is the
      // documented replacement path — but it IS worth naming, because a bundled
      // row silently not applying is otherwise indistinguishable from absence.
      warnOnce(
        `[claudish] predefined endpoint '${entry.name}' skipped: a provider named ` +
          `'${entry.name}' is already registered for this process.`
      );
      skip("already registered");
      continue;
    }

    // R4: a user's own entry REPLACES the bundled one entirely — not a merge.
    // The user entry is registered by `loadCustomEndpoints` at its own call
    // site, so all that is needed here is to stand aside. Suppression rather
    // than write-order because `ensureEndpointsRegistered` runs from six sites
    // and "whoever registers last wins" is a guarantee a future reordering
    // would silently flip.
    if (userEndpoints.has(name)) {
      // Announced ONLY when the vendor's own variable is actually set, because
      // that is exactly when the replacement surprises: the user's entry gets
      // `CUSTOM_<NAME>_KEY`, so a perfectly good VENDOR_API_KEY sitting in the
      // environment is now ignored — silently, and from neither file's point of
      // view. With no such key there is nothing to be surprised by, and an
      // unconditional line would print on every launch of a correct config,
      // into a stderr that during an interactive session is Claude Code's own
      // TTY.
      if (hasLocalApiKey({ envVar: entry.apiKeyEnvVar })) {
        warnOnce(
          `[claudish] customEndpoints['${entry.name}'] replaces the bundled entry entirely; ` +
            `${entry.apiKeyEnvVar} no longer applies to it. Add ` +
            `"apiKey": "\${${entry.apiKeyEnvVar}}" to that entry to keep using it.`
        );
      }
      skipStale("replaced by customEndpoints");
      continue;
    }

    if (optOut.disable.has(name)) {
      skipStale("disabled in config");
      continue;
    }

    // ── permissions ─────────────────────────────────────────────────────────

    const { envVar, aliases } = credentialEnvVars(entry);
    // The keychain is OR-ed in as a PRESENCE check only. Registration cannot
    // await, and a per-variable keychain value read costs ~17ms — but
    // `keychainHasAnyOf` answers for every vendor from ONE enumerate call, so
    // the gate stays affordable. Deliberately not folded into
    // `hasLocalApiKey`: that function IS the authority's value-resolution step
    // (see local-api-key.ts), and widening it would change what every provider
    // in claudish signs requests with, which is not an endpoints decision.
    const permitted =
      optOut.enable.has(name) ||
      hasLocalApiKey({ envVar, aliases }) ||
      keychainHasAnyOf([envVar, ...(aliases ?? [])]);
    if (!permitted) {
      skipStale("no local credential");
      continue;
    }

    // ── the base URL has to exist before anything is registered ─────────────
    //
    // Checked at the gate as well as at handler build: at the gate so a
    // malformed override never produces a provider that cannot serve, and at
    // handler build so a URL exported AFTER startup is checked too.
    const resolvedUrl = classifyEndpointBaseUrl(entry.baseUrl, entry.baseUrlEnvVars);
    if (!resolvedUrl.ok) {
      const detail = describeBadBaseUrlOverride(resolvedUrl, entry.baseUrl);
      warnOnce(`[claudish] predefined endpoint '${entry.name}' skipped: ${detail}`);
      recordEndpointUnavailable(entry.name, detail);
      skipStale("invalid base URL override");
      continue;
    }

    try {
      registerEndpoint(entry.name, compileToCustomEndpoint(entry), overridesFor(entry));
      ownRegistrations.add(name);
      result.registered.push(entry.name);
    } catch (err) {
      // A malformed row fails exactly where a malformed USER row fails — same
      // Zod schema, same non-fatal warn-and-skip. It should be impossible (the
      // catalog is type-checked and CI-validated), which is precisely why it
      // must not be able to take startup down when it happens anyway.
      warnOnce(
        `[claudish] predefined endpoint '${entry.name}' skipped: ` +
          `${err instanceof Error ? err.message : String(err)}`
      );
      skip("invalid catalog row");
    }
  }

  return result;
}