Skip to content

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

70.6 KB
Raw Blame
import { resolveSubscriptionRouting } from "../adapters/model-catalog.js";
import { credentials } from "../auth/credentials/authority.js";
import type { ReadinessResult } from "../auth/credentials/types.js";
import { resolveDefaultProvider } from "../default-provider.js";
import { isSubscriptionProvider } from "../handlers/shared/remote-provider-types.js";
import { log, logStderr } from "../logger.js";
import type { RecommendedModelsDoc } from "../model-loader.js";
import { loadConfig, loadLocalConfig } from "../profile-config.js";
import type { RoutingEntry, RoutingRules } from "../profile-config.js";
import { DISPLAY_NAMES, PROVIDER_TO_PREFIX } from "./auto-route.js";
import { resolveExternalId } from "./catalog-client.js";
import type { ConnectionPrice } from "./connection-price.js";
import { ensureEndpointsRegistered } from "./endpoint-registration.js";
import { providerServesModel } from "./model-availability.js";
import { AUTO_ROUTE_PROVIDER, PROVIDER_SHORTCUTS } from "./model-parser.js";
import { parseModelSpec } from "./model-parser.js";
import { type NativeRoute, proxyRouteDecision } from "./native-route.js";
import { PREDEFINED_ENDPOINTS } from "./predefined-catalog.js";
import { type RouteTier, getProviderByName } from "./provider-definitions.js";
import {
  type RouteCandidate,
  catalogDeniesProvider,
  catalogMapsOnlyOptIn,
  compareRouteCandidates,
  gatherRouteCandidates,
} from "./route-candidates.js";
import { buildCredentialHint } from "./routing-hints.js";
import {
  describeUnknownShortcut,
  isKnownProviderName,
  typedShortcutOf,
} from "./unknown-shortcut.js";

export interface RoutingRuleSources {
  globalRules: RoutingRules;
  localRules: RoutingRules;
  recommendedModels?: RecommendedModelsDoc;
}

/**
 * Load the user's effective routing rules. Two layers, both the user's own:
 *   1. Global config (~/.claudish/config.json)
 *   2. Local config (./.claudish.json)
 *
 * Local overwrites global by exact key match — no glob-vs-glob interleaving.
 *
 * THERE ARE NO BUILT-IN RULES. The providers that can serve a bare name are
 * GATHERED from the cloud models catalog (`route-candidates.ts`), which
 * publishes every tier — subscriptions, native APIs and gateways — for every
 * model; a hand-written table merged under the user's rules could only
 * approximate that. So the result here is frequently `{}`, and `explainBareName`
 * treats "no rule matched" as "ask the catalog" rather than as an error.
 *
 * What a user rule now MEANS is therefore stronger than it was: a match is used
 * VERBATIM and is never merged with, reordered by or appended to by anything —
 * including the fallback hop. `routing["*"] = []` is consequently still the
 * strict no-route switch it always was, and `routing["*"] = [...]` replaces the
 * fallback outright.
 *
 * `sources` keeps rule composition testable without reading machine config.
 * The recommended-model projection is not a routing-rule override.
 *
 * Prints nothing. It runs inside the config TUI and the `--probe` TUI, where a
 * stray stderr line lands in the middle of a frame, and on every `route()` call.
 * Problems in the rules are {@link routingRuleProblems}'s to report: the proxy
 * prints them once at startup, and `explainRoute` returns them as warnings.
 */
export function loadRoutingRules(sources?: RoutingRuleSources): RoutingRules {
  const { localRules: local, globalRules: global_ } = sources ?? loadRoutingRuleSources();
  return { ...global_, ...local };
}

/**
 * The two rule tables `loadRoutingRules` merges, read from this machine's config
 * and kept apart: global (`~/.claudish/config.json`, or the `--config` file) and
 * project (`./.claudish.json`). A caller that must say WHICH file a matched rule
 * came from (`explainRoute`) reads them here and merges them itself.
 */
export function loadRoutingRuleSources(): RoutingRuleSources {
  const localRules = loadLocalConfig()?.routing ?? {};
  const globalRules = loadConfig().routing ?? {};
  return { globalRules, localRules };
}

/**
 * Validate that every provider name a routing rules table references exists.
 * The `unknown-provider` problems of {@link routingRuleProblems}, thrown.
 *
 * Throws, so it is for a caller that wants a typo to be loud — a config
 * validator or a test — never the request path. `loadRoutingRules` deliberately
 * does not call it: a user whose hand-written rule names a provider claudish
 * dropped should get a degraded chain and a warning (`routingRuleProblems`), not
 * a crash on every request.
 *
 * Its subject used to be the shipped table, which is gone. What remains to
 * check is the USER's rules, which is the only table left.
 */
export function validateRoutingRulesAgainstProviders(rules: RoutingRules): void {
  // The scope is not part of the message; the table is checked as one file.
  const unknown = ruleTableProblems(rules, "global").filter(
    (problem) => problem.problem === "unknown-provider"
  );

  if (unknown.length > 0) {
    const lines = unknown.map((u) => {
      const entry = u.entry ?? "";
      return `  rule "${u.pattern}" → entry "${entry}" → unknown provider "${ruleEntryProvider(entry)}"`;
    });
    throw new Error(`[claudish] routing rules reference unknown providers:\n${lines.join("\n")}`);
  }
}

/** A problem in the user's routing rules that would make them silently misbehave. */
export interface RoutingRuleProblem {
  /** The config file the rule is in. */
  scope: RuleScope;
  /** The rule key as stored. */
  pattern: string;
  problem: "multiple-wildcards" | "case-collision" | "unknown-provider";
  /** `unknown-provider` only: the rule entry, as written, that names no provider. */
  entry?: string;
  /** `case-collision` only: the earlier key in the same file this one collides with. */
  collidesWith?: string;
}

/**
 * Every problem in the user's two rule files. It reads no file and prints
 * nothing, so a TUI can show the result and the proxy can print it once.
 *
 * `unknown-provider` asks the provider registry, so the CALLER registers the
 * custom and bundled endpoints first (`ensureEndpointsRegistered`); without that
 * every custom endpoint a rule names reads as a typo. A bundled endpoint is known
 * by its catalog row, since registration skips one whose key is absent: that rule
 * entry is `no-credential` when routed, not a typo.
 *
 * Each file is checked on its own, as the rules have always been: a key that
 * collides only with a key in the OTHER file is not reported.
 *
 * An empty chain is not a problem: `[]` is the user's explicit no-route.
 */
export function routingRuleProblems(sources: {
  globalRules: RoutingRules;
  localRules: RoutingRules;
}): RoutingRuleProblem[] {
  return [
    ...ruleTableProblems(sources.globalRules, "global"),
    ...ruleTableProblems(sources.localRules, "project"),
  ];
}

function ruleTableProblems(rules: RoutingRules, scope: RuleScope): RoutingRuleProblem[] {
  const problems: RoutingRuleProblem[] = [];
  // Track lower-cased keys to catch case-insensitive collisions. Matching is
  // case-insensitive, so two keys that differ only in case will silently
  // collapse to whichever the iteration order favors.
  const seenLower = new Map<string, string>();
  for (const key of Object.keys(rules)) {
    // Multi-wildcard patterns only use the first *, rest become literals
    if (key !== "*" && (key.match(/\*/g) || []).length > 1) {
      problems.push({ scope, pattern: key, problem: "multiple-wildcards" });
    }
    const lower = key.toLowerCase();
    const prior = seenLower.get(lower);
    if (prior !== undefined && prior !== key) {
      problems.push({ scope, pattern: key, problem: "case-collision", collidesWith: prior });
    } else {
      seenLower.set(lower, key);
    }
    for (const entry of rules[key] ?? []) {
      if (!isKnownProvider(ruleEntryProvider(entry))) {
        problems.push({ scope, pattern: key, problem: "unknown-provider", entry });
      }
    }
  }
  return problems;
}

/**
 * The claudish provider a rule entry names: the part before an optional
 * `@<wire id>`, with a shortcut (`or`) resolved, exactly as `buildRoutingChain`
 * resolves it.
 */
function ruleEntryProvider(entry: RoutingEntry): string {
  const atIdx = entry.indexOf("@");
  const providerRaw = atIdx === -1 ? entry : entry.slice(0, atIdx);
  return PROVIDER_SHORTCUTS[providerRaw.toLowerCase()] ?? providerRaw.toLowerCase();
}

/** A built-in provider, a registered endpoint, or a bundled endpoint's catalog row. */
function isKnownProvider(provider: string): boolean {
  return (
    getProviderByName(provider) !== undefined ||
    PREDEFINED_ENDPOINTS.some((row) => row.name.toLowerCase() === provider)
  );
}

/** One line for a rule problem, without a "[claudish]" prefix (logStderr adds it). */
export function describeRoutingRuleProblem(problem: RoutingRuleProblem): string {
  switch (problem.problem) {
    case "multiple-wildcards":
      return (
        `routing pattern "${problem.pattern}" (${problem.scope}) has more than one * — ` +
        "only a single * is supported, so it may not match as expected."
      );
    case "case-collision":
      return (
        `routing patterns "${problem.collidesWith}" and "${problem.pattern}" (${problem.scope}) ` +
        "differ only in case. Matching ignores case, so one silently shadows the other: " +
        "pick one casing and remove the duplicate."
      );
    case "unknown-provider": {
      const entry = problem.entry ?? "";
      return (
        `routing rule "${problem.pattern}" (${problem.scope}) names "${entry}", but no ` +
        `provider "${ruleEntryProvider(entry)}" exists, so that entry never routes.`
      );
    }
  }
}

/**
 * Match a model name against routing rules. Case-INSENSITIVE — provider
 * docs and catalogs use mixed casing (`MiniMax-M2.5`, `GPT-4o`) but the
 * underlying APIs accept any case, so users get bitten when copy-paste
 * casing doesn't exactly match a lowercase rule key.
 *
 * Priority: exact → longest glob → "*" catch-all → null (the catalog decides).
 *
 * NOTE: only the rule LOOKUP is lowered. The original `modelName` casing is
 * preserved when the route is built and sent to provider APIs (some are
 * case-sensitive on their own model IDs).
 *
 * The chain of the key {@link matchRoutingRuleKey} returns, so the two cannot
 * disagree about which rule a name matches.
 */
export function matchRoutingRule(modelName: string, rules: RoutingRules): RoutingEntry[] | null {
  const key = matchRoutingRuleKey(modelName, rules);
  // Catch-all included: its chain may be an empty array, which the caller treats
  // as "no route".
  return key === null ? null : rules[key];
}

/**
 * The rule KEY a model name matches, spelled exactly as it is stored in
 * `rules`, or `null` when no rule matches.
 *
 * Priority, as {@link matchRoutingRule} applies it: an exact key compared
 * case-insensitively (the stored spelling is returned, not the model name), then
 * the longest matching glob, then `"*"`.
 *
 * A display needs the key, not the chain: two rules can name the same chain, and
 * "which rule decided this" is the question a user asks when a model goes
 * somewhere they did not expect. Returning the stored key also lets a caller
 * that knows where each key came from (global or project config) name the
 * scope.
 */
export function matchRoutingRuleKey(modelName: string, rules: RoutingRules): string | null {
  const lowered = modelName.toLowerCase();

  // 1. Exact match (case-insensitive over rule keys)
  for (const key of Object.keys(rules)) {
    if (!key.includes("*") && key.toLowerCase() === lowered) return key;
  }

  // 2. Glob patterns (sorted longest-first = most specific)
  const globKeys = Object.keys(rules)
    .filter((k) => k !== "*" && k.includes("*"))
    .sort((a, b) => b.length - a.length);

  for (const pattern of globKeys) {
    if (globMatch(pattern, modelName)) return pattern;
  }

  // 3. Catch-all
  if (rules["*"] !== undefined) return "*";

  return null;
}

/**
 * Convert routing entries to Route objects.
 * Plain name "provider" uses originalModelName.
 * Explicit "provider@model" uses the specified model.
 *
 * An entry whose subscription plan does not include the model is dropped (see
 * {@link resolveRoutingEntries}, which keeps it, marked, for `explainRoute`).
 */
export function buildRoutingChain(
  entries: RoutingEntry[],
  originalModelName: string,
  cachePath?: string
): Route[] {
  return resolveRoutingEntries(entries, originalModelName, cachePath)
    .filter((resolved) => !resolved.exclusion)
    .map((resolved) => resolved.route);
}

/** One routing entry turned into a route, or kept only to say why it was not. */
interface ResolvedEntry {
  route: Route;
  /**
   * Set when the entry is excluded before any credential is read. `route` then
   * carries the name it would have been asked by, since no wire id was resolved.
   *
   * - `excluded-by-membership`: the entry's subscription plan publishes a
   *   membership that does not include the model.
   * - `excluded-by-content-use`: the provider maps the model only through a
   *   content-use opt-in wire id, which claudish never chooses (`content-use.ts`).
   */
  exclusion?: PreFilterExclusion;
}

/** The outcomes that remove a candidate before the credential filter runs. */
type PreFilterExclusion = "excluded-by-membership" | "excluded-by-content-use";

/** Whether a candidate was removed before the credential filter, i.e. never reaches it. */
function isPreFilterExclusion(outcome: CandidateOutcome): boolean {
  return outcome === "excluded-by-membership" || outcome === "excluded-by-content-use";
}

/**
 * {@link buildRoutingChain}'s loop, keeping the entries plan membership excludes
 * instead of skipping them. `buildRoutingChain` drops those; `explainRoute`
 * reports them as `excluded-by-membership`. One loop, so the chain a request
 * uses and the chain a display explains cannot drift apart.
 */
function resolveRoutingEntries(
  entries: RoutingEntry[],
  originalModelName: string,
  cachePath?: string
): ResolvedEntry[] {
  const resolved: ResolvedEntry[] = [];

  for (const entry of entries) {
    const atIdx = entry.indexOf("@");
    let providerRaw: string;
    let modelName: string;

    if (atIdx !== -1) {
      providerRaw = entry.slice(0, atIdx);
      modelName = entry.slice(atIdx + 1);
    } else {
      providerRaw = entry;
      modelName = originalModelName;
    }

    // Resolve shortcut
    const provider = PROVIDER_SHORTCUTS[providerRaw.toLowerCase()] ?? providerRaw.toLowerCase();

    // Subscription endpoints speak their own wire ids (Kimi Code serves `k3`,
    // not the catalog's `kimi-k3`). When the entry didn't pin a model
    // explicitly, translate via the catalog — and drop the candidate outright
    // when the plan doesn't include this model, so the chain falls through to a
    // provider that can actually serve it instead of erroring or silently
    // handing back a different model.
    let wireIdResolved = false;
    if (atIdx === -1) {
      const routing = resolveSubscriptionRouting(modelName, provider, cachePath);
      if (routing.kind === "not-served") {
        resolved.push({
          route: routeFor(provider, modelName),
          exclusion: "excluded-by-membership",
        });
        continue;
      }
      // The provider publishes this model ONLY through a content-use opt-in
      // wire id. Sending the plain name would ask a route for an id it never
      // published, and sending the opt-in id would choose it for the user
      // (`content-use.ts`). A `["zgo"]` rule for `gemini-4-argon` lands here.
      if (routing.kind !== "serves" && catalogMapsOnlyOptIn(provider, modelName, cachePath)) {
        resolved.push({
          route: routeFor(provider, modelName),
          exclusion: "excluded-by-content-use",
        });
        continue;
      }
      if (routing.kind === "serves") {
        modelName = routing.externalId;
        // Already the plan's wire id — do NOT resolve again below, or the
        // generic lookup would translate an external id a second time.
        wireIdResolved = true;
      }
    }

    // Every provider's wire id comes from the SAME catalog lookup
    // (`aggregators[]`), not a per-provider resolver. This is what makes
    // `[email protected]` reach `gemini-3.6-flash-high` and
    // `together-ai@glm-5` reach `zai-org/GLM-5` without either provider
    // needing bespoke code. No match → the name passes through unchanged.
    if (!wireIdResolved) {
      modelName = resolveExternalId(modelName, provider, cachePath) ?? modelName;
    }

    resolved.push({ route: routeFor(provider, modelName) });
  }

  return resolved;
}

/**
 * One provider plus the id it will actually be SENT → a `Route`.
 *
 * The ONE copy of the modelSpec rule, which has exactly one exception:
 * OpenRouter's ids are already vendor-qualified (`moonshotai/kimi-k3`), so they
 * are their own spec, while everyone else takes a provider prefix. Both callers
 * go through here — `buildRoutingChain`, which resolves a wire id from a user
 * rule, and the catalog-candidate adapter, which is HANDED one — so the rule
 * cannot drift between the two paths. `wireIdOf` is its inverse and would
 * silently disagree if a second copy appeared.
 */
function routeFor(provider: string, wireId: string): Route {
  const modelSpec =
    provider === "openrouter" ? wireId : `${PROVIDER_TO_PREFIX[provider] ?? provider}@${wireId}`;
  return { provider, modelSpec, displayName: DISPLAY_NAMES[provider] ?? provider };
}

/**
 * Single-wildcard glob: "kimi-*" matches "kimi-k2.5". Case-INSENSITIVE so
 * `MiniMax-M2.5` matches `minimax-*` and `GPT-4o` matches `gpt-*`. Provider
 * docs use mixed casing, model IDs in catalogs are usually lowercase, but
 * users routinely paste from docs and would otherwise hit the catch-all.
 */
function globMatch(pattern: string, value: string): boolean {
  const star = pattern.indexOf("*");
  const p = pattern.toLowerCase();
  const v = value.toLowerCase();
  if (star === -1) return p === v;
  const prefix = p.slice(0, star);
  const suffix = p.slice(star + 1);
  return v.startsWith(prefix) && v.endsWith(suffix) && v.length >= prefix.length + suffix.length;
}

// ---------------------------------------------------------------------------
// route() — single routing entry point (plan §B.3)
// ---------------------------------------------------------------------------

/** A single resolved route candidate. */
export interface Route {
  /** Canonical provider name (e.g. "openai", "openrouter"). */
  provider: string;
  /** Ready-to-handle "provider@model" string for downstream handler creation. */
  modelSpec: string;
  /** Human-readable provider label. */
  displayName: string;
}

/**
 * Result of resolving a model spec.
 *
 *   - `kind: "ok"`        — at least one credentialed provider was found.
 *                           `primary` is the first; `fallbacks` follow in order.
 *   - `kind: "no-route"`  — either the explicit prefix had no credentials
 *                           configured, or the chain was empty after credential
 *                           filtering. `hint` is a multi-line message with
 *                           actionable suggestions.
 */
export type RoutePlan =
  | { kind: "ok"; primary: Route; fallbacks: Route[] }
  | { kind: "no-route"; reason: string; hint?: string };

/**
 * Check whether the user has credentials for a given canonical provider.
 *
 * Delegates to the credential authority's sync readiness oracle. The authority's
 * per-provider impls replicate every special case this function used to inline:
 *   - `native-anthropic` requires an explicit ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
 *     (NativeAnthropicCredentialProvider).
 *   - `openai-codex` requires its codex-specific key or OAuth — the OPENAI_API_KEY
 *     alias is excluded (the Codex composite's API-key half has no aliases).
 *   - Local transports (ollama, lmstudio, vllm, mlx) require explicit enablement
 *     (LocalCredentialProvider → isLocalProviderEnabled).
 *   - OAuth-backed providers (kimi, antigravity) accept an OAuth file or env
 *     key; the oauthFallback affordance is honored by ApiKeyCredentialProvider.
 *     (A `publicKeyFallback` affordance also used to be honored here; it was
 *     removed — a keyless provider now declares `authScheme: "none"`.)
 *
 * Equivalence with the previous inline logic is pinned by
 * auth/credentials/equivalence.test.ts.
 */
export async function hasCredentialsForProvider(provider: string): Promise<boolean> {
  return credentials.isAvailable(provider);
}

// ---------------------------------------------------------------------------
// explainRoute() — the routing decision, every candidate, and why
// ---------------------------------------------------------------------------

/** Which config file a user rule came from. */
export type RuleScope = "global" | "project";

/**
 * What became of one route candidate. `kept` is a hop of the routing chain;
 * every other value names the step that removed the candidate.
 */
export type CandidateOutcome =
  /** Passed the credential and availability filters: a hop of the routing chain. */
  | "kept"
  /** The credential filter found no credential. */
  | "no-credential"
  /** A SUBSCRIPTION's credential exists but could not be read (1Password, Keychain). */
  | "credential-unreadable"
  /** The account's dynamic models catalog denies the model. */
  | "not-served"
  /** The subscription plan's published membership does not include the model. */
  | "excluded-by-membership"
  /**
   * The provider maps the model only through a content-use opt-in wire id, which
   * claudish never chooses; typed exactly (`provider@<id>`), it is sent.
   */
  | "excluded-by-content-use"
  /**
   * An explicit spec's shortcut names no claudish provider (`isKnownProviderName`).
   * Decided before any credential is read.
   */
  | "unknown-provider";

/** One route candidate, where the chain placed it, and what became of it. */
export interface ExplainedCandidate {
  /** claudish provider. */
  provider: string;
  displayName: string;
  /** Exactly the `Route.modelSpec` a kept candidate becomes. */
  modelSpec: string;
  /**
   * The wire id this candidate sends. For `excluded-by-membership`, the name it
   * would have been asked by: no wire id is resolved for a plan that excludes it.
   */
  wireId: string;
  /**
   * `fallback` is the fallback hop's POSITION, appended after the catalog's own
   * candidates. It is independent of `outcome`: an uncredentialed fallback is
   * `no-credential` and is dropped like any other candidate.
   */
  position: "candidate" | "fallback";
  /** The definition's tier; absent for a name no definition carries. */
  tier?: RouteTier;
  /** Catalog-gathered candidates only: the model's own vendor's route. */
  isVendorOwn?: boolean;
  /** Catalog-gathered candidates only. */
  price?: ConnectionPrice;
  /** Catalog-gathered candidates only, when the catalog publishes one. */
  contextWindow?: number;
  outcome: CandidateOutcome;
  /**
   * Kept candidates whose availability was checked: `serves` when the account
   * confirmed the model, `unknown` when nothing denied it.
   */
  availability?: "serves" | "unknown";
}

/** Why a target has no route. */
export type NoRouteCause =
  /** A user rule matched and nothing survived plan membership, a matched `[]` included. */
  | "rule-empty"
  /** No cloud models catalog could be read and no namespace claim applies. */
  | "catalog-unreadable"
  /** The catalog was read and gathered nothing, and no fallback hop survived. */
  | "catalog-empty"
  /** Every remaining candidate lacked a credential, or its credential could not be read. */
  | "no-credential"
  /** The account's dynamic models catalog denied every credentialed candidate. */
  | "not-served"
  /** An explicit spec's shortcut names no claudish provider (`describeUnknownShortcut`). */
  | "explicit-unknown-shortcut"
  /** An explicit spec's provider has no credential. */
  | "explicit-no-credential"
  /** An explicit spec's plan membership excludes the model, so no route could be built. */
  | "explicit-unbuildable"
  /** An explicit spec's provider does not serve the model. */
  | "explicit-not-served";

/**
 * The decision. It mirrors `RoutePlan.kind` field for field, which is what makes
 * {@link toRoutePlan} a 1:1 map: `hint` is present, possibly as `undefined`,
 * exactly where `route()` has always set it.
 */
export type RouteOutcome =
  | { kind: "ok" }
  | { kind: "no-route"; cause: NoRouteCause; reason: string; hint?: string };

/**
 * Why the fallback hop was not appended to a catalog-gathered chain. The first
 * condition that holds, in the order `buildCatalogChain` tests them.
 */
export type FallbackWithheld =
  /** `defaultProvider` is `""`. */
  | "disabled"
  /** No cloud models catalog: claudish never invents a hop without one. */
  | "catalog-unreadable"
  /** The catalog already gathered that provider. */
  | "already-gathered"
  /** The fallback's route is backend-owned and the catalog maps it no connection to this model. */
  | "catalog-denies";

/**
 * Something the user should know about a decision. `route()` prints the two
 * billing notices to stderr. `explainRoute` never writes; a display shows these
 * instead. A `rule-problem` comes only from `explainRoute` when it read the rule
 * files itself: it is about the config, not about this decision, and the proxy
 * prints it once at startup rather than per request.
 */
export type RouteWarning =
  | { type: "rule-problem"; problem: RoutingRuleProblem; message: string }
  | {
      type: "subscription-not-served";
      providers: string[];
      /** The claudish provider the request lands on. */
      usedInstead: string;
      message: string;
    }
  | {
      type: "subscription-credential-unreadable";
      providers: string[];
      /** The claudish provider the request lands on. */
      usedInstead: string;
      message: string;
    };

/** The routing decision for one target, with every candidate and why. */
export interface RouteExplanation {
  /** The target as passed. */
  requestedModel: string;
  /**
   * The name rules and the catalog were asked about: a known `vendor/` stripped,
   * `normalizeGlmSlug` applied. For an explicit target, the model part of the
   * spec (`anthropic/<id>` verbatim); for a native target, the target.
   */
  routedModel: string;
  /** Where the chain came from. ORIGIN only: `outcome` says whether it routed. */
  source: "native" | "explicit" | "user-rule" | "catalog";
  /** Explicit only: how the target named its provider. */
  via?: "model-spec" | "vendor-qualified-id" | "poe";
  /** User rule only: the rule key as stored, a matched `[]` included. */
  matchedPattern?: string;
  /** User rule only, when `explainRoute` loaded the rules itself. */
  ruleScope?: RuleScope;
  /** Catalog only: whether the cloud models catalog could be read and had the name. */
  catalog?: "found" | "absent" | "unreadable";
  /** Chain order. A dropped candidate stays where the chain placed it. `[]` for native. */
  candidates: ExplainedCandidate[];
  /** Catalog only, when the fallback hop was not appended. */
  fallbackWithheld?: FallbackWithheld;
  outcome: RouteOutcome;
  warnings: RouteWarning[];
  /** Native only: what the native passthrough sends, on Claude Code's own auth. */
  native?: NativeRoute;
}

export interface ExplainRouteOptions {
  /**
   * Absent: the global and project rules are loaded here, so `ruleScope` is known
   * and their problems are returned as `rule-problem` warnings.
   */
  rules?: RoutingRules;
  /**
   * Absent: `route()`'s rule. With `rules` passed none is read, so the fallback
   * hop takes `openrouter`; otherwise `effectiveDefaultProvider()`.
   */
  defaultProvider?: string;
  cachePath?: string;
}

/** A route as an explained candidate. `gathered` is the catalog candidate it came from, if any. */
function explainCandidate(
  route: Route,
  position: ExplainedCandidate["position"],
  outcome: CandidateOutcome,
  gathered?: RouteCandidate
): ExplainedCandidate {
  const tier = gathered ? gathered.tier : getProviderByName(route.provider)?.tier;
  return {
    provider: route.provider,
    displayName: route.displayName,
    modelSpec: route.modelSpec,
    wireId: wireIdOf(route),
    position,
    ...(tier !== undefined ? { tier } : {}),
    ...(gathered ? { isVendorOwn: gathered.isVendorOwn, price: gathered.price } : {}),
    ...(gathered?.contextWindow !== undefined ? { contextWindow: gathered.contextWindow } : {}),
    outcome,
  };
}

/** The outcome of a resolved routing entry before any credential is read. */
function entryOutcome(resolved: ResolvedEntry): CandidateOutcome {
  return resolved.exclusion ?? "kept";
}

/**
 * Path 1: an explicit "provider@model" spec. Probe ONLY that provider's
 * credentials; never fall back silently.
 */
async function explainExplicitSpec(
  requestedModel: string,
  modelSpec: string,
  model: string,
  provider: string,
  cachePath?: string
): Promise<RouteExplanation> {
  // FIRST, ahead of every credential read: a shortcut that names no provider is
  // answered as unknown, never as "no credentials". No authority lookup, readiness
  // probe or 1Password attempt runs for a name that cannot exist (D9). This check
  // must stay ahead of any credential read added to this function later.
  if (!isKnownProviderName(provider)) {
    return explainUnknownShortcut(requestedModel, modelSpec, model, provider, cachePath);
  }

  const credentialed = await hasCredentialsForProvider(provider);

  // The one candidate is built whatever the credential says, so a display can
  // name what the spec asks for. Built AFTER the credential read, the order
  // route() has always used; building it is a catalog lookup and nothing else.
  const [resolved] = resolveRoutingEntries([modelSpec], model, cachePath);
  const candidate = explainCandidate(resolved.route, "candidate", entryOutcome(resolved));
  const explanation: RouteExplanation = {
    requestedModel,
    routedModel: model,
    source: "explicit",
    via: "model-spec",
    candidates: [candidate],
    outcome: { kind: "ok" },
    warnings: [],
  };

  if (!credentialed) {
    candidate.outcome = "no-credential";
    explanation.outcome = {
      kind: "no-route",
      cause: "explicit-no-credential",
      reason: `No credentials configured for "${provider}".`,
      hint: buildCredentialHint(model, [provider]) ?? undefined,
    };
    return explanation;
  }

  if (resolved.exclusion) {
    explanation.outcome = {
      kind: "no-route",
      cause: "explicit-unbuildable",
      reason: `Could not build a route for "${modelSpec}".`,
    };
    return explanation;
  }

  // An explicit address is NEVER silently dropped — the user named this vendor,
  // so a "does not serve it" verdict is something to TELL them, not something to
  // route around. That is the difference from the bare path, where claudish
  // assembled the chain itself and may quietly pick another link.
  //
  // Without this the request still fails, just later and less clearly: OpenCode
  // Zen Go answers for a model it does not carry with HTTP 401, which reads as a
  // credential problem and sends the user to check a key that works.
  const availability = await providerServesModel(candidate.provider, candidate.wireId);
  if (availability === "not-served") {
    candidate.outcome = "not-served";
    explanation.outcome = {
      kind: "no-route",
      cause: "explicit-not-served",
      reason: `${candidate.displayName} does not serve "${model}".`,
      hint:
        `Check the model id, or use a bare \`${model}\` to let claudish pick a provider ` +
        "that carries it.",
    };
    return explanation;
  }

  candidate.availability = availability;
  return explanation;
}

/**
 * An explicit spec whose shortcut names no claudish provider. The one candidate
 * names what was typed, with no tier and no catalog lookup; the outcome carries
 * `describeUnknownShortcut`'s wording, which every surface prints verbatim.
 */
function explainUnknownShortcut(
  requestedModel: string,
  modelSpec: string,
  model: string,
  provider: string,
  cachePath?: string
): RouteExplanation {
  const { reason, hint } = describeUnknownShortcut(
    typedShortcutOf(modelSpec),
    model,
    cachePath,
    modelSpec
  );
  return {
    requestedModel,
    routedModel: model,
    source: "explicit",
    via: "model-spec",
    candidates: [
      {
        provider,
        displayName: provider,
        modelSpec,
        wireId: model,
        position: "candidate",
        outcome: "unknown-provider",
      },
    ],
    outcome: { kind: "no-route", cause: "explicit-unknown-shortcut", reason, hint },
    warnings: [],
  };
}

/**
 * The provider that occupies the LAST hop, or null when the user disabled it.
 *
 * The fallback is a POSITION, not a property of any provider (see `RouteTier`).
 * Two ways to empty that position, and BOTH are preserved from the design this
 * replaced:
 *
 *   - `defaultProvider: ""` — an explicitly empty string. `undefined` is not the
 *     same thing: unset means "no preference", which takes `openrouter`, and
 *     that is what the deleted `"*": ["openrouter"]` catch-all used to supply
 *     for 1,109 models. Only a deliberate empty string disables.
 *   - a user rule that matches — `routing["*"] = []` most explicitly. That
 *     never reaches here at all: a matched rule is used verbatim and this
 *     function is only consulted on the gathered path.
 */
function fallbackProviderFor(defaultProvider: string | undefined): string | null {
  if (defaultProvider !== undefined && defaultProvider.length === 0) return null;
  const named = defaultProvider ?? DEFAULT_FALLBACK_PROVIDER;
  return PROVIDER_SHORTCUTS[named.toLowerCase()] ?? named.toLowerCase();
}

/**
 * The provider the last hop takes when the user expressed no preference.
 *
 * A rule, not a pinned model id: it names the one gateway that resells nearly
 * every vendor, which is why the deleted table used it as its catch-all. It is
 * overridden by `defaultProvider` and emptied by `defaultProvider: ""`.
 */
export const DEFAULT_FALLBACK_PROVIDER = "openrouter";

/**
 * The `defaultProvider` this process routes with when no caller named one:
 * `CLAUDISH_DEFAULT_PROVIDER`, then `defaultProvider` in the config file, then
 * `openrouter` (`resolveDefaultProvider`). May be `""`, which disables the
 * fallback hop.
 *
 * Read per call, like the rules. `route()` without overrides and `--probe`'s
 * chain both read it here, so the two cannot name different fallback hops. The
 * `--default-provider` flag arrives through the env variable (index.ts exports it).
 */
export function effectiveDefaultProvider(): string {
  return resolveDefaultProvider({ config: loadConfig(), env: process.env }).provider;
}

/** A chain assembled from the catalog, plus whether a catalog could be read. */
export interface CatalogChain {
  routes: Route[];
  /**
   * False means NO catalog was readable — not merely that it lacked this name.
   * A caller must treat that as "claudish cannot answer", never as "no provider
   * serves it": the two look identical in `routes` and only this tells them
   * apart.
   */
  catalogReadable: boolean;
}

/**
 * Steps 2 and 3 of the bare-name path: gather from the catalog, then append the
 * fallback hop. No credential or availability filtering — those belong to
 * `explainBareName`, which owns them, and duplicating either here would create
 * the second oracle `route-candidates.ts` exists to avoid.
 *
 * Exported for `route-candidates.test.ts`, which checks the gathered chain and
 * the fallback append apart from the two filters. No display calls it: `--probe`
 * and the config TUI render `explainRoute`, which runs these two steps
 * (`explainCatalogChain`) and then the filters, exactly as `route()` does.
 */
export function buildCatalogChain(
  model: string,
  defaultProvider?: string,
  cachePath?: string
): CatalogChain {
  const chain = explainCatalogChain(model, defaultProvider, cachePath);
  return {
    routes: chain.candidates
      .filter((candidate) => !isPreFilterExclusion(candidate.outcome))
      .map(routeOf),
    catalogReadable: chain.catalog !== "unreadable",
  };
}

/** {@link buildCatalogChain}'s two steps, with every candidate kept and the fallback's fate. */
interface CatalogChainExplanation {
  /** Gathered candidates, then the fallback hop; plan-excluded ones marked, not dropped. */
  candidates: ExplainedCandidate[];
  catalog: "found" | "absent" | "unreadable";
  fallbackWithheld?: FallbackWithheld;
}

function explainCatalogChain(
  model: string,
  defaultProvider: string | undefined,
  cachePath: string | undefined
): CatalogChainExplanation {
  // Bundled endpoints (`together`, `fireworks`) have no provider DEFINITION
  // until this has run, and `gatherFromConnections` drops a connection whose
  // provider it cannot resolve — silently, because that is also what a provider
  // the user holds no key for looks like. An earlier preview ran without it and
  // blamed this redesign for 241 unroutable `together-ai` connections it had
  // not caused.
  //
  // Called HERE rather than trusted from a caller: six startup paths register
  // endpoints and this is reachable from all of them plus the MCP server, the
  // launcher's context-window probe and the TUI. Sync, config-only and latched,
  // so every call after the first is free.
  ensureEndpointsRegistered();

  const gathering = gatherRouteCandidates(model, cachePath);
  // The gatherer's excluded candidates join the explanation with THEIR outcome,
  // never `kept`, at the position the chain order gives them. They are shown by
  // `--probe` and never become a hop: every filter below skips them.
  const ordered: Array<{ gathered: RouteCandidate; outcome: CandidateOutcome }> = [
    ...gathering.candidates.map((gathered) => ({ gathered, outcome: "kept" as const })),
    ...gathering.excluded.map(({ candidate, outcome }) => ({ gathered: candidate, outcome })),
  ].sort((a, b) => compareRouteCandidates(a.gathered, b.gathered));
  const candidates = ordered.map(({ gathered, outcome }) =>
    explainCandidate(routeFor(gathered.provider, gathered.wireId), "candidate", outcome, gathered)
  );
  const catalog = !gathering.catalogReadable
    ? "unreadable"
    : gathering.catalogMiss
      ? "absent"
      : "found";

  const fallback = fallbackProviderFor(defaultProvider);
  let fallbackWithheld: FallbackWithheld | undefined;
  if (!fallback) {
    fallbackWithheld = "disabled";
  } else if (!gathering.catalogReadable) {
    // NEVER invent a hop with no catalog: `openrouter@<name>` for a name nobody
    // published is a metered request billed for its own 404, and a name the
    // backend has since RENAMED looks identical.
    fallbackWithheld = "catalog-unreadable";
  } else if (
    candidates.some((candidate) => candidate.provider === fallback && candidate.outcome === "kept")
  ) {
    // A KEPT candidate only: an excluded one is not in the chain, so the fallback
    // still gets its own say (and the catalog's denial, or its own exclusion).
    fallbackWithheld = "already-gathered";
  } else if (catalogDeniesProvider(fallback, model, cachePath)) {
    fallbackWithheld = "catalog-denies";
  } else {
    // Through `resolveRoutingEntries`, not `routeFor`: the fallback is named by
    // PROVIDER only, so its wire id still has to be resolved, and that
    // resolution (subscription plan ids, then the catalog's `aggregators[]`)
    // lives there. It legitimately yields nothing routable when a
    // subscription's plan does not include the model.
    for (const resolved of resolveRoutingEntries([fallback], model, cachePath)) {
      candidates.push(explainCandidate(resolved.route, "fallback", entryOutcome(resolved)));
    }
  }

  return { candidates, catalog, ...(fallbackWithheld ? { fallbackWithheld } : {}) };
}

/** Why a bare name's chain is empty before any credential is read. */
type EmptyChainCause = "rule-empty" | "catalog-empty";

/**
 * The no-route outcome for a bare name whose chain is empty before any
 * credential is read. Two very different causes, and a user reading the message
 * needs to know which: their OWN rule named nothing (they asked for this), or
 * the catalog publishes no way to call the model (nobody serves it).
 */
function emptyChainOutcome(
  model: string,
  nativeProvider: string,
  cause: EmptyChainCause,
  cachePath?: string
): RouteOutcome {
  return {
    kind: "no-route",
    cause,
    reason:
      cause === "rule-empty"
        ? `A routing rule matched "${model}" and named no provider.`
        : `No provider in the catalog serves "${model}".`,
    hint: emptyChainHint(model, nativeProvider, cause, cachePath),
  };
}

/**
 * The hint for a bare name whose chain is empty before any credential is read:
 * a user rule that named no provider, or a catalog that gathered none.
 *
 * `nativeProvider` is the provider the parser attributed the name to, and its
 * credential line is offered when it IS one. `AUTO_ROUTE_PROVIDER` says the
 * parser attributed the name to nobody, so there is no credential to name. Before
 * it existed those names parsed as `native-anthropic`, and the hint told the user
 * to set ANTHROPIC_API_KEY for a model Anthropic does not serve.
 *
 * When the CATALOG gathered nothing for such a name, the `or@<model>` line is
 * also dropped if the catalog denies OpenRouter the model (`catalogDeniesProvider`,
 * the test that withholds the fallback append): it would send the user to a hop
 * nobody published. Not for a matched user rule, whose empty chain is the user's
 * own statement, and not for a name the parser attributes to a provider: that
 * one keeps the line whatever the catalog says, the same flaw, left to a
 * separate fix.
 */
function emptyChainHint(
  model: string,
  nativeProvider: string,
  cause: EmptyChainCause,
  cachePath?: string
): string | undefined {
  if (nativeProvider !== AUTO_ROUTE_PROVIDER) {
    return buildCredentialHint(model, [nativeProvider]) ?? undefined;
  }
  const suggestOpenRouter =
    cause === "rule-empty" || !catalogDeniesProvider("openrouter", model, cachePath);
  return buildCredentialHint(model, [], { suggestOpenRouter }) ?? undefined;
}

/** `route()`'s inputs for a bare name, resolved only once a name is known to be bare. */
interface BareRouting {
  rules: RoutingRules;
  defaultProvider: string | undefined;
  /** Where a matched rule key came from, when the caller read the two rule files itself. */
  scopeOf?: (ruleKey: string) => RuleScope;
  /** Problems in those two files, when the caller read them itself. */
  ruleProblems?: RoutingRuleProblem[];
}

/** Rule problems as explanation warnings, each with its one-line message. */
function ruleProblemWarnings(problems: RoutingRuleProblem[] | undefined): RouteWarning[] {
  return (problems ?? []).map((problem) => ({
    type: "rule-problem",
    problem,
    message: describeRoutingRuleProblem(problem),
  }));
}

/**
 * Path 2: a bare model name.
 *
 *   1. a user rule matches?  → that chain, VERBATIM. Never merged, reordered or
 *                              appended to, including by the fallback. A match
 *                              of `[]` is a match: the user said "no route".
 *   2. otherwise             → `gatherRouteCandidates`, which reads every
 *                              connection the catalog publishes for this model
 *                              and orders them by tier, vendor, price, window.
 *   3. append the fallback   → last, deduped, disableable, and NOT appended when
 *                              the catalog positively denies it.
 *   4. credential filter     → {@link applyCandidateFilters}.
 *   5. availability filter   → {@link applyCandidateFilters}.
 *   6. primary + fallbacks   → {@link toRoutePlan}.
 *
 * Steps 4 and 5 are deliberately NOT duplicated by step 2 — see the header of
 * `route-candidates.ts`. A gathered candidate is a claim about what the catalog
 * publishes, never a claim that this user can call it.
 */
async function explainBareName(
  requestedModel: string,
  model: string,
  nativeProvider: string,
  routing: BareRouting,
  cachePath?: string
): Promise<RouteExplanation> {
  // `null` and `[]` are DIFFERENT answers and the old `?? []` conflated them.
  // `[]` is a user rule that matched and named no provider — strict no-route,
  // and the one thing that must not then collect a fallback.
  const matchedKey = matchRoutingRuleKey(model, routing.rules);
  const matched = matchedKey === null ? null : routing.rules[matchedKey];

  let explanation: RouteExplanation;
  if (matchedKey !== null && matched !== null) {
    explanation = {
      requestedModel,
      routedModel: model,
      source: "user-rule",
      matchedPattern: matchedKey,
      ...(routing.scopeOf ? { ruleScope: routing.scopeOf(matchedKey) } : {}),
      candidates: resolveRoutingEntries(matched, model, cachePath).map((resolved) =>
        explainCandidate(resolved.route, "candidate", entryOutcome(resolved))
      ),
      outcome: { kind: "ok" },
      warnings: ruleProblemWarnings(routing.ruleProblems),
    };
  } else {
    const chain = explainCatalogChain(model, routing.defaultProvider, cachePath);
    explanation = {
      requestedModel,
      routedModel: model,
      source: "catalog",
      catalog: chain.catalog,
      candidates: chain.candidates,
      ...(chain.fallbackWithheld ? { fallbackWithheld: chain.fallbackWithheld } : {}),
      outcome: { kind: "ok" },
      warnings: ruleProblemWarnings(routing.ruleProblems),
    };
  }

  const remaining = explanation.candidates.filter(
    (candidate) => !isPreFilterExclusion(candidate.outcome)
  );

  // NO CATALOG MEANS LOCAL ONLY. With nothing readable, claudish knows no
  // provider serves this name and must say so rather than guess. A namespace
  // claim still counts — that is claudish's own statement about a plan the
  // user holds, not an inference from a catalog it could not read — so the
  // check is on an EMPTY result, not on the catalog being unreadable alone.
  // Local providers and explicit `provider@model` specs are unaffected: neither
  // comes through here.
  if (explanation.catalog === "unreadable" && remaining.length === 0) {
    explanation.outcome = {
      kind: "no-route",
      cause: "catalog-unreadable",
      reason: `No model catalog available, so "${model}" cannot be routed by name.`,
      hint:
        "Run `claudish --models-refresh` to fetch the catalog, or name the provider " +
        `explicitly (e.g. \`openrouter@${model}\`).`,
    };
    return explanation;
  }

  if (remaining.length === 0) {
    explanation.outcome = emptyChainOutcome(
      model,
      nativeProvider,
      explanation.source === "user-rule" ? "rule-empty" : "catalog-empty",
      cachePath
    );
    return explanation;
  }

  await applyCandidateFilters(explanation, remaining);
  return explanation;
}

/**
 * Steps 4 and 5 of the bare-name path, recorded on each candidate: the
 * credential filter, then the availability filter. Sets the outcome and the two
 * billing warnings. Prints nothing; `route()` prints from the explanation.
 */
async function applyCandidateFilters(
  explanation: RouteExplanation,
  candidates: ExplainedCandidate[]
): Promise<void> {
  const model = explanation.routedModel;
  const credentialed: ExplainedCandidate[] = [];
  const skipped: string[] = [];
  const skippedFailed: string[] = [];

  // ── ONE CREDENTIAL READ PER CANDIDATE PER ROUTING DECISION ────────────────
  //
  // Resolve each candidate's credentials concurrently (each call funnels through
  // the SDK serialization queue internally), but keep the original chain ORDER
  // when partitioning into credentialed / skipped.
  //
  // A SUBSCRIPTION candidate is described ONCE, and both facts come from that
  // single answer: whether it joins the chain, and — when it does not — whether
  // its credential was ABSENT or FAILED to resolve. Reading twice (a boolean to
  // partition, then `describeReadiness` to ask why) is the trap: the authority
  // memoizes a resolved key but deliberately NOT a failure, so the two reads
  // can disagree, and a credential that recovered between them would fall out
  // of both partitions and erase the evidence of the failure that removed it.
  //
  // Non-subscription candidates keep the boolean, which is all they can
  // contribute: `skippedFailed` is subscription-only by construction. The
  // boolean is itself the `=== "present"` projection of one `describeReadiness`
  // (authority.ts), so the partition is byte-identical to what it was.
  const verdicts = await Promise.all(
    candidates.map(async (candidate): Promise<ReadinessResult> => {
      if (isSubscriptionProvider(candidate.provider)) {
        return credentials.describeReadiness(candidate.provider);
      }
      const present = await hasCredentialsForProvider(candidate.provider);
      return { readiness: present ? "present" : "absent" };
    })
  );
  candidates.forEach((candidate, i) => {
    const verdict = verdicts[i];
    if (verdict.readiness === "present") {
      credentialed.push(candidate);
      return;
    }
    skipped.push(candidate.provider);
    // Measured causes of a real, present subscription key reading as "no key":
    // a concurrent 1Password handshake denial and its 15-second suppression
    // window, a locked Mac, a disabled or denied Keychain backend, and a stale
    // `.env` shadowing the op:// chain. Each one used to route a paid
    // subscription onto a metered provider with NOTHING printed.
    if (verdict.readiness === "failed") {
      skippedFailed.push(candidate.provider);
      candidate.outcome = "credential-unreadable";
    } else {
      candidate.outcome = "no-credential";
    }
  });

  if (credentialed.length === 0) {
    explanation.outcome = {
      kind: "no-route",
      cause: "no-credential",
      reason:
        skipped.length > 0
          ? `No credentialed providers in chain for "${model}" (tried: ${skipped.join(", ")}).`
          : `No providers available for "${model}".`,
      hint: buildCredentialHint(model, skipped) ?? undefined,
    };
    return;
  }

  // AVAILABILITY filter — drop a candidate only when a source positively says
  // it does not carry this model.
  //
  // This runs AFTER the credential filter, not before, and the order is not
  // cosmetic: `providerServesModel` may hit the provider's own discovery endpoint,
  // which needs that provider's credential. Asking about a provider the user
  // cannot authenticate to would be a guaranteed-failing round-trip.
  //
  // Only "not-served" removes anything. "unknown" — no source covers this
  // provider, the catalog is cold, the discovery endpoint was briefly down — keeps
  // the candidate exactly where it was. That asymmetry is the whole safety
  // property: reading absence of evidence as denial would drop every provider
  // neither source covers, which is almost entirely the SUBSCRIPTION providers,
  // and would move users off plans they pay for onto metered hops.
  const availability = await Promise.all(
    credentialed.map((candidate) => providerServesModel(candidate.provider, candidate.wireId))
  );
  const serving: ExplainedCandidate[] = [];
  const notServing: string[] = [];
  credentialed.forEach((candidate, i) => {
    const verdict = availability[i];
    if (verdict === "not-served") {
      notServing.push(candidate.provider);
      candidate.outcome = "not-served";
    } else {
      serving.push(candidate);
      candidate.availability = verdict;
    }
  });

  if (serving.length === 0) {
    // Every credentialed provider positively denied carrying this model. That is
    // strong evidence — "unknown" never lands here — so a clear no-route beats
    // sending a request that each of them would reject in turn.
    explanation.outcome = {
      kind: "no-route",
      cause: "not-served",
      reason: `No provider serves "${model}" (checked: ${notServing.join(", ")}).`,
      hint: buildCredentialHint(model, notServing) ?? undefined,
    };
    return;
  }

  // Warn only when the skip changes how the user is billed. A subscription
  // provider dropped in favour of a metered one is a cost change they did not
  // choose — claudish assembled this chain — which is the same reason
  // fallback-handler announces advancing past a spent plan. Every other skip is
  // routine and goes only to the debug log (`emitRouteNotices`).
  if (notServing.length > 0) {
    const droppedSubscription = notServing.filter((p) => isSubscriptionProvider(p));
    if (droppedSubscription.length > 0 && !isSubscriptionProvider(serving[0].provider)) {
      explanation.warnings.push({
        type: "subscription-not-served",
        providers: droppedSubscription,
        usedInstead: serving[0].provider,
        message:
          `${droppedSubscription.join(", ")} does not serve ${model} — ` +
          `using ${serving[0].displayName}, which bills per token.`,
      });
    }
  }

  // A subscription dropped because its credential FAILED gets its own warning,
  // never folded into "does not serve": the remedy differs (unlock the keychain
  // or 1Password, not "pick another model"), and "no key" would tell the user
  // to buy a subscription they already hold. Same billing condition as above —
  // raised only when the request lands on a metered provider.
  if (skippedFailed.length > 0 && !isSubscriptionProvider(serving[0].provider)) {
    explanation.warnings.push({
      type: "subscription-credential-unreadable",
      providers: skippedFailed,
      usedInstead: serving[0].provider,
      message:
        `${skippedFailed.join(", ")}: the credential could not be READ (not "no key") — ` +
        `using ${serving[0].displayName}, which bills per token.`,
    });
  }
}

/**
 * The id a route would actually SEND, extracted from its `modelSpec`.
 *
 * `buildRoutingChain` emits `provider@model` for everyone except OpenRouter,
 * whose ids are already vendor-qualified and are their own spec. Availability
 * must be asked about the wire id, never the name the user typed — comparing the
 * typed name would test the wrong side of an `externalId` mapping, and that
 * mapping is exactly what a dynamic models catalog settles (OpenCode Zen Go serves
 * `deepseek-v4-pro`, while the catalog id carries a date suffix).
 */
function wireIdOf(route: Route): string {
  const at = route.modelSpec.indexOf("@");
  return at === -1 ? route.modelSpec : route.modelSpec.slice(at + 1);
}

/**
 * Rewrite a dash-slugified GLM version to its canonical dotted form
 * (`glm-5-2` → `glm-5.2`), so a client that slugifies dots still finds the
 * catalog entry instead of missing it and falling through to the fallback hop.
 *
 * Anchored and deliberately narrow. The second group must be ALL digits to the
 * end (or to a `-suffix`), which is what keeps dash-native open-model ids
 * intact: `glm-4-9b` and `glm-4-flash` are untouched because "9b" and "flash"
 * are not pure digits.
 *
 * Applied ONLY on the bare-name path, to keep the rewrite's blast radius as
 * small as the problem it solves.
 *
 * To be precise about why that is a choice and not a load-bearing guard:
 * the explicit path forwards the ORIGINAL `modelSpec` to buildRoutingChain, which
 * re-parses it and takes the model from the entry itself, ignoring the `model`
 * argument for any entry containing "@". So normalizing the explicit path would
 * currently be a no-op rather than a bug. Restricting it here means that stays
 * true even if buildRoutingChain's precedence ever changes.
 *
 * That matters because Devin re-serves other vendors' models under uids that
 * legitimately contain dashes, `glm-5-2` and `glm-5-2-1m` among them (see
 * providers/devin/model-id-resolver.ts). Those are matched against Devin's LIVE
 * dynamic models catalog, so a `dv@glm-5-2` that ever became `[email protected]` would
 * request a uid that does not exist.
 *
 * No bare name can reach Devin through a COLLIDING family, which is what makes
 * the bare path safe to rewrite. Devin is a dynamic subscription, so it
 * publishes no catalog connection and can only be gathered from its namespace
 * claim — and that claim is exactly `/^swe-/i`, Cognition's own line. A bare
 * `glm-5-2` therefore never produces a Devin candidate, by either route.
 */
export function normalizeGlmSlug(model: string): string {
  return model.replace(
    /^glm-(\d+)-(\d+)(-.*)?$/i,
    (_m, major, minor, suffix) => `glm-${major}.${minor}${suffix ?? ""}`
  );
}

/**
 * Resolve a model name to a provider chain.
 *
 * Two paths:
 *   1. Explicit prefix (`provider@model`): the caller named the vendor. We
 *      probe ONLY that vendor's credentials; missing credentials → no-route
 *      with a credential hint. **No silent fallback** — `defaultProvider` is
 *      not consulted because the user named a specific vendor.
 *   2. Bare name: a matching USER rule wins verbatim; otherwise the chain is
 *      gathered from the cloud models catalog and the fallback hop is appended
 *      last. Then the credential and availability filters. Empty filtered chain
 *      → no-route with hints. See `explainBareName`.
 *
 * Rules and the default provider are loaded fresh each call (via `loadRoutingRules()`
 * and `effectiveDefaultProvider()`, which reads CLAUDISH_DEFAULT_PROVIDER and then
 * the config) unless overrides are supplied. Tests should pass overrides to avoid
 * disk and environment lookups.
 *
 * DERIVED from the explanation. `explainRoutePlan` makes the decision; this
 * prints the notices a request's user must see and returns the kept candidates.
 * `explainRoute` runs the same function, so a display cannot show a chain this
 * does not use.
 */
export async function route(
  modelSpec: string,
  rulesOverride?: RoutingRules,
  defaultProviderOverride?: string,
  cachePath?: string
): Promise<RoutePlan> {
  const explanation = await explainRoutePlan(
    modelSpec,
    () => {
      const rules = rulesOverride ?? loadRoutingRules();
      // When tests pass an explicit `rulesOverride`, treat the rule set as the
      // authoritative source of truth and read the default provider from neither the
      // environment nor the config file — either would leak this machine's setting
      // into unit tests. A caller that passes rules and wants a fallback
      // passes it as the third argument. Callers with no overrides
      // get `effectiveDefaultProvider()`: the env variable, then the config.
      const defaultProvider =
        defaultProviderOverride !== undefined
          ? defaultProviderOverride
          : rulesOverride !== undefined
            ? undefined
            : effectiveDefaultProvider();
      return { rules, defaultProvider };
    },
    cachePath
  );
  emitRouteNotices(explanation);
  return toRoutePlan(explanation);
}

/**
 * The decision `route()` returns, explained. `route()` and `explainRoute` both
 * call this, which is what keeps the chain a display shows and the chain a
 * request uses the same.
 *
 * An explicit spec is decided BEFORE `bareRouting` runs, so it never loads the
 * rules or reads the default provider, exactly as `route()` never has.
 */
async function explainRoutePlan(
  modelSpec: string,
  bareRouting: () => BareRouting,
  cachePath: string | undefined,
  requestedModel: string = modelSpec
): Promise<RouteExplanation> {
  const parsed = parseModelSpec(modelSpec);

  if (parsed.isExplicitProvider) {
    // Not normalized here — see normalizeGlmSlug's note on explicit specs.
    return explainExplicitSpec(requestedModel, modelSpec, parsed.model, parsed.provider, cachePath);
  }

  return explainBareName(
    requestedModel,
    normalizeGlmSlug(parsed.model),
    parsed.provider,
    bareRouting(),
    cachePath
  );
}

/**
 * The routing decision for `target`, without making it: the provider a request
 * would use, every candidate the chain considered and what removed it, and why.
 * For `--probe` and the config TUI.
 *
 * It starts where the proxy starts, at `proxyRouteDecision`. A `native` target is
 * answered there (no candidates: Claude Code's own auth serves it). `poe:<id>` and
 * `anthropic/<id>` are the explicit targets the proxy serves without `route()`.
 * A `bare` target and a `provider@model` spec run the function `route()` runs,
 * `explainRoutePlan`, with the target the proxy hands `route()` (a bare target's
 * parsed model), so the chain shown is the chain a request uses.
 *
 * Never writes to stderr: the billing notices `route()` prints are on `warnings`.
 */
export async function explainRoute(
  target: string,
  opts: ExplainRouteOptions = {}
): Promise<RouteExplanation> {
  const decision = proxyRouteDecision(target);

  if (decision.type === "native") {
    return {
      requestedModel: target,
      routedModel: target,
      source: "native",
      candidates: [],
      outcome: { kind: "ok" },
      warnings: [],
      native: decision.route,
    };
  }
  if (decision.type === "poe") {
    return explainUnroutedExplicit(target, "poe", "poe", decision.model);
  }
  if (decision.type === "explicit" && decision.via === "vendor-qualified-id") {
    return explainUnroutedExplicit(
      target,
      "vendor-qualified-id",
      decision.provider,
      decision.model
    );
  }

  const routeTarget = decision.type === "explicit" ? decision.spec : decision.model;
  return explainRoutePlan(routeTarget, () => bareRoutingFor(opts), opts.cachePath, target);
}

/**
 * The two explicit targets the proxy serves without `route()`: `poe:<id>` (its Poe
 * step) and `anthropic/<id>` (OpenRouter, the id sent verbatim). One candidate,
 * with the credential check the proxy applies and nothing else: the proxy runs no
 * availability check for either, so neither does this.
 *
 * Known gap, deferred: with no Poe credential the proxy's Poe step declines and
 * the request falls through to the native handler, while this says
 * `no-credential`.
 */
async function explainUnroutedExplicit(
  requestedModel: string,
  via: "poe" | "vendor-qualified-id",
  provider: string,
  wireId: string
): Promise<RouteExplanation> {
  // `credentials.isAvailable`, the gate the proxy's Poe step uses too.
  const credentialed = await hasCredentialsForProvider(provider);
  const tier = getProviderByName(provider)?.tier;
  return {
    requestedModel,
    routedModel: wireId,
    source: "explicit",
    via,
    candidates: [
      {
        provider,
        displayName: DISPLAY_NAMES[provider] ?? provider,
        // The target itself: the proxy carries it verbatim past its gate.
        modelSpec: requestedModel,
        wireId,
        position: "candidate",
        ...(tier !== undefined ? { tier } : {}),
        outcome: credentialed ? "kept" : "no-credential",
      },
    ],
    outcome: credentialed
      ? { kind: "ok" }
      : {
          kind: "no-route",
          cause: "explicit-no-credential",
          reason: `No credentials configured for "${provider}".`,
          hint: buildCredentialHint(wireId, [provider]) ?? undefined,
        },
    warnings: [],
  };
}

/**
 * `route()`'s inputs for a bare name, as `explainRoute` resolves them. With no
 * `rules` passed it reads both rule files itself, which is what lets it name a
 * matched rule's scope; they merge exactly as `loadRoutingRules` merges them.
 */
function bareRoutingFor(opts: ExplainRouteOptions): BareRouting {
  if (opts.rules !== undefined) {
    // route()'s guard: rules passed and no default provider named reads none.
    return { rules: opts.rules, defaultProvider: opts.defaultProvider };
  }
  const sources = loadRoutingRuleSources();
  return {
    rules: loadRoutingRules(sources),
    defaultProvider:
      opts.defaultProvider !== undefined ? opts.defaultProvider : effectiveDefaultProvider(),
    // The project file overwrites the global one key by key, so a key the project
    // file holds is the project's rule.
    scopeOf: (ruleKey) => (Object.hasOwn(sources.localRules, ruleKey) ? "project" : "global"),
    ruleProblems: ruleProblemsAfterRegistration(sources),
  };
}

/**
 * {@link routingRuleProblems} once the custom and bundled endpoints are
 * registered, so a rule naming one is not reported as unknown. Latched, so
 * free after the first call.
 */
function ruleProblemsAfterRegistration(sources: RoutingRuleSources): RoutingRuleProblem[] {
  ensureEndpointsRegistered();
  return routingRuleProblems(sources);
}

/**
 * The `RoutePlan` an explanation stands for: every `kept` candidate in chain
 * order, whatever its position, or the no-route verbatim. An uncredentialed
 * fallback is not kept, so it never becomes a handler that answers 401.
 *
 * Throws for a native explanation: `RoutePlan` has no native case, and
 * `route()` never produces one.
 */
export function toRoutePlan(explanation: RouteExplanation): RoutePlan {
  const { outcome } = explanation;
  if (outcome.kind === "no-route") {
    // `hint` is copied only where it is present (present as `undefined`
    // included), so the plan is the object route() has always returned.
    return "hint" in outcome
      ? { kind: "no-route", reason: outcome.reason, hint: outcome.hint }
      : { kind: "no-route", reason: outcome.reason };
  }
  const [primary, ...fallbacks] = explanation.candidates
    .filter((candidate) => candidate.outcome === "kept")
    .map(routeOf);
  if (!primary) {
    throw new Error(
      `toRoutePlan: "${explanation.requestedModel}" (${explanation.source}) has no kept candidate, so it has no RoutePlan.`
    );
  }
  return { kind: "ok", primary, fallbacks };
}

function routeOf(candidate: ExplainedCandidate): Route {
  return {
    provider: candidate.provider,
    modelSpec: candidate.modelSpec,
    displayName: candidate.displayName,
  };
}

/**
 * What `route()` writes for a decision, in the order it always has: the
 * `[routing] … skipped` debug line, then each billing warning through
 * `logStderr`. Only for a decision that routed; a no-route writes nothing.
 */
function emitRouteNotices(explanation: RouteExplanation): void {
  if (explanation.outcome.kind !== "ok") return;
  const notServing = explanation.candidates
    .filter((candidate) => candidate.outcome === "not-served")
    .map((candidate) => candidate.provider);
  if (notServing.length > 0) {
    log(
      `[routing] ${explanation.routedModel}: skipped ${notServing.join(", ")} — does not serve this model`
    );
  }
  for (const warning of explanation.warnings) {
    // A rule problem is about the config, not this request: the proxy prints
    // those once at startup, never per request.
    if (warning.type === "rule-problem") continue;
    // No "[claudish]" in the message: logStderr adds the prefix itself.
    logStderr(warning.message);
  }
}

/**
 * The label a display shows for a hop's tier. Strings only: a display picks the
 * colour from `C.*` at render time, never from a module-level constant.
 */
export const TIER_LABEL: Record<RouteTier, string> = {
  subscription: "subscription",
  "dynamic-subscription": "subscription · account decides models",
  native: "native API",
  gateway: "gateway",
  fallback: "fallback",
};

/**
 * A hop's label: the fallback POSITION overrides the tier of whichever provider
 * holds it. The one copy of the rule: `describeRouteExplanation` words its
 * "… first" with it, and `--probe` and the config TUI label their rows with it.
 */
export function hopLabel(candidate: {
  position?: ExplainedCandidate["position"];
  tier?: RouteTier;
}): string {
  if (candidate.position === "fallback") return TIER_LABEL.fallback;
  return candidate.tier ? TIER_LABEL[candidate.tier] : "unregistered provider";
}

/**
 * One line saying where a routing decision came from. `--probe` and the config
 * TUI both show it, so the same decision is never worded two ways.
 */
export function describeRouteExplanation(explanation: RouteExplanation): string {
  const line = describeOrigin(explanation);
  // Only where routing chose the provider: an explicit spec names the model
  // part of what the user typed, which is no news.
  const routed = explanation.source === "user-rule" || explanation.source === "catalog";
  return routed && explanation.requestedModel !== explanation.routedModel
    ? `${line} · asked as ${explanation.routedModel}`
    : line;
}

function describeOrigin(explanation: RouteExplanation): string {
  switch (explanation.source) {
    case "native":
      return "native · Claude Code's own auth · not probed";
    case "explicit": {
      const name = explanation.candidates[0]?.displayName ?? explanation.routedModel;
      return explanation.via === "vendor-qualified-id"
        ? `explicit · ${name} · vendor-qualified id sent verbatim`
        : `explicit · ${name}`;
    }
    case "user-rule": {
      const scope = explanation.ruleScope ? ` (${explanation.ruleScope})` : "";
      return `user rule "${explanation.matchedPattern}"${scope}`;
    }
    case "catalog":
      return describeCatalogOrigin(explanation);
  }
}

function describeCatalogOrigin(explanation: RouteExplanation): string {
  if (explanation.catalog === "unreadable") {
    const refresh = "run claudish --models-refresh";
    // A namespace claim is claudish's own statement, so it gathers with no
    // catalog: say what became of it rather than implying nothing routes.
    return explanation.candidates.length > 0
      ? `no cloud models catalog · ${firstHopPhrase(explanation)} · ${refresh}`
      : `no cloud models catalog · ${refresh}`;
  }
  if (explanation.catalog === "absent") return describeAbsentEntry(explanation);
  return `catalog · ${firstHopPhrase(explanation)}`;
}

/**
 * What became of a lone fallback hop the filters dropped. The line names the
 * outcome the candidate has, so a dropped hop is never described as the route.
 */
const DROPPED_FALLBACK_PHRASE: Record<Exclude<CandidateOutcome, "kept">, string> = {
  "no-credential": "has no credential",
  "credential-unreadable": "has a credential that could not be read",
  "not-served": "does not serve it",
  "excluded-by-membership": "is outside its plan's membership",
  "excluded-by-content-use": "maps it only through a contributor (content-use opt-in) id",
  "unknown-provider": "is not a known provider shortcut",
};

/**
 * A readable catalog with no entry for the name. The only candidates are a
 * namespace claim's and the fallback hop, and each gets words for its outcome.
 */
function describeAbsentEntry(explanation: RouteExplanation): string {
  const head = `catalog has no entry for "${explanation.routedModel}"`;
  const withheld = explanation.fallbackWithheld;
  if (explanation.candidates.some((candidate) => candidate.position === "candidate")) {
    // A namespace claim gathered something the catalog does not list.
    // `already-gathered` is not news here: the fallback's provider is that claim.
    const noFallback =
      withheld && withheld !== "already-gathered" ? ` · no fallback (${withheld})` : "";
    return `${head} · ${firstHopPhrase(explanation)}${noFallback}`;
  }
  if (withheld) return `${head} · no fallback (${withheld})`;
  const fallback = explanation.candidates.find((candidate) => candidate.position === "fallback");
  // The appended fallback always resolves to one candidate; this guards the words.
  if (!fallback) return `${head} · ${firstHopPhrase(explanation)}`;
  return fallback.outcome === "kept"
    ? `${head} · fallback only`
    : `${head} · fallback ${fallback.displayName} ${DROPPED_FALLBACK_PHRASE[fallback.outcome]}`;
}

function firstHopPhrase(explanation: RouteExplanation): string {
  if (explanation.outcome.kind === "no-route") return `no route (${explanation.outcome.cause})`;
  const first = explanation.candidates.find((candidate) => candidate.outcome === "kept");
  return first ? `${hopLabel(first)} first` : "no route";
}