Skip to content

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

90.8 KB
Raw Blame
/**
 * Provider Definitions — Single Source of Truth
 *
 * Every provider's identity (name, shortcuts, prefixes, patterns, API key info,
 * display name, transport type, capabilities) lives here. All other files derive
 * from these definitions instead of maintaining their own copies.
 *
 * Adding a new provider: add one entry to BUILTIN_PROVIDERS. No other file changes needed
 * for identity/routing — only transport and adapter wiring in provider-profiles.ts.
 */

import { VERTEX_SET_PROJECT_REMEDY } from "../auth/vertex-auth.js";
import type { RemoteProvider } from "../handlers/shared/remote-provider-types.js";
import type { ModelHandler } from "../handlers/types.js";
import { getEndpoint as getConfigEndpoint } from "../profile-config.js";
// Type-only import — erased at compile time, so no runtime import cycle with
// model-discovery.ts (which imports getProviderByName from here).
import type { ModelDiscoveryDescriptor } from "./model-discovery.js";
// Type-only, like ModelDiscoveryDescriptor below: erased at compile time, so
// declaring the handler here costs nothing at module load. The 28 heavy imports
// in provider-profiles.ts arrive only when `lazyHandler`'s thunk is invoked.
import type { AsyncProviderProfile, ProfileContext, ProviderProfile } from "./provider-profiles.js";
import { getRuntimeProviders } from "./runtime-providers.js";

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export type TransportType =
  | "openai"
  | "anthropic"
  | "gemini"
  | "antigravity"
  | "devin"
  | "grok-subscription"
  | "meta-muse-code"
  | "openrouter"
  | "ollamacloud"
  | "kimi-coding"
  | "litellm"
  | "vertex"
  | "local"
  | "ollama"
  | "poe";

export type TokenStrategy = "delta-aware" | "accumulate-both" | undefined;

/**
 * WHICH KIND of way-to-call-a-model a provider is — the one routing fact the
 * cloud models catalog cannot publish.
 *
 * Everything else routing needs about a connection is in the catalog: the wire
 * id, the price, the context window, the vendor, and (since v3) the route
 * binding that names the transport. What the catalog does NOT say is how
 * claudish should PREFER one connection over another, because that depends on
 * how the user pays claudish's providers, not on what the model is. This field
 * is that statement, declared once per provider, and `route-candidates.ts`
 * orders by it.
 *
 * The five values, and the line between the two flat-rate ones:
 *
 *  - `subscription` — flat-rate, and the catalog publishes the plan's MEMBERSHIP
 *    (`subscriptionPlanIds[]`), so a candidate can be gathered from the catalog
 *    alone: `kimi-coding`, `glm-coding`, `qwen-token-plan`, `opencode-zen-go`.
 *  - `dynamic-subscription` — flat-rate, but the ACCOUNT's own list decides what
 *    it serves, so the catalog publishes no connection for it at all and a
 *    candidate can only come from a namespace claim plus the account's dynamic
 *    models catalog: `antigravity`, `grok-subscription`, `devin`,
 *    `sakana-subscription`. Measured on generation
 *    `g-20260921062451697-f490edba`: all four appear in the probe map as
 *    `client_model_selection_required` and publish zero `aggregators[]` rows.
 *  - `native` — the vendor's own metered endpoint (`openai`, `google`, `kimi`,
 *    `z-ai`, `qwen-payg`, …). Billed per token by the company that made the model.
 *  - `gateway` — a metered service reselling many vendors (`openrouter`, `poe`,
 *    `vertex`, `ollamacloud`, `litellm`, `opencode-zen`), plus every custom and
 *    bundled endpoint, which claudish cannot classify more precisely than "a
 *    metered endpoint someone else operates".
 *  - `fallback` — the last-resort hop. A POSITION, never a property: whichever
 *    provider `defaultProvider` names occupies it, so NO definition declares it
 *    and a provider that would otherwise be a `gateway` does not become one
 *    here.
 *
 * NOT a billing oracle, and must not be used as one. `SUBSCRIPTION_PROVIDERS`
 * (handlers/shared/remote-provider-types.ts) still decides whether a user is
 * quoted a per-token price, and the two tables deliberately disagree on
 * `openai-codex` and `native-anthropic`: both are CREDENTIAL-decided — a metered
 * key reaches the same provider name — so naming their flat-rate ROUTE here says
 * nothing about who pays for a given request. See `ai-docs/architecture/` and
 * CLAUDE.md's Invariants: a provider wrongly called flat-rate accrues $0 against
 * real spend, which is the one error this field must not be allowed to cause.
 *
 * Unrelated to `PredefinedEndpointEvidenceSchema.tier` ("live" | "probe"), which
 * records how a bundled row was VERIFIED. Different object, different question.
 */
export type RouteTier = "subscription" | "dynamic-subscription" | "native" | "gateway" | "fallback";

export interface ProviderCapabilities {
  supportsTools?: boolean;
  supportsVision?: boolean;
  supportsStreaming?: boolean;
  supportsJsonMode?: boolean;
  supportsReasoning?: boolean;
}

/**
 * Why a provider has no handler factory. A first-class value, not an omission.
 *
 * Eight builtins legitimately construct no handler through this path, for five
 * different reasons, and every one of them used to be expressed by simply not
 * appearing in a second table — which is indistinguishable from forgetting.
 * Naming the reason is what turns "is this a bug?" into an answered question.
 */
export type NoHandlerReason =
  /** Renamed before the request path sees it; the handler lives under the new name. */
  | "renamed-at-runtime"
  /** Served by a dedicated handler that predates this table (OpenRouter). */
  | "dedicated-handler"
  /** Resolved by the local-provider path, not `direct-api`. */
  | "local"
  /** No baseUrl — exists only so nativeModelPatterns can steer a bare name. */
  | "virtual"
  /** Transport exists, factory never written. A real gap, stated as one. */
  | "unimplemented";

/** A provider that deliberately builds no handler here, and says why. */
export interface NoHandler {
  kind: "none";
  reason: NoHandlerReason;
  /** Free text: what actually serves it, or what is missing. */
  note: string;
}

/**
 * Build a handler for one request — LAZILY.
 *
 * The laziness is the whole point of the shape. The construction code imports
 * every transport, every adapter and ComposedHandler (28 static imports);
 * provider IDENTITY is read by 33 files, most of which only want to know
 * whether `gk@` is a real prefix and will never open a socket. A thunk keeps
 * those two facts in ONE table without making the cheap question pay for the
 * expensive one.
 */
export type LazyHandlerFactory = (ctx: ProfileContext) => Promise<ModelHandler | null>;

/** Type-only view of the builder module. Erased at compile time — no runtime import. */
type ProfileBuilders = typeof import("./provider-profiles.js");

/**
 * Wrap a builder in a deferred import.
 *
 * `pick` is a typed accessor rather than a string key on purpose: a key would
 * be a third place to typo a provider name, which is the exact failure this
 * merge exists to remove.
 */
function lazyHandler(
  pick: (m: ProfileBuilders) => ProviderProfile | AsyncProviderProfile
): LazyHandlerFactory {
  return async (ctx) => pick(await import("./provider-profiles.js")).createHandler(ctx);
}

export interface ProviderDefinition {
  /**
   * How this provider builds a handler — or an explicit statement that it does
   * not, and why.
   *
   * REQUIRED, and that is the point of merging the two tables. Handler wiring
   * used to live in a separate `PROVIDER_PROFILES` map keyed by name, so adding
   * a builtin and forgetting the second entry produced a provider that silently
   * answered from OPENROUTER — CLAUDE.md names that this project's worst
   * failure class. As a required field the compiler refuses the half-add, which
   * is a stronger guarantee than any test: you cannot merge code that forgot.
   */
  createHandler: LazyHandlerFactory | NoHandler;
  /**
   * WHICH KIND of route this is — see {@link RouteTier}. Read at routing time by
   * `route-candidates.ts`; a provider with no tier can never become a gathered
   * candidate, which is the safe direction (it is skipped, never guessed at).
   *
   * Declared optional HERE and REQUIRED on every table that feeds routing:
   * `BUILTIN_PROVIDERS` and the custom-endpoint builder are both typed
   * {@link TieredProviderDefinition}, so adding a provider to either without a
   * tier does not compile — the same compiler-enforced completeness
   * `createHandler` gets, and for the same reason (a half-added provider
   * silently answering from somewhere else is this project's worst failure
   * class). The optionality exists only because four TEST files construct
   * `ProviderDefinition` literals for unrelated features, and a test's fixture
   * has no routing tier to declare. Promote it to required here once those
   * literals carry one.
   */
  tier?: RouteTier;
  /** Canonical provider name (lowercase, unique key) */
  name: string;
  /** Human-readable display name (proper capitalization) */
  displayName: string;
  /** Transport type for handler construction */
  transport: TransportType;
  /** Token counting strategy */
  tokenStrategy?: TokenStrategy;
  /** Base URL for the API (may be overridden by env var) */
  baseUrl: string;
  /** Environment variables that can override the base URL */
  baseUrlEnvVars?: string[];
  /**
   * This provider's TRANSPORT builds the request URL itself, so an empty
   * `baseUrl` is correct and complete rather than missing.
   *
   * Declared because "no base URL" otherwise means "not configured", and
   * `getRemoteProviders()` drops such a provider from the registry — after which
   * `resolveRemoteProvider("vertex@…")` returns null and the failure reads as a
   * missing credential, sending the user to find a key that was never the
   * problem. LiteLLM has the same empty `baseUrl` but a DIFFERENT cause: its URL
   * arrives from `LITELLM_BASE_URL`, so resolving `baseUrlEnvVars` rescues it.
   * No env var can ever rescue this case, because there is no single URL to
   * name: Vertex's endpoint is assembled per request from the project, the
   * location and the publisher
   * (`https://<location>-aiplatform.googleapis.com/v1/projects/<project>/…`).
   *
   * A capability, not a name check: anything whose transport composes its own
   * endpoint sets this, and nothing in the registry mentions "vertex".
   */
  buildsOwnEndpoint?: true;
  /** API path template (e.g., "/v1/chat/completions") */
  apiPath: string;
  /** Primary API key environment variable */
  apiKeyEnvVar: string;
  /** Alternative env vars to check */
  apiKeyAliases?: string[];
  /**
   * Env vars that hold a DIFFERENT tier's key for the SAME vendor — names a user
   * is likely to already have set, which this provider does NOT accept.
   *
   * Purely explanatory: nothing resolves, signs or gates on it. It exists because
   * "No API key for provider X. Set Y" is an unhelpful sentence to read while
   * holding a key from the same vendor, and the user's next move — exporting the
   * key they have under the name we asked for — produces a 401 they cannot
   * attribute. `describeMissingCredential` appends one clause naming the sibling
   * and, looked up LIVE from the catalog, which provider it does belong to.
   *
   * Declared today only by `opencode-zen-go`, which carried
   * `apiKeyAliases: ["OPENCODE_API_KEY"]` until 2026-09-02 and so has an
   * installed base of users for whom that key used to work. `sakana-subscription`
   * / `sakana`, `qwen-token-plan` / `qwen-payg` and `kimi-coding` / `kimi` are the same
   * two-tier shape and could adopt it; each is a user-visible message change and
   * belongs to whichever change is looking at that provider.
   */
  siblingKeyEnvVars?: string[];
  /** Human-readable API key description */
  apiKeyDescription: string;
  /** URL where user can obtain an API key */
  apiKeyUrl: string;
  /**
   * Auth scheme for the API key header.
   *
   * `"none"` means the provider takes NO credential — the transports emit no auth
   * header and the credential authority reports it available with nothing
   * configured. Only reachable from a user `customEndpoints` entry today; no
   * builtin declares it, and none should, since every hosted vendor authenticates.
   */
  authScheme?: "x-api-key" | "bearer" | "none";
  /** Provider shortcuts (e.g., ["g", "gemini"] → "google") */
  shortcuts: string[];
  /** Legacy prefix patterns for backwards compat (e.g., ["g/", "gemini/"]) */
  legacyPrefixes: Array<{ prefix: string; stripPrefix: boolean }>;
  /** Native model patterns for auto-detection (when no provider prefix) */
  nativeModelPatterns?: Array<{ pattern: RegExp }>;
  /**
   * Opt in to live, per-subscription model discovery. When set, claudish calls
   * the provider's own authenticated model-listing endpoint to learn the real
   * dynamic models catalog and per-model context windows for THIS user's plan, instead of
   * trusting a static list. Required for subscription endpoints whose context
   * window varies by tier (see providers/model-discovery.ts).
   */
  modelDiscovery?: ModelDiscoveryDescriptor;
  /** Provider capabilities */
  capabilities?: ProviderCapabilities;
  /** Custom HTTP headers to include with requests */
  headers?: Record<string, string>;
  // `publicKeyFallback?: string` REMOVED (2026-08-22).
  //
  // It carried a hardcoded literal to send as the bearer token for a vendor's
  // "free tier" — only ever `"public"`, only ever for OpenCode Zen, and the
  // endpoint answers 401 to it. Two things made it worse than a dead value:
  // `isAvailable()` returned true on its mere PRESENCE without issuing any
  // request, so the provider advertised itself Ready and the failure only
  // appeared under a live test; and inventing a vendor's shared secret is
  // exactly what the catalog forbids ("a default is a rule, never a pinned id").
  //
  // `authScheme: "none"` is the correct — and now the only — way to express a
  // keyless endpoint. It states that NO credential is expected and sends no auth
  // header, rather than guessing one. See config-schema.ts and proxy-server.ts.
  /** OAuth credential file under ~/.claudish/ to check as fallback */
  oauthFallback?: string;
  /**
   * Slug for `claudish login {slug}` if this provider supports OAuth.
   * Single source of truth: keep this in sync with AUTH_PROVIDERS in
   * src/auth/auth-commands.ts.
   */
  oauthLoginSlug?: "codex" | "kimi" | "antigravity" | "grok" | "muse";
  /** Whether this is a local provider (no API key needed) */
  isLocal?: boolean;
  /** Whether this provider supports direct API access (not just via OpenRouter) */
  isDirectApi?: boolean;
  /** Shortest @ prefix for handler creation (reverse of shortcuts) */
  shortestPrefix?: string;
  /** Short description for TUI display (e.g., "580+ models, default backend") */
  description?: string;
}

/**
 * A definition that MUST state its routing tier.
 *
 * Every table a routing decision reads is typed with this rather than with
 * `ProviderDefinition`, so "forgot the tier" is a compile error at the two
 * places a real provider is born — `BUILTIN_PROVIDERS` below and
 * `buildProviderDefinition` in custom-endpoints-loader.ts — instead of a silent
 * absence that drops the provider from every gathered chain.
 */
export type TieredProviderDefinition = ProviderDefinition & { tier: RouteTier };

// ---------------------------------------------------------------------------
// Built-in provider definitions
// ---------------------------------------------------------------------------

// ---------------------------------------------------------------------------
// Handler factories, shared across providers.
//
// Declared once here rather than inline per entry because the mapping is
// many-to-one (several OpenAI-compatible providers share `openaiProfile`), and
// inlining copies the same thunk per entry, which is how tables drift. A
// catalog-routed provider is built from its connection's wire BEFORE its
// profile is consulted (`createHandlerForProvider` → `buildWireHandler`); the
// profile serves only the providers and models the catalog does not route.
// ---------------------------------------------------------------------------

const geminiHandler = lazyHandler((m) => m.geminiProfile);
const antigravityHandler = lazyHandler((m) => m.antigravityProfile);
const devinHandler = lazyHandler((m) => m.devinProfile);
const grokSubscriptionHandler = lazyHandler((m) => m.grokSubscriptionProfile);
const museCodeHandler = lazyHandler((m) => m.museCodeProfile);
const openaiHandler = lazyHandler((m) => m.openaiProfile);
const openaiCodexHandler = lazyHandler((m) => m.openaiCodexProfile);
const anthropicCompatHandler = lazyHandler((m) => m.anthropicCompatProfile);
const glmHandler = lazyHandler((m) => m.glmProfile);
const openCodeZenHandler = lazyHandler((m) => m.openCodeZenProfile);
const ollamaCloudHandler = lazyHandler((m) => m.ollamaCloudProfile);
const litellmHandler = lazyHandler((m) => m.litellmProfile);
const vertexHandler = lazyHandler((m) => m.vertexProfile);
const poeHandler = lazyHandler((m) => m.poeProfile);

/** Shorthand for the five documented reasons a provider builds nothing here. */
const noHandler = (reason: NoHandlerReason, note: string): NoHandler => ({
  kind: "none",
  reason,
  note,
});

/**
 * Handler for a provider registered at RUNTIME — a custom endpoint.
 *
 * Its builder cannot be named at compile time because the provider does not
 * exist until a config file is read, so this defers to the runtime profile
 * registry the loader populates. Still a required field on the definition, so a
 * custom endpoint that registers a provider and forgets its profile fails the
 * same way a builtin would: at the type level, not at request time.
 */
export function runtimeHandler(name: string): LazyHandlerFactory {
  return async (ctx) => {
    const { getRuntimeProfiles } = await import("./runtime-providers.js");
    const profile = getRuntimeProfiles().get(name);
    return profile ? profile.createHandler(ctx) : null;
  };
}

export const BUILTIN_PROVIDERS: TieredProviderDefinition[] = [
  // ── Google Gemini (direct API) ─────────────────────────────────────
  {
    createHandler: geminiHandler,
    tier: "native",
    name: "google",
    displayName: "Gemini",
    transport: "gemini",
    baseUrl: "https://generativelanguage.googleapis.com",
    baseUrlEnvVars: ["GEMINI_BASE_URL"],
    apiPath: "/v1beta/models/{model}:streamGenerateContent?alt=sse",
    apiKeyEnvVar: "GEMINI_API_KEY",
    apiKeyDescription: "Google Gemini API Key",
    apiKeyUrl: "https://aistudio.google.com/app/apikey",
    shortcuts: ["g", "gemini"],
    shortestPrefix: "g",
    legacyPrefixes: [
      { prefix: "g/", stripPrefix: true },
      { prefix: "gemini/", stripPrefix: true },
    ],
    nativeModelPatterns: [{ pattern: /^google\//i }, { pattern: /^gemini-/i }],
    isDirectApi: true,
    description: "Direct Gemini API (g@, google@)",
    // No oauthLoginSlug: the Gemini direct API takes GEMINI_API_KEY. The
    // Gemini SUBSCRIPTION flow is `antigravity` below, which authenticates with
    // the shared agy token — a different product, not an OAuth mode of this one.
  },

  // ── Antigravity (shared OAuth token — subscription) ────────────────
  // The individuals/Ultra subscription flow. Auth = the SHARED Antigravity
  // token (the `agy` keychain item), NOT a GEMINI_API_KEY.
  {
    createHandler: antigravityHandler,
    tier: "dynamic-subscription",
    name: "antigravity",
    displayName: "Antigravity",
    transport: "antigravity",
    baseUrl: "https://cloudcode-pa.googleapis.com",
    apiPath: "/v1internal:streamGenerateContent?alt=sse",
    apiKeyEnvVar: "",
    apiKeyDescription: "Antigravity (shared OAuth token)",
    apiKeyUrl: "https://antigravity.google/",
    // Dedicated login: `claudish login antigravity` (OAuth PKCE → shared keychain
    // store). NOT the gemini-cli login, which mints a token the Antigravity
    // backend rejects for generation.
    oauthLoginSlug: "antigravity",
    shortcuts: ["ag", "antigravity"],
    shortestPrefix: "ag",
    legacyPrefixes: [
      { prefix: "ag/", stripPrefix: true },
      { prefix: "antigravity/", stripPrefix: true },
    ],
    // THE NAMESPACE CLAIM, not an auto-detect win. `google` declares the same
    // `/^gemini-/i` and is defined ABOVE, so `getNativeModelPatterns()` — which
    // is first-wins on array order — still answers `google` for a bare
    // `gemini-3.6-flash`, exactly as before. What this adds is the one thing
    // `route-candidates.ts` needs: `google/antigravity-subscription` sits in the
    // probe map as `client_model_selection_required` and publishes ZERO
    // `aggregators[]` rows, so gathering from the catalog alone can never see
    // this plan. Without a claim here, the 5 Gemini models a seat actually
    // serves (measured on generation g-20260921062451697-f490edba) would move
    // off a flat-rate plan onto the metered `google` hop — the one ordering
    // error that costs money.
    //
    // The family, not a list of ids: which VARIANTS a seat serves is per-account
    // and drifts (`v1internal:fetchAvailableModels`), and the AVAILABILITY
    // filter asks the account itself. This only says "Gemini is the namespace
    // this plan sells", which is the provider's product definition.
    //
    // Deliberately NOT `/^claude-/i`: the Antigravity backend does serve Claude
    // ids, but a bare Claude name must never reach `route()` at all
    // (`nativeRouteFor` handles it first — see CLAUDE.md's Invariants).
    nativeModelPatterns: [{ pattern: /^gemini-/i }],
    // Not a GET — an OAuth POST to v1internal:fetchAvailableModels, so `path`
    // is ignored. Declared so the picker prefers the per-subscription dynamic
    // models catalog and, more importantly, its per-model `maxTokens`: the backend and
    // the shared catalog disagree by 4x on claude-sonnet-4-6 (250K vs 1M).
    modelDiscovery: { path: "", format: "antigravity" },
    isDirectApi: true,
    description: "Antigravity subscription (ag@)",
  },

  // ── Devin (Cognition/Codeium subscription) ─────────────────────────
  // Auth is the Devin CLI's own session token, read verbatim from
  // ~/.local/share/devin/credentials.toml (or WINDSURF_API_KEY). One flat
  // subscription serving several vendors' models over a Connect-protobuf rpc.
  {
    createHandler: devinHandler,
    tier: "dynamic-subscription",
    name: "devin",
    displayName: "Devin",
    transport: "devin",
    baseUrl: "https://server.codeium.com",
    baseUrlEnvVars: ["WINDSURF_API_SERVER_URL"],
    apiPath: "/exa.api_server_pb.ApiServerService/GetChatMessage",
    // MUST stay empty — this is load-bearing, not an oversight. proxy-server
    // only runs its credential-extraction block for a NON-empty apiKeyEnvVar,
    // and that block extracts the key by stripping `Bearer ` from
    // `auth.headers.Authorization`. Devin's artifact is
    // `authorization: Basic <k>-<k>` (lowercase header, Basic scheme), so the
    // extraction would yield "" -> `return null` -> the handler is never built
    // and the model SILENTLY falls through to OpenRouter. A wrong provider
    // quietly succeeding is worse than a crash. Empty makes proxy-server skip
    // the block and lets the transport pull its own artifact from the credential
    // authority — exactly the Antigravity pattern.
    apiKeyEnvVar: "",
    apiKeyDescription: "Devin CLI session token (~/.local/share/devin/credentials.toml)",
    apiKeyUrl: "https://devin.ai/",
    shortcuts: ["dv", "devin"],
    shortestPrefix: "dv",
    legacyPrefixes: [
      { prefix: "dv/", stripPrefix: true },
      { prefix: "devin/", stripPrefix: true },
    ],
    // EXACTLY ONE pattern, and it is Cognition's OWN family.
    //
    // The rule this narrows: Devin's RE-SERVED uids collide head-on with other
    // providers' namespaces — `claude-opus-5-medium` matches native-anthropic's
    // /^claude-/i, `gpt-5-6-luna-medium` matches OpenAI's, `glm-5-2` matches
    // GLM's, `kimi-k3-high` matches Kimi's — so those must never auto-detect as
    // Devin, and Devin must never be prepended to their chains. That reasoning
    // is intact: access to another vendor's model through the plan stays
    // EXPLICIT (`dv@claude-opus-5`), same as Alibaba Token Plan.
    //
    // `swe-*` is different in kind: it is Cognition's own model line, no other
    // provider in the catalog carries it, and it collides with nothing. The
    // pattern is Devin's namespace claim: `gatherFromNamespaceClaims`
    // (route-candidates.ts) makes Devin a route candidate for a bare `swe-*`
    // name, which the catalog cannot list because the account decides what the
    // seat serves. It was added when `parseModelSpec` still sent every
    // unrecognised bare name to native-anthropic: `swe-1.7` never reached
    // routing, was silently rewritten to `claude-opus-4-1` and answered by a
    // different vendor's model, probing byte-identically to a nonsense string
    // while `[email protected]` served fine.
    //
    // Do NOT extend this list to Devin's re-served families.
    nativeModelPatterns: [{ pattern: /^swe-/i }],
    modelDiscovery: { path: "", format: "devin-connect" },
    isDirectApi: true,
    description: "Devin subscription (dv@, devin@)",
  },

  // NOTE: the `gemini-codeassist` provider was REMOVED here. Google retired
  // "Code Assist for individuals" for gemini-cli's OAuth client
  // (UNSUPPORTED_CLIENT), so it could not authenticate for any consumer account.
  // The Gemini subscription flow is `antigravity` above; `g@`/`google@` remains
  // the direct pay-per-use API.

  // ── OpenAI (direct API) ────────────────────────────────────────────
  {
    createHandler: openaiHandler,
    tier: "native",
    name: "openai",
    displayName: "OpenAI",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.openai.com",
    baseUrlEnvVars: ["OPENAI_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "OPENAI_API_KEY",
    apiKeyDescription: "OpenAI API Key",
    apiKeyUrl: "https://platform.openai.com/api-keys",
    shortcuts: ["oai"],
    shortestPrefix: "oai",
    legacyPrefixes: [{ prefix: "oai/", stripPrefix: true }],
    nativeModelPatterns: [
      { pattern: /^openai\//i },
      { pattern: /^gpt-/i },
      { pattern: /^o1(-|$)/i },
      { pattern: /^o3(-|$)/i },
      { pattern: /^chatgpt-/i },
    ],
    isDirectApi: true,
    description: "Direct OpenAI API (oai@)",
  },

  // ── OpenAI Codex (Responses API — ChatGPT Plus/Pro subscription) ────
  {
    createHandler: openaiCodexHandler,
    // The ROUTE is the ChatGPT plan, and the catalog publishes its membership
    // (`openai/codex-subscription`), so this is where routing should prefer it.
    // It is NOT a billing statement: `openai-codex` is CREDENTIAL-decided
    // (`CREDENTIAL_DECIDED_PROVIDERS`) because an `OPENAI_CODEX_API_KEY` reaches
    // the same name against api.openai.com and bills the developer — measured,
    // `"payer": "developer"`. So this provider must still never be derived into
    // `SUBSCRIPTION_PROVIDERS`; the name check there short-circuits the probe.
    tier: "subscription",
    name: "openai-codex",
    displayName: "OpenAI Codex",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.openai.com",
    baseUrlEnvVars: ["OPENAI_CODEX_BASE_URL"],
    apiPath: "/v1/responses",
    apiKeyEnvVar: "OPENAI_CODEX_API_KEY",
    apiKeyAliases: ["OPENAI_API_KEY"],
    apiKeyDescription: "OpenAI Codex API Key (ChatGPT Plus/Pro subscription)",
    apiKeyUrl: "https://platform.openai.com/api-keys",
    oauthFallback: "codex-oauth.json",
    oauthLoginSlug: "codex",
    shortcuts: ["cx", "codex"],
    shortestPrefix: "cx",
    legacyPrefixes: [{ prefix: "cx/", stripPrefix: true }],
    nativeModelPatterns: [{ pattern: /codex$/i }],
    isDirectApi: true,
    description: "OpenAI Codex (cx@, codex@)",
  },

  // ── OpenRouter ─────────────────────────────────────────────────────
  {
    createHandler: noHandler(
      "dedicated-handler",
      "Served by OpenRouterHandler, which predates this table. proxy-server returns null here on purpose so the request falls through to it."
    ),
    tier: "gateway",
    name: "openrouter",
    displayName: "OpenRouter",
    transport: "openrouter",
    baseUrl: "https://openrouter.ai",
    apiPath: "/api/v1/chat/completions",
    apiKeyEnvVar: "OPENROUTER_API_KEY",
    apiKeyDescription: "OpenRouter API Key",
    apiKeyUrl: "https://openrouter.ai/keys",
    shortcuts: ["or"],
    shortestPrefix: "or",
    legacyPrefixes: [{ prefix: "or/", stripPrefix: true }],
    nativeModelPatterns: [{ pattern: /^openrouter\//i }],
    headers: {
      "HTTP-Referer": "https://claudish.com",
      "X-Title": "Claudish - OpenRouter Proxy",
    },
    isDirectApi: true,
    description: "580+ models, default backend (or@)",
  },

  // ── xAI / Grok (OpenAI-compatible) ──────────────────────────────────
  {
    createHandler: openaiHandler,
    tier: "native",
    name: "x-ai",
    displayName: "xAI",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.x.ai",
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "XAI_API_KEY",
    apiKeyDescription: "xAI API Key",
    apiKeyUrl: "https://console.x.ai/",
    // Canonical name is "x-ai" (matches the Firebase catalog slug). The bare
    // "xai" and "grok" forms remain as input aliases so existing `xai@...`
    // commands and scripts keep routing.
    shortcuts: ["x-ai", "xai", "grok"],
    shortestPrefix: "x-ai",
    legacyPrefixes: [{ prefix: "xai/", stripPrefix: true }],
    nativeModelPatterns: [{ pattern: /^x-ai\//i }, { pattern: /^grok-/i }],
    isDirectApi: true,
  },

  // ── Grok Build subscription (SuperGrok / X Premium+) ───────────────
  //
  // Same models as `x-ai` above, different BILLING: this one is covered by the
  // user's Grok subscription, while `x-ai` is metered per token against
  // XAI_API_KEY. The same subscription-vs-metered split claudish already models
  // for GLM (gc@/glm@), MiniMax (mmc@/mm@), Qwen (qtoken@/qpay@) and Sakana (sc@/sakana@).
  //
  // Full protocol write-up: ai-docs/reports/grok-subscription/protocol-spec.md
  {
    createHandler: grokSubscriptionHandler,
    tier: "dynamic-subscription",
    name: "grok-subscription",
    displayName: "Grok Build (subscription)",
    transport: "grok-subscription",
    tokenStrategy: "delta-aware",
    // The proxy the Grok CLI itself talks to. GROK_PROXY_URL is the CLI's own
    // override, so it is honoured here too.
    baseUrl: "https://cli-chat-proxy.grok.com",
    baseUrlEnvVars: ["GROK_PROXY_URL"],
    apiPath: "/v1/chat/completions",
    // MUST stay empty — load-bearing, not an oversight. proxy-server only runs
    // its credential-extraction block for a NON-empty apiKeyEnvVar, and that
    // block would happily extract this bearer token and then CACHE it, past the
    // six-hour life it actually has. Empty makes proxy-server skip the block, so
    // every request goes through the credential authority, which is the only
    // place expiry is checked and a refresh happens.
    apiKeyEnvVar: "",
    apiKeyDescription:
      "Grok subscription OAuth (`claudish login grok`, or an existing `grok login`)",
    apiKeyUrl: "https://x.ai/cli",
    // claudish drives its OWN device-authorization flow — xAI registered this
    // as a PUBLIC client (no secret), so unlike Antigravity there is no
    // rotating app secret forcing us through the vendor CLI.
    oauthLoginSlug: "grok",
    oauthFallback: "grok-oauth.json",
    // `grok@` deliberately stays with the metered `x-ai` provider so no existing
    // command silently changes meaning. `gk@` is the new, explicit spelling.
    shortcuts: ["gk", "grok-subscription"],
    shortestPrefix: "gk",
    legacyPrefixes: [{ prefix: "gk/", stripPrefix: true }],
    // THE NAMESPACE CLAIM. `x-ai` declares the same `/^grok-/i` and is defined
    // ABOVE, so `getNativeModelPatterns()` — first-wins on array order — still
    // answers `x-ai` for a bare `grok-4.6`, and this provider does NOT win
    // auto-detection. A claim is not an auto-detect: it exists so
    // `route-candidates.ts` can emit a candidate the CATALOG cannot publish.
    // `x-ai/supergrok-subscription` sits in the probe map as
    // `client_model_selection_required` with ZERO `aggregators[]` rows, so
    // gathering would otherwise put a SuperGrok seat's 2 models (measured on
    // generation g-20260921062451697-f490edba) on the metered `x-ai` hop and
    // bill per token for what the plan already covers.
    //
    // Safe as a bare name for the reason the routing chain relied on before:
    // these ids are xAI's OWN, so — unlike Devin's re-served uids — there is no
    // other vendor's namespace to collide with. Which grok ids a seat serves
    // stays ACCOUNT-SCOPED, so the claim names the family and the availability
    // filter asks `/v1/models`.
    nativeModelPatterns: [{ pattern: /^grok-/i }],
    // The dynamic models catalog is ACCOUNT-SCOPED and drifts, so it is discovered, never
    // pinned. `/v1/models` is genuinely authenticated here (401 without a token,
    // unlike Alibaba's coding-intl model list where a 200 proves nothing), and it
    // answers the standard OpenAI `{object, data:[{id}]}` shape. Discovery falls
    // back to the credential authority when `apiKeyEnvVar` is empty, which also
    // supplies the mandatory client-version headers.
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    isDirectApi: true,
    description: "Grok on your SuperGrok or X Premium+ plan (gk@)",
  },

  // ── Muse Code (Meta subscription) ──────────────────────────────────
  // Meta's flat-rate Muse Code plan, signed with an `LLM|` key MINTED from a
  // Meta `dca:` login (claudish's own, its borrowed copy, or — interactive only —
  // the Muse Code CLI's Keychain item). The mint's entitlement answer is what
  // permits SUB billing. Wire: OpenAI Responses, `store: false`. The metered
  // Meta API on META_API_KEY is the separate `meta` provider.
  // Write-up: ai-docs/sessions/…/research/muse-wire.md (§8: mint and login).
  {
    createHandler: museCodeHandler,
    tier: "subscription",
    name: "meta-muse-code",
    displayName: "Muse Code (subscription)",
    transport: "meta-muse-code",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.meta.ai",
    // No baseUrlEnvVars, deliberately: the login, the minted key and every
    // request go only to https://api.meta.ai. Bun loads a cwd `.env` before any
    // claudish code runs, so an override could be set by any repository
    // (`MUSE_CODE_BASE_URL` in providers/meta-muse/muse-mint.ts).
    apiPath: "/v1/responses",
    // MUST stay empty, as for gk@/ag@/dv@: a non-empty value makes the generic
    // loop register an api-key provider and lets proxy-server cache a minted
    // key past its life. META_API_KEY is never aliased (metered `meta`).
    apiKeyEnvVar: "",
    apiKeyDescription:
      "Muse Code login (`claudish login muse`, or `muse login` in an interactive session)",
    apiKeyUrl: "https://dev.meta.ai",
    // `claudish login muse`: Meta device code, claudish's own login file.
    oauthLoginSlug: "muse",
    shortcuts: ["muse"],
    shortestPrefix: "muse",
    legacyPrefixes: [],
    // The account's own list, with windows and modalities; contributor ids are
    // moved out of every offered list by the discovery choke point.
    modelDiscovery: { path: "/muse-code/models", format: "muse-code-models" },
    isDirectApi: true,
    description: "Muse Code on your Meta subscription (muse@)",
  },

  // ── MiniMax (Anthropic-compatible) ─────────────────────────────────
  {
    createHandler: anthropicCompatHandler,
    tier: "native",
    name: "minimax",
    displayName: "MiniMax",
    transport: "anthropic",
    // The two MiniMax hosts are REGIONS, and a key works only on the host of the
    // platform that issued it: api.minimax.io for the international platform
    // (platform.minimax.io), api.minimaxi.com for the China platform
    // (minimaxi.com). Metered and coding-plan keys follow the same rule.
    //
    // The default is the international host. Measured 2026-09-19 with a fresh
    // international metered key: api.minimax.io answered 200 on /v1/models,
    // /anthropic/v1/messages and /v1/chat/completions, and api.minimaxi.com
    // answered 401 "invalid api key (2049)" on all three. This entry pointed at
    // minimaxi.com from 2026-08-11 (b7173d2), so every international metered key
    // failed. A China-platform key needs MINIMAX_BASE_URL=https://api.minimaxi.com.
    // The catalog publishes one profile, `minimax/direct-api`, with no region, so
    // the host is claudish's choice rather than a contract value.
    baseUrl: "https://api.minimax.io",
    baseUrlEnvVars: ["MINIMAX_BASE_URL"],
    apiPath: "/anthropic/v1/messages",
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    apiKeyEnvVar: "MINIMAX_API_KEY",
    apiKeyDescription: "MiniMax API Key",
    apiKeyUrl: "https://platform.minimax.io/user-center/basic-information/interface-key",
    authScheme: "bearer",
    shortcuts: ["mm", "mmax"],
    shortestPrefix: "mm",
    legacyPrefixes: [
      { prefix: "mmax/", stripPrefix: true },
      { prefix: "mm/", stripPrefix: true },
    ],
    nativeModelPatterns: [
      { pattern: /^minimax\//i },
      { pattern: /^minimax-/i },
      { pattern: /^abab-/i },
    ],
    isDirectApi: true,
    description: "MiniMax API (mm@, mmax@)",
  },

  // ── MiniMax Coding Plan ────────────────────────────────────────────
  {
    createHandler: anthropicCompatHandler,
    tier: "subscription",
    name: "minimax-coding",
    displayName: "MiniMax Coding",
    transport: "anthropic",
    baseUrl: "https://api.minimax.io",
    baseUrlEnvVars: ["MINIMAX_CODING_BASE_URL"],
    apiPath: "/anthropic/v1/messages",
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    apiKeyEnvVar: "MINIMAX_CODING_API_KEY",
    apiKeyDescription: "MiniMax Coding Plan API Key",
    apiKeyUrl: "https://platform.minimax.io/user-center/basic-information/interface-key",
    authScheme: "bearer",
    shortcuts: ["mmc"],
    shortestPrefix: "mmc",
    legacyPrefixes: [{ prefix: "mmc/", stripPrefix: true }],
    isDirectApi: true,
    description: "MiniMax Coding Plan (mmc@)",
  },

  // ── Kimi Coding Plan (must be before Kimi — kimi-for-coding$ is more specific than kimi-*)
  {
    createHandler: anthropicCompatHandler,
    tier: "subscription",
    name: "kimi-coding",
    displayName: "Kimi Coding",
    transport: "kimi-coding",
    baseUrl: "https://api.kimi.com/coding/v1",
    apiPath: "/messages",
    apiKeyEnvVar: "KIMI_CODING_API_KEY",
    apiKeyDescription: "Kimi Coding API Key (membership page, or run: claudish login kimi)",
    apiKeyUrl: "https://www.kimi.com/code",
    oauthFallback: "kimi-oauth.json",
    oauthLoginSlug: "kimi",
    shortcuts: ["kc"],
    shortestPrefix: "kc",
    legacyPrefixes: [{ prefix: "kc/", stripPrefix: true }],
    // Namespace ownership only — WHICH models exist is discovered live, never
    // listed here. `kimi-for-coding` is K2.7 Coding (+ `-highspeed`); `k3*`
    // covers K3 and its context-capped SKUs (k3-256k).
    nativeModelPatterns: [{ pattern: /^kimi-for-coding/i }, { pattern: /^k3(-|$)/i }],
    // The coding endpoint serves several models whose context windows depend on
    // the subscriber's tier (k3 is 1M only on Allegretto+). Ask the endpoint
    // itself — the call is authenticated, so it answers for THIS user's plan.
    modelDiscovery: { path: "/models", format: "openai-models-list" },
    isDirectApi: true,
    description: "Kimi Coding Plan (kc@)",
  },

  // ── Kimi / Moonshot (Anthropic-compatible) ─────────────────────────
  {
    createHandler: anthropicCompatHandler,
    tier: "native",
    name: "kimi",
    displayName: "Kimi",
    transport: "anthropic",
    baseUrl: "https://api.moonshot.ai",
    baseUrlEnvVars: ["MOONSHOT_BASE_URL", "KIMI_BASE_URL"],
    apiPath: "/anthropic/v1/messages",
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    apiKeyEnvVar: "MOONSHOT_API_KEY",
    apiKeyAliases: ["KIMI_API_KEY"],
    apiKeyDescription: "Kimi/Moonshot API Key",
    apiKeyUrl: "https://platform.moonshot.cn/",
    shortcuts: ["kimi", "moon", "moonshot"],
    shortestPrefix: "kimi",
    legacyPrefixes: [
      { prefix: "kimi/", stripPrefix: true },
      { prefix: "moonshot/", stripPrefix: true },
    ],
    nativeModelPatterns: [
      { pattern: /^moonshot(ai)?\//i },
      { pattern: /^moonshot-/i },
      { pattern: /^kimi-/i },
    ],
    isDirectApi: true,
    description: "Kimi API (kimi@, moon@)",
  },

  // ── GLM / Zhipu (OpenAI-compatible) ────────────────────────────────
  {
    createHandler: glmHandler,
    tier: "native",
    name: "glm",
    displayName: "GLM",
    transport: "openai",
    tokenStrategy: "delta-aware",
    // api.z.ai is the international mirror — same models, same auth,
    // dramatically better reachability from outside CN than open.bigmodel.cn.
    baseUrl: "https://api.z.ai",
    baseUrlEnvVars: ["ZHIPU_BASE_URL", "GLM_BASE_URL"],
    apiPath: "/api/paas/v4/chat/completions",
    modelDiscovery: { path: "/api/paas/v4/models", format: "openai-models-list" },
    apiKeyEnvVar: "ZHIPU_API_KEY",
    apiKeyAliases: ["GLM_API_KEY"],
    apiKeyDescription: "GLM/Zhipu API Key",
    apiKeyUrl: "https://z.ai/manage-apikey/apikey-list",
    shortcuts: ["glm", "zhipu"],
    shortestPrefix: "glm",
    legacyPrefixes: [
      { prefix: "glm/", stripPrefix: true },
      { prefix: "zhipu/", stripPrefix: true },
    ],
    nativeModelPatterns: [
      { pattern: /^zhipu\//i },
      { pattern: /^glm-/i },
      { pattern: /^chatglm-/i },
    ],
    isDirectApi: true,
    description: "GLM API (glm@, zhipu@)",
  },

  // ── GLM Coding Plan ────────────────────────────────────────────────
  {
    createHandler: glmHandler,
    tier: "subscription",
    name: "glm-coding",
    displayName: "GLM Coding",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.z.ai",
    apiPath: "/api/coding/paas/v4/chat/completions",
    modelDiscovery: { path: "/api/coding/paas/v4/models", format: "openai-models-list" },
    apiKeyEnvVar: "GLM_CODING_API_KEY",
    apiKeyAliases: ["ZAI_CODING_API_KEY"],
    apiKeyDescription: "GLM Coding Plan API Key",
    apiKeyUrl: "https://z.ai/subscribe",
    shortcuts: ["gc"],
    shortestPrefix: "gc",
    legacyPrefixes: [{ prefix: "gc/", stripPrefix: true }],
    isDirectApi: true,
    description: "GLM Coding Plan (gc@)",
  },

  // ── Z.AI (Anthropic-compatible GLM API) ────────────────────────────
  {
    createHandler: anthropicCompatHandler,
    tier: "native",
    name: "z-ai",
    displayName: "Z.AI",
    transport: "anthropic",
    baseUrl: "https://api.z.ai",
    baseUrlEnvVars: ["ZAI_BASE_URL"],
    apiPath: "/api/anthropic/v1/messages",
    apiKeyEnvVar: "ZAI_API_KEY",
    apiKeyDescription: "Z.AI API Key",
    apiKeyUrl: "https://z.ai/manage-apikey/apikey-list",
    // Canonical name is "z-ai" (matches the Firebase catalog slug). Bare "zai"
    // stays as an input alias for existing `zai@...` commands.
    shortcuts: ["z-ai", "zai"],
    shortestPrefix: "z-ai",
    legacyPrefixes: [{ prefix: "zai/", stripPrefix: true }],
    nativeModelPatterns: [{ pattern: /^z-ai\//i }, { pattern: /^zai\//i }],
    isDirectApi: true,
    description: "Z.AI API (z-ai@)",
  },

  // ── OllamaCloud ────────────────────────────────────────────────────
  {
    createHandler: ollamaCloudHandler,
    tier: "gateway",
    name: "ollamacloud",
    displayName: "OllamaCloud",
    transport: "ollamacloud",
    tokenStrategy: "accumulate-both",
    baseUrl: "https://ollama.com",
    baseUrlEnvVars: ["OLLAMACLOUD_BASE_URL"],
    apiPath: "/api/chat",
    apiKeyEnvVar: "OLLAMA_API_KEY",
    apiKeyDescription: "OllamaCloud API Key",
    apiKeyUrl: "https://ollama.com/settings/keys",
    shortcuts: ["oc", "llama", "lc"],
    shortestPrefix: "oc",
    legacyPrefixes: [{ prefix: "oc/", stripPrefix: true }],
    nativeModelPatterns: [
      { pattern: /^ollamacloud\//i },
      { pattern: /^meta-llama\//i },
      { pattern: /^llama-/i },
      { pattern: /^llama3/i },
    ],
    isDirectApi: true,
    description: "Cloud Ollama (oc@, llama@)",
  },

  // ── OpenCode Zen ───────────────────────────────────────────────────
  {
    createHandler: openCodeZenHandler,
    tier: "gateway",
    name: "opencode-zen",
    displayName: "OpenCode Zen",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://opencode.ai/zen",
    baseUrlEnvVars: ["OPENCODE_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "OPENCODE_API_KEY",
    apiKeyDescription: "OpenCode Zen API Key (Console > Settings > Service accounts)",
    apiKeyUrl: "https://opencode.ai/console",
    // publicKeyFallback REMOVED (was `"public"`).
    //
    // It sent the literal string "public" as the bearer token on the theory that
    // Zen's free tier accepts a shared sentinel. Measured 2026-08-22: the
    // endpoint answers `401 — Missing API key`. Whether it ever worked or was
    // withdrawn, it does not work now.
    //
    // Leaving it in was worse than a dead credential, because `isAvailable()`
    // returns TRUE on the mere presence of a publicKeyFallback without issuing a
    // request — so the provider advertised itself as Ready, sorted above the
    // "not configured" divider, and only revealed the 401 when someone pressed
    // `t`. A row that asserts readiness it has never verified is a worse defect
    // than a row that admits it has no key.
    //
    // It also violated the catalog's own rule (CLAUDE.md): never hardcode a
    // value discovered from a vendor — a default is a rule, not a pinned id.
    //
    // Zen remains reachable with a real OPENCODE_API_KEY, and `zengo@`
    // (opencode-zen-go) is unaffected. If Zen documents a genuine keyless tier
    // again, the right shape is live discovery, not another literal.
    shortcuts: ["zen"],
    shortestPrefix: "zen",
    legacyPrefixes: [{ prefix: "zen/", stripPrefix: true }],
    isDirectApi: true,
    description: "OpenCode Zen (zen@)",
  },

  // ── OpenCode Zen Go (lite plan) ────────────────────────────────────
  {
    createHandler: openCodeZenHandler,
    tier: "subscription",
    name: "opencode-zen-go",
    displayName: "OpenCode Zen Go",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://opencode.ai/zen/go",
    baseUrlEnvVars: ["OPENCODE_GO_BASE_URL"],
    apiPath: "/v1/chat/completions",
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    // Zen Go is a separate paid tier from the METERED Zen plan. This block used
    // to claim "keys for one tier are not accepted by the other (401)" and kept
    // `apiKeyAliases: ["OPENCODE_API_KEY"]` — the metered Zen key — on the
    // strength of it.
    //
    // ("the free Zen plan" is what it also said. Zen's keyless tier is dead —
    // measured 401, see the publicKeyFallback removal ~40 lines above — so Zen is
    // the metered tier and calling it free contradicted its own file.)
    //
    // THE 401 CLAIM IS FALSE. Measured 2026-09-02 on `minimax-m3`, a model BOTH
    // tiers serve, one POST to chat/completions per row
    // (ai-docs/reports/data/measurements-20260902.txt):
    //
    //   CONTROL  Zen Go key -> https://opencode.ai/zen/go/v1/chat/completions -> 200
    //   CROSS    Zen Go key -> https://opencode.ai/zen/v1/chat/completions    -> 200
    //   BOGUS    fake key   -> https://opencode.ai/zen/v1/chat/completions    -> 401
    //                         {"type":"error","error":{"type":"AuthError",…}}
    //
    // The bogus row is what makes the cross-tier 200 mean something: that endpoint
    // does authenticate, so it ACCEPTED the other tier's key rather than waving
    // everything through. The two answered with different response-id shapes
    // (`06e71dee…` vs `chatcmpl-76bdafac…`), i.e. different upstreams honouring one
    // key. So keys are NOT tier-locked in the direction that was measurable here,
    // and the symmetric claim the alias rested on is disproven.
    //
    // WHAT IS NOT MEASURED, stated plainly: a ZEN-TIER key against /zen/go. No
    // Zen-tier key exists on this machine. That is the direction that costs money —
    // `opencode-zen-go` is classified flat-rate BY NAME
    // (remote-provider-types.ts SUBSCRIPTION_PROVIDERS), so a Zen-tier key
    // satisfying `zgo@` would be metered usage reported as SUB and $0.
    //
    // Hence the alias is GONE (2026-09-02). It was justified by a claim now known
    // to be false, and it made that money-losing case reachable with no evidence
    // that the endpoint would refuse it. `zgo@` now requires its own key; a user
    // holding only OPENCODE_API_KEY gets `siblingKeyEnvVars` named in the
    // missing-credential sentence instead of a silent `SUB` label.
    apiKeyEnvVar: "OPENCODE_GO_API_KEY",
    siblingKeyEnvVars: ["OPENCODE_API_KEY"],
    apiKeyDescription:
      "OpenCode Zen Go (Lite Plan) API Key (Console > Settings > Service accounts)",
    apiKeyUrl: "https://opencode.ai/console",
    shortcuts: ["zengo", "zgo"],
    shortestPrefix: "zengo",
    legacyPrefixes: [
      { prefix: "zengo/", stripPrefix: true },
      { prefix: "zgo/", stripPrefix: true },
    ],
    isDirectApi: true,
    description: "OpenCode Zen Go plan (zengo@)",
  },

  // ── Vertex AI ──────────────────────────────────────────────────────
  {
    createHandler: vertexHandler,
    // Account-SELECTED but METERED: which publishers a project may call is a GCP
    // fact the catalog cannot know (it sits in the probe map as
    // `client_model_selection_required`, beside the flat-rate four), yet every
    // call is billed per token. `dynamic-subscription` would say the opposite
    // about money, so the tier follows the BILLING and the selection stays a
    // fact about entitlement, settled by the availability filter. Consequence,
    // stated so it is not mistaken for an oversight: Vertex gets no namespace
    // claim, so a model only Vertex serves stays reachable by `v@model`.
    tier: "gateway",
    name: "vertex",
    displayName: "Vertex AI",
    transport: "vertex",
    baseUrl: "",
    // The transport composes the endpoint from project + location + publisher,
    // so the empty baseUrl above is the finished answer. Without this the
    // registry filter drops Vertex entirely (see `buildsOwnEndpoint`).
    buildsOwnEndpoint: true,
    apiPath: "",
    // Not an API key: the project ID, paired with Application Default
    // Credentials. It stays on `apiKeyEnvVar` because that is what makes the
    // credential authority resolve Vertex at all, and what names the remedy in
    // "no credential" messages. VERTEX_API_KEY (Express) was REMOVED from
    // `apiKeyAliases` on 2026-09-21 along with the mode itself. Claudish also
    // resolves the project from the ADC file and `gcloud config` — see
    // `resolveVertexConfig` — so an unset VERTEX_PROJECT is not fatal.
    apiKeyEnvVar: "VERTEX_PROJECT",
    apiKeyDescription: "Vertex AI project ID (with Application Default Credentials)",
    apiKeyUrl: "https://console.cloud.google.com/vertex-ai",
    shortcuts: ["v", "vertex"],
    shortestPrefix: "v",
    legacyPrefixes: [
      { prefix: "v/", stripPrefix: true },
      { prefix: "vertex/", stripPrefix: true },
    ],
    isDirectApi: true,
    description: "Vertex AI on Application Default Credentials (v@, vertex@)",
  },

  // ── LiteLLM ────────────────────────────────────────────────────────
  {
    createHandler: litellmHandler,
    // A proxy in front of many vendors, whose own URL the user supplies: a
    // gateway in every sense the tier means, even when the instance is theirs.
    tier: "gateway",
    name: "litellm",
    displayName: "LiteLLM",
    transport: "litellm",
    baseUrl: "",
    baseUrlEnvVars: ["LITELLM_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "LITELLM_API_KEY",
    apiKeyDescription: "LiteLLM API Key",
    apiKeyUrl: "https://docs.litellm.ai/",
    shortcuts: ["litellm", "ll"],
    shortestPrefix: "ll",
    legacyPrefixes: [
      { prefix: "litellm/", stripPrefix: true },
      { prefix: "ll/", stripPrefix: true },
    ],
    isDirectApi: true,
    description: "LiteLLM proxy (ll@, litellm@)",
  },

  // ── Poe ────────────────────────────────────────────────────────────
  {
    createHandler: poeHandler,
    tier: "gateway",
    name: "poe",
    displayName: "Poe",
    transport: "poe",
    baseUrl: "https://api.poe.com",
    apiPath: "/v1/chat/completions",
    // The catalog has no verified probe pick for Poe, so the account's own list
    // is the only source of one. Measured 2026-09-19: /v1/models answers 200
    // with 341 models.
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    apiKeyEnvVar: "POE_API_KEY",
    apiKeyDescription: "Poe API Key",
    apiKeyUrl: "https://poe.com/api_key",
    shortcuts: ["poe"],
    shortestPrefix: "poe",
    legacyPrefixes: [],
    nativeModelPatterns: [{ pattern: /^poe:/i }],
    isDirectApi: true,
    description: "Poe API (poe@)",
  },

  // ── Ollama (local) ─────────────────────────────────────────────────
  //
  // THE FOUR LOCAL PROVIDERS ARE `native`, and the tier is inert for them.
  //
  // Inert first, because that is what makes the choice cheap: a local server is
  // bound to no catalog route (`ollama/cloud` belongs to `ollamacloud`, not to
  // this entry), so no catalog connection can ever name one, and only a
  // `dynamic-subscription` may claim a namespace — so no local provider can be
  // gathered as a remote candidate at all. Local models reach a request the way
  // they always have: an explicit `[email protected]`, or the local-provider path.
  //
  // `native` among the four remaining values because the request goes to the
  // endpoint that runs the model, with no reseller and no plan in between —
  // which is what `native` means minus the metering. `gateway` would be false
  // (nothing is resold, nothing is billed) and `subscription` would be worse: it
  // claims a plan with a published membership, and would sort a local server
  // ahead of a subscription the user actually pays for if the tier ever stopped
  // being inert.
  {
    createHandler: noHandler(
      "local",
      "Built by the local-provider path; never reaches direct-api."
    ),
    tier: "native",
    name: "ollama",
    displayName: "Ollama",
    transport: "local",
    baseUrl: "http://localhost:11434",
    baseUrlEnvVars: ["OLLAMA_BASE_URL", "OLLAMA_HOST"],
    apiPath: "/api/chat",
    // Optional: Ollama supports auth when exposed over the network (e.g.
    // via reverse proxy). Empty by default; user sets OLLAMA_API_KEY if
    // their deployment requires it.
    apiKeyEnvVar: "OLLAMA_API_KEY",
    apiKeyDescription: "Ollama API Key (optional — leave blank for localhost)",
    apiKeyUrl: "",
    shortcuts: ["ollama"],
    shortestPrefix: "ollama",
    legacyPrefixes: [
      { prefix: "ollama/", stripPrefix: true },
      { prefix: "ollama:", stripPrefix: true },
    ],
    isLocal: true,
    // The daemon knows exactly which models are pulled; nothing else can. Path
    // is unused by the `ollama-tags` fetcher, which owns its own endpoint.
    modelDiscovery: { path: "/api/tags", format: "ollama-tags" },
    description: "Local Ollama (ollama@)",
  },

  // ── LM Studio (local) ──────────────────────────────────────────────
  {
    createHandler: noHandler(
      "local",
      "Built by the local-provider path; never reaches direct-api."
    ),
    tier: "native",
    name: "lmstudio",
    displayName: "LM Studio",
    transport: "local",
    baseUrl: "http://localhost:1234",
    baseUrlEnvVars: ["LMSTUDIO_BASE_URL"],
    apiPath: "/v1/chat/completions",
    // Optional: LM Studio supports API key auth when "Reachable on local
    // network" is enabled in its server settings. Empty by default; user
    // sets LMSTUDIO_API_KEY if their server requires it.
    apiKeyEnvVar: "LMSTUDIO_API_KEY",
    apiKeyDescription: "LM Studio API Key (optional — leave blank for localhost)",
    apiKeyUrl: "https://lmstudio.ai/docs/developer/core/server",
    shortcuts: ["lms", "lmstudio", "mlstudio"],
    shortestPrefix: "lms",
    legacyPrefixes: [
      { prefix: "lmstudio/", stripPrefix: true },
      { prefix: "lmstudio:", stripPrefix: true },
      { prefix: "mlstudio/", stripPrefix: true },
      { prefix: "mlstudio:", stripPrefix: true },
    ],
    isLocal: true,
    // LM Studio serves an OpenAI-compatible list of the models it has loaded.
    // Previously unlisted, so the picker made users type a name from memory.
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    description: "Local LM Studio (lms@)",
  },

  // ── vLLM (local) ───────────────────────────────────────────────────
  {
    createHandler: noHandler(
      "local",
      "Built by the local-provider path; never reaches direct-api."
    ),
    tier: "native",
    name: "vllm",
    displayName: "vLLM",
    transport: "local",
    baseUrl: "http://localhost:8000",
    baseUrlEnvVars: ["VLLM_BASE_URL"],
    apiPath: "/v1/chat/completions",
    // Optional: vLLM accepts an API key when started with --api-key.
    apiKeyEnvVar: "VLLM_API_KEY",
    apiKeyDescription: "vLLM API Key (optional — set if --api-key is configured)",
    apiKeyUrl: "",
    shortcuts: ["vllm"],
    shortestPrefix: "vllm",
    legacyPrefixes: [
      { prefix: "vllm/", stripPrefix: true },
      { prefix: "vllm:", stripPrefix: true },
    ],
    isLocal: true,
    description: "Local vLLM (vllm@)",
  },

  // ── MLX (local) ────────────────────────────────────────────────────
  {
    createHandler: noHandler(
      "local",
      "Built by the local-provider path; never reaches direct-api."
    ),
    tier: "native",
    name: "mlx",
    displayName: "MLX",
    transport: "local",
    baseUrl: "http://localhost:8080",
    baseUrlEnvVars: ["MLX_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "MLX_API_KEY",
    apiKeyDescription: "MLX API Key (optional)",
    apiKeyUrl: "",
    shortcuts: ["mlx"],
    shortestPrefix: "mlx",
    legacyPrefixes: [
      { prefix: "mlx/", stripPrefix: true },
      { prefix: "mlx:", stripPrefix: true },
    ],
    isLocal: true,
    description: "Local MLX (mlx@)",
  },

  // ── DeepSeek (OpenAI-compatible direct API) ─────────────────────────
  {
    createHandler: openaiHandler,
    tier: "native",
    name: "deepseek",
    displayName: "DeepSeek",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.deepseek.com",
    baseUrlEnvVars: ["DEEPSEEK_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "DEEPSEEK_API_KEY",
    apiKeyDescription: "DeepSeek API Key",
    apiKeyUrl: "https://platform.deepseek.com/api_keys",
    shortcuts: ["ds"],
    shortestPrefix: "ds",
    legacyPrefixes: [{ prefix: "ds/", stripPrefix: true }],
    nativeModelPatterns: [{ pattern: /^deepseek\//i }, { pattern: /^deepseek-/i }],
    isDirectApi: true,
    description: "DeepSeek API (ds@)",
  },

  // ── Meta (native API, metered) ─────────────────────────────────────
  // Meta's own model API at api.meta.ai, billed per token on META_API_KEY. Not
  // the Muse Code subscription, which is a separate claudish provider with its
  // own login. Requests are built from the catalog's `meta/direct-api`
  // connections (their wire is `responses`); `apiPath` is only the
  // off-catalog default.
  //
  // NO `modelDiscovery`: `/v1/models` returns ids only, and a successful
  // discovery replaces the catalog rows in the picker, which carry the
  // windows, prices and modalities. The picker reads the catalog slug `meta`.
  {
    createHandler: openaiHandler,
    tier: "native",
    name: "meta",
    displayName: "Meta",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.meta.ai",
    baseUrlEnvVars: ["META_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "META_API_KEY",
    apiKeyDescription: "Meta Model API key",
    apiKeyUrl: "https://dev.meta.ai",
    shortcuts: ["meta"],
    shortestPrefix: "meta",
    legacyPrefixes: [],
    // parseModelSpec auto-detection only: a bare `muse-*` name is still routed
    // by the catalog (`route()`), never pinned to this provider.
    nativeModelPatterns: [{ pattern: /^muse-/i }],
    isDirectApi: true,
    description: "Meta Model API (meta@)",
  },

  // ── Mistral (OpenAI-compatible direct API) ─────────────────────────
  // The catalog carries 13 mistralai-served models; 5 of them
  // (labs-leanstral-1-5, ministral-3-3b/3-8b-instruct, mistral-medium-3.5,
  // mistral-small-4.0-2603) are served by NO other provider claudish can
  // reach, so without this they are simply unroutable.
  //
  // NOTE on ids: Mistral's own wire ids are floating aliases
  // (`mistral-large-latest`, `ministral-8b-latest`) that silently move to a new
  // model on each release. The catalog carries them as `aggregators[].externalId`
  // against pinned catalog ids (`mistral-large-2512`), and the generic
  // externalId resolution translates one to the other — so a user typing the
  // pinned id still reaches the alias, and no per-provider code is needed here.
  {
    createHandler: openaiHandler,
    tier: "native",
    name: "mistralai",
    displayName: "Mistral",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.mistral.ai",
    baseUrlEnvVars: ["MISTRAL_BASE_URL"],
    apiPath: "/v1/chat/completions",
    // Without this, Test All had ONE candidate and no way past it. The catalog's
    // probe pick is `labs-leanstral-1-5`, and a Labs model answers `403 "… is a
    // Labs model. To use Labs models, an admin must enable them in your
    // organization settings"` for any account that has not enabled Labs
    // (measured 2026-09-19). The account's own list answers 200 with 53 models,
    // only 2 of them Labs, so endpoint discovery can walk to a model the account
    // can actually call.
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    apiKeyEnvVar: "MISTRAL_API_KEY",
    apiKeyDescription: "Mistral API Key",
    apiKeyUrl: "https://console.mistral.ai/api-keys",
    shortcuts: ["mistral"],
    shortestPrefix: "mistral",
    legacyPrefixes: [{ prefix: "mistral/", stripPrefix: true }],
    // `ministral-` and `codestral-` are distinct product lines, not prefixes of
    // `mistral-`, so each needs its own pattern. Anchored to avoid catching
    // unrelated ids that merely contain the substring.
    nativeModelPatterns: [
      { pattern: /^mistralai\//i },
      { pattern: /^mistral-/i },
      { pattern: /^ministral-/i },
      { pattern: /^codestral-/i },
    ],
    isDirectApi: true,
    description: "Direct Mistral API (mistral@)",
  },

  // ── Sakana Fugu (OpenAI-compatible direct API / token plan) ────────
  {
    createHandler: openaiHandler,
    tier: "native",
    name: "sakana",
    displayName: "Sakana Fugu",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.sakana.ai",
    baseUrlEnvVars: ["SAKANA_BASE_URL"],
    apiPath: "/v1/chat/completions",
    apiKeyEnvVar: "SAKANA_API_KEY",
    apiKeyDescription: "Sakana Fugu API Key",
    apiKeyUrl: "https://console.sakana.ai/get-started",
    shortcuts: ["sakana", "fugu"],
    shortestPrefix: "fugu",
    legacyPrefixes: [
      { prefix: "sakana/", stripPrefix: true },
      { prefix: "fugu/", stripPrefix: true },
    ],
    nativeModelPatterns: [{ pattern: /^fugu/i }, { pattern: /^sakana\//i }],
    isDirectApi: true,
    description: "Sakana Fugu API (sakana@, fugu@)",
  },

  // ── Sakana Fugu Subscription Plan ──────────────────────────────────
  // A general-purpose subscription (NOT coding-specific) — usable for any task.
  // Same endpoint as the API/token plan (api.sakana.ai — the only endpoint
  // Sakana exposes), but the BILLING MODE is fixed at KEY CREATION: the Sakana
  // console lets you mint a key as either a "subscription" key or an "API usage"
  // (pay-as-you-go) key. They are GENUINELY DIFFERENT keys — a PAYG key draws
  // from prepaid credits, a subscription key from the monthly plan allowance —
  // so this provider has its OWN env var (SAKANA_SUBSCRIPTION_API_KEY) with NO
  // alias back to SAKANA_API_KEY. Aliasing caused sc@ to fall back to the PAYG
  // key and bill prepaid credits ("Prepaid credit balance is exhausted") despite
  // an active subscription. (Sakana's public API reference shows only one
  // SAKANA_API_KEY because the wire is identical; the subscription-vs-API
  // distinction lives in the key, set at creation in the console.)
  {
    createHandler: openaiHandler,
    // Flat-rate, but `sakana/fugu-subscription` publishes no connection — it sits
    // in the probe map as `client_model_selection_required`, so what the plan
    // serves is settled by this key's own `/v1/models`, not by the catalog.
    tier: "dynamic-subscription",
    name: "sakana-subscription",
    displayName: "Sakana Fugu Subscription",
    transport: "openai",
    tokenStrategy: "delta-aware",
    baseUrl: "https://api.sakana.ai",
    baseUrlEnvVars: ["SAKANA_BASE_URL"],
    apiPath: "/v1/chat/completions",
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    // Primary env var matches Sakana's own term ("subscription"). The old
    // SAKANA_CODING_API_KEY is kept only as a back-compat alias. NEITHER aliases
    // the API-usage SAKANA_API_KEY — that's the PAYG key and would bill prepaid
    // credits.
    apiKeyEnvVar: "SAKANA_SUBSCRIPTION_API_KEY",
    apiKeyAliases: ["SAKANA_CODING_API_KEY"],
    apiKeyDescription: "Sakana Fugu Subscription API Key",
    apiKeyUrl: "https://console.sakana.ai/get-started",
    shortcuts: ["sc"],
    shortestPrefix: "sc",
    legacyPrefixes: [{ prefix: "sc/", stripPrefix: true }],
    // THE NAMESPACE CLAIM. `sakana` above declares the same `/^fugu/i` (plus
    // `/^sakana\//i`, which `parseModelSpec` strips to a bare `fugu…` before
    // routing ever sees it) and is defined FIRST, so auto-detection is
    // unchanged. This claim is what lets `route-candidates.ts` emit a
    // subscription candidate at all: `sakana/fugu-subscription` is
    // `client_model_selection_required` in the probe map with ZERO
    // `aggregators[]` rows, and without it the 8 Fugu models a plan serves
    // (measured on generation g-20260921062451697-f490edba) would silently move
    // onto the metered `sakana` key — which draws PREPAID CREDITS, a different
    // wallet from the subscription, and has already billed a user once.
    //
    // `/^fugu/i` rather than `/^fugu-/i`: the bare id `fugu` is a real model, so
    // a hyphen-anchored rule would miss the family's own head.
    nativeModelPatterns: [{ pattern: /^fugu/i }],
    isDirectApi: true,
    description: "Sakana Fugu Subscription (sc@)",
  },

  // ── Alibaba Token Plan (must be before Qwen — /^qwen/i would swallow it) ──
  // Alibaba Token Plan: subscription credits on its own host and credential.
  {
    createHandler: anthropicCompatHandler,
    tier: "subscription",
    name: "qwen-token-plan",
    displayName: "Alibaba Token Plan",
    transport: "anthropic",
    baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com",
    baseUrlEnvVars: ["QWEN_TOKEN_PLAN_BASE_URL"],
    apiPath: "/apps/anthropic/v1/messages",
    apiKeyEnvVar: "QWEN_TOKEN_PLAN_API_KEY",
    siblingKeyEnvVars: ["QWEN_CODING_PLAN_API_KEY", "DASHSCOPE_API_KEY"],
    apiKeyDescription: "Alibaba Model Studio Token Plan API Key (subscription credits)",
    apiKeyUrl: "https://docs.qwencloud.com/token-plan/overview",
    authScheme: "bearer",
    shortcuts: ["qtoken"],
    shortestPrefix: "qtoken",
    legacyPrefixes: [],
    nativeModelPatterns: [{ pattern: /^qwen3\.\d/i }],
    modelDiscovery: { path: "/compatible-mode/v1/models", format: "openai-models-list" },
    isDirectApi: true,
    description: "Alibaba Token Plan subscription (qtoken@)",
  },

  // Alibaba Coding Plan: request-based subscription on its own host and credential.
  {
    createHandler: anthropicCompatHandler,
    tier: "subscription",
    name: "qwen-coding",
    displayName: "Alibaba Coding Plan",
    transport: "anthropic",
    baseUrl: "https://coding-intl.dashscope.aliyuncs.com",
    baseUrlEnvVars: ["QWEN_CODING_PLAN_BASE_URL"],
    apiPath: "/apps/anthropic/v1/messages",
    apiKeyEnvVar: "QWEN_CODING_PLAN_API_KEY",
    siblingKeyEnvVars: ["QWEN_TOKEN_PLAN_API_KEY", "DASHSCOPE_API_KEY"],
    apiKeyDescription: "Alibaba Model Studio Coding Plan API Key (subscription requests)",
    apiKeyUrl: "https://www.alibabacloud.com/help/en/model-studio/coding-plan",
    authScheme: "bearer",
    shortcuts: ["qcode"],
    shortestPrefix: "qcode",
    legacyPrefixes: [],
    modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
    isDirectApi: true,
    description: "Alibaba Coding Plan subscription (qcode@)",
  },

  // Alibaba PAYG: token-metered access on its own host and credential.
  {
    createHandler: anthropicCompatHandler,
    tier: "native",
    name: "qwen-payg",
    displayName: "Alibaba PAYG",
    transport: "anthropic",
    baseUrl: "https://dashscope-intl.aliyuncs.com",
    baseUrlEnvVars: ["DASHSCOPE_BASE_URL"],
    apiPath: "/apps/anthropic/v1/messages",
    apiKeyEnvVar: "DASHSCOPE_API_KEY",
    siblingKeyEnvVars: ["QWEN_TOKEN_PLAN_API_KEY", "QWEN_CODING_PLAN_API_KEY"],
    apiKeyDescription: "Alibaba Model Studio PAYG API Key",
    apiKeyUrl: "https://www.alibabacloud.com/help/en/model-studio/get-api-key",
    authScheme: "bearer",
    shortcuts: ["qpay"],
    shortestPrefix: "qpay",
    legacyPrefixes: [],
    modelDiscovery: { path: "/compatible-mode/v1/models", format: "openai-models-list" },
    isDirectApi: true,
    description: "Alibaba Model Studio PAYG (qpay@)",
  },

  // ── Qwen (auto-routed, no direct API) ──────────────────────────────
  {
    // VIRTUAL, and it must say so: no baseUrl, no apiPath, no apiKeyEnvVar.
    // The entry exists so a bare `qwen*` name has a provider to be steered
    // FROM; `qwen-payg` is what actually calls dashscope.
    //
    // It used to carry `openaiHandler` and a comment arguing it was unreachable
    // anyway, because `providerForCatalogRoute` returned only the FIRST provider
    // bound to `qwen/dashscope-direct` and `qwen-payg` is the earlier key. v10.0.0
    // made the gatherer take ALL of them (now `routingProvidersForRoute`) — the
    // z-ai/glm key-silo fix — and deleted the premise. This became a gathered
    // candidate, so `--probe qwen3.8-max` printed a `Qwen ✗ key missing` hop and
    // sent the reader looking for a key that no environment variable can hold.
    // `route()` never yielded it (the credential filter drops it), so the damage
    // was confined to the display; `reason: "virtual"` is what keeps it that way.
    createHandler: noHandler(
      "virtual",
      "No baseUrl. Exists only so nativeModelPatterns can steer a bare qwen* name; qwen-payg serves dashscope."
    ),
    // The vendor's own namespace, so `native`.
    tier: "native",
    name: "qwen",
    displayName: "Qwen",
    transport: "openai",
    baseUrl: "",
    apiPath: "",
    apiKeyEnvVar: "",
    apiKeyDescription: "Qwen (auto-routed via OpenRouter)",
    apiKeyUrl: "",
    shortcuts: [],
    shortestPrefix: "qwen",
    legacyPrefixes: [],
    nativeModelPatterns: [{ pattern: /^qwen/i }],
    description: "Qwen (auto-routed via OpenRouter)",
  },

  // ── Native Anthropic (Claude Code auth) ────────────────────────────
  {
    createHandler: noHandler(
      "virtual",
      "No baseUrl. Exists only so nativeModelPatterns can steer a bare claude-* name to the native path."
    ),
    // The route IS the Claude Code subscription — the catalog's
    // `anthropic/claude-code-subscription` profile — so `subscription` is the
    // only honest tier for it. Two things it does NOT mean, both of which this
    // project has been bitten by: it is not a billing statement (an explicit
    // ANTHROPIC_API_KEY reaches this same name and is metered, which is why
    // deriving `SUBSCRIPTION_PROVIDERS` from tier must exclude it alongside
    // `openai-codex`), and it is not a claim that this provider is routable —
    // `nativeRouteFor()` must intercept a bare Claude name BEFORE `route()`,
    // because there is no credential store here for the credential filter to
    // consult and the chain would degrade to OpenRouter.
    tier: "subscription",
    name: "native-anthropic",
    displayName: "Anthropic (Native)",
    transport: "anthropic",
    baseUrl: "",
    apiPath: "",
    apiKeyEnvVar: "",
    apiKeyDescription: "Anthropic (Native Claude Code auth)",
    apiKeyUrl: "",
    shortcuts: [],
    shortestPrefix: "",
    legacyPrefixes: [],
    nativeModelPatterns: [{ pattern: /^anthropic\//i }, { pattern: /^claude-/i }],
    description: "Native Claude Code auth",
  },
];

// ---------------------------------------------------------------------------
// Lazy-cached derived accessors
// ---------------------------------------------------------------------------

let _shortcutsCache: Record<string, string> | null = null;
let _legacyPrefixCache: Array<{
  prefix: string;
  provider: string;
  stripPrefix: boolean;
}> | null = null;
let _nativeModelPatternsCache: Array<{ pattern: RegExp; provider: string }> | null = null;
let _providerByNameCache: Map<string, ProviderDefinition> | null = null;
let _directApiProvidersCache: Set<string> | null = null;
let _localProvidersCache: Set<string> | null = null;

function ensureProviderByNameCache(): Map<string, ProviderDefinition> {
  if (!_providerByNameCache) {
    _providerByNameCache = new Map();
    for (const def of BUILTIN_PROVIDERS) {
      _providerByNameCache.set(def.name, def);
    }
  }
  return _providerByNameCache;
}

/**
 * Get the shortcuts → canonical provider name mapping.
 * Replaces PROVIDER_SHORTCUTS in model-parser.ts.
 *
 * Builtin shortcuts are cached on first access. Runtime providers merge their
 * shortcuts fresh each call (the registry is small and startup-only, so the
 * extra allocation is negligible and avoids cache-invalidation complexity).
 */
export function getShortcuts(): Record<string, string> {
  if (!_shortcutsCache) {
    _shortcutsCache = {};
    for (const def of BUILTIN_PROVIDERS) {
      for (const shortcut of def.shortcuts) {
        _shortcutsCache[shortcut] = def.name;
      }
    }
  }
  const runtime = getRuntimeProviders();
  if (runtime.size === 0) return _shortcutsCache;
  const merged: Record<string, string> = { ..._shortcutsCache };
  for (const def of runtime.values()) {
    for (const shortcut of def.shortcuts) {
      merged[shortcut] = def.name;
    }
  }
  return merged;
}

/**
 * Get legacy prefix patterns for backwards compatibility.
 * Replaces LEGACY_PREFIX_PATTERNS in model-parser.ts.
 */
export function getLegacyPrefixPatterns(): Array<{
  prefix: string;
  provider: string;
  stripPrefix: boolean;
}> {
  if (!_legacyPrefixCache) {
    _legacyPrefixCache = [];
    for (const def of BUILTIN_PROVIDERS) {
      for (const lp of def.legacyPrefixes) {
        _legacyPrefixCache.push({
          prefix: lp.prefix,
          provider: def.name,
          stripPrefix: lp.stripPrefix,
        });
      }
    }
  }
  return _legacyPrefixCache;
}

/**
 * Get native model patterns for auto-detection.
 * Replaces NATIVE_MODEL_PATTERNS in model-parser.ts.
 *
 * Order follows the definition order in BUILTIN_PROVIDERS.
 * kimi-coding's pattern (kimi-for-coding$) comes before kimi's (kimi-*) because
 * kimi-coding is defined earlier in BUILTIN_PROVIDERS.
 */
export function getNativeModelPatterns(): Array<{ pattern: RegExp; provider: string }> {
  if (!_nativeModelPatternsCache) {
    _nativeModelPatternsCache = [];
    for (const def of BUILTIN_PROVIDERS) {
      if (def.nativeModelPatterns) {
        for (const np of def.nativeModelPatterns) {
          _nativeModelPatternsCache.push({
            pattern: np.pattern,
            provider: def.name,
          });
        }
      }
    }
  }
  return _nativeModelPatternsCache;
}

/**
 * Get a provider definition by canonical name.
 * Consults the builtin cache first, then the runtime registry for custom
 * endpoints registered at startup via `custom-endpoints-loader.ts`.
 */
export function getProviderByName(name: string): ProviderDefinition | undefined {
  const builtin = ensureProviderByNameCache().get(name);
  if (builtin) return builtin;
  return getRuntimeProviders().get(name);
}

/**
 * Get API key info for a provider.
 * Replaces API_KEY_INFO in provider-resolver.ts.
 */
export function getApiKeyInfo(providerName: string): {
  envVar: string;
  description: string;
  url: string;
  aliases?: string[];
  oauthFallback?: string;
} | null {
  const def = getProviderByName(providerName);
  if (!def) return null;
  return {
    envVar: def.apiKeyEnvVar,
    description: def.apiKeyDescription,
    url: def.apiKeyUrl,
    aliases: def.apiKeyAliases,
    oauthFallback: def.oauthFallback,
  };
}

/**
 * The one-sentence remedy for "this provider produced no handler".
 *
 * Derived entirely from the provider DEFINITION — runtime-aware, so a bundled
 * or user-declared endpoint gets the same treatment as a builtin — rather than
 * from the hand-maintained builtin-only `API_KEY_MAP`, which is the second-table
 * coupling that produces silent mis-routes elsewhere in this codebase.
 *
 * Three shapes, because "no credential" has three different causes and naming
 * the wrong one sends the user somewhere expensive:
 *
 * 1. **A LOCAL provider** (`ollama`, `lmstudio`, `vllm`, `mlx`) is not gated on
 *    a key at all. `LocalCredentialProvider.isAvailable()` is literally
 *    `isLocalProviderEnabled(name)` — i.e. `config.localProviders` contains the
 *    name — and its optional bearer token can never block a handler
 *    (`getRequestAuth` returns empty headers when there is none). So the actual
 *    cause is "not enabled in config", and leading with "Set OLLAMA_API_KEY"
 *    names a variable the user almost certainly should not set. The key clause
 *    survives, in parentheses, for the gateway case that really does want one.
 *
 * 2. **A provider with an `oauthFallback`** is DUAL-MODE: `openai-codex` is a
 *    ChatGPT Plus/Pro subscription OR a metered `OPENAI_API_KEY`, `kimi-coding`
 *    a Kimi membership OR a key. Telling a subscriber to go and buy metered API
 *    access is the more expensive of the two asymmetric errors — the same
 *    reasoning that keeps `openai-codex` out of `SUBSCRIPTION_PROVIDERS` — so
 *    the sign-in path is named FIRST and the key path second. The provider NAME
 *    is a valid `claudish login` argument (`auth-commands.ts` `findProvider`
 *    matches on `registryKeys`, which carry the canonical names), so no second
 *    name table is introduced here.
 *
 * 3. Everything else keeps today's text exactly.
 *
 * Orthogonal to all three: a provider declaring `siblingKeyEnvVars` gains one
 * trailing clause naming the same vendor's OTHER key. See that field.
 */
export function describeMissingCredential(providerName: string): string {
  const info = getApiKeyInfo(providerName);
  const keyNames = info?.envVar ? [info.envVar, ...(info.aliases ?? [])].join(" or ") : undefined;
  const signup = info?.url ? ` Get one at ${info.url}.` : "";
  const def = getProviderByName(providerName);
  const sibling = describeSiblingKeys(def);

  if (providerName === "vertex") {
    return (
      `No Google Cloud project for provider "vertex". ${VERTEX_SET_PROJECT_REMEDY}. ` +
      "Application Default Credentials already handles the credential; Vertex takes no API key."
    );
  }

  if (isLocalTransport(providerName)) {
    const where = def ? ` Claudish will use ${getEffectiveBaseUrl(def)}.` : "";
    const keyClause = keyNames
      ? ` (Only set ${keyNames} if your local server requires a bearer token.)`
      : "";
    return (
      `Provider "${providerName}" is a LOCAL server and is not enabled. ` +
      "Enable it in `claudish config` (Providers tab), or add " +
      `"localProviders": ["${providerName}"] to ~/.claudish/config.json.${where}${keyClause}${sibling}`
    );
  }

  if (def?.oauthFallback) {
    const keyClause = keyNames
      ? ` Or set ${keyNames} (env, config, or 1Password import) to use a metered API key instead.${signup}`
      : "";
    return (
      `No credential for provider "${providerName}". Sign in with ` +
      `\`claudish login ${providerName}\` to use your existing subscription.${keyClause}${sibling}`
    );
  }

  return keyNames
    ? `No API key for provider "${providerName}". Set ${keyNames} (env, config, or 1Password import).${signup}${sibling}`
    : `No API key for provider "${providerName}".${sibling}`;
}

/**
 * The trailing clause for a provider that declares `siblingKeyEnvVars`.
 *
 * Empty string for everyone else, so the three sentences above are unchanged for
 * every provider that declares none.
 *
 * The OWNER of each sibling variable is looked up live from the catalog rather
 * than written into the definition beside it. A second spelling of "which
 * provider does OPENCODE_API_KEY belong to" is exactly the two-table coupling
 * that produced the mis-routes this file's other comments record, and the answer
 * is already in the catalog as `apiKeyEnvVar`. A variable no provider claims
 * (a rename, a removal) degrades to the bare name instead of asserting a
 * provider that no longer exists.
 *
 * Exported because the SECOND place a user meets this fact is a 401 — they set
 * the sibling key, and the vendor's other host rejected it with wording that
 * attributes nothing (`invalid access token or token expired`). The recovery
 * hint in `composed-handler.ts` appends this same sentence there, rather than
 * writing a second one, so the "no key" copy and the "wrong key" copy can never
 * disagree about which variable belongs to which plan.
 */
export function describeSiblingKeys(def: ProviderDefinition | undefined): string {
  const vars = def?.siblingKeyEnvVars ?? [];
  if (vars.length === 0) return "";
  const all = getAllProviders();
  const named = vars.map((v) => {
    const owner = all.find((p) => p.name !== def?.name && p.apiKeyEnvVar === v);
    return owner ? `${v} (${owner.name})` : v;
  });
  return ` Note: ${named.join(" or ")} is a DIFFERENT plan's key and is not accepted here.`;
}

/**
 * Get display name for a provider.
 * Replaces PROVIDER_DISPLAY_NAMES in provider-resolver.ts.
 */
export function getDisplayName(providerName: string): string {
  const def = getProviderByName(providerName);
  return def?.displayName || providerName.charAt(0).toUpperCase() + providerName.slice(1);
}

/** Where a base-URL override came from, so a caller can phrase the remedy. */
export interface BaseUrlOverrideCandidate {
  /** The variable / `config.endpoints` key that supplied it. */
  envVar: string;
  /** The raw value, exactly as stored. Not validated and not trimmed. */
  value: string;
  source: "config" | "env";
}

/**
 * Every base-URL override that is present, in precedence order.
 *
 * THE one oracle for "where does this provider actually point". It exists
 * because there were briefly two: `getEffectiveBaseUrl` walked
 * `config.endpoints` → env → default, while the custom-endpoint classifier
 * walked env only. The config TUI's URL editor writes BOTH `setEndpoint()` and
 * `process.env`, so the second oracle looked correct for the rest of the
 * session and diverged only after a restart — at which point the TUI still
 * DISPLAYED the saved private URL while requests went to the bundled public
 * host. UI says private, wire says public, which is the data-egress failure the
 * R12 skip-not-fallback rule exists to prevent, inverted.
 *
 * Returned as a LIST rather than a single winner because the two callers apply
 * different policy to it: `getEffectiveBaseUrl` takes the first and is done,
 * while `classifyEndpointBaseUrl` must skip an unexpanded `${VAR}` placeholder
 * (which means "unset", not "wrong") and continue to the next candidate. A
 * single-winner API would force the placeholder rule to live in one of them
 * only — i.e. two oracles again.
 *
 * Precedence, unchanged: config.endpoints[VAR] for every var in order, then
 * process.env[VAR] for every var in order. So `config.endpoints.OLLAMA_HOST`
 * beats `process.env.LMSTUDIO_BASE_URL` — config wins as a TIER, matching the
 * `apiKeys` rule, not per-variable.
 */
export function baseUrlOverrideCandidates(
  baseUrlEnvVars?: readonly string[]
): BaseUrlOverrideCandidate[] {
  const found: BaseUrlOverrideCandidate[] = [];
  if (!baseUrlEnvVars || baseUrlEnvVars.length === 0) return found;
  // Config wins over env (matches the apiKeys precedence rule).
  for (const envVar of baseUrlEnvVars) {
    const fromConfig = getConfigEndpoint(envVar);
    if (fromConfig) found.push({ envVar, value: fromConfig, source: "config" });
  }
  for (const envVar of baseUrlEnvVars) {
    const value = process.env[envVar];
    if (value) found.push({ envVar, value, source: "env" });
  }
  return found;
}

/**
 * Get the effective base URL for a provider.
 *
 * Resolution precedence (highest to lowest):
 *   1. config.endpoints[envVar] from ~/.claudish/config.json — primary,
 *      TUI-editable, scoped to the user's profile.
 *   2. process.env[envVar] — fallback for CI/scripted environments.
 *   3. def.baseUrl — static default (e.g. http://localhost:1234).
 *
 * Each candidate env var name in `baseUrlEnvVars` is consulted in order
 * for both config and env steps, so an explicit `LMSTUDIO_BASE_URL` setting
 * wins over a generic `OLLAMA_HOST`.
 */
export function getEffectiveBaseUrl(def: ProviderDefinition): string {
  return baseUrlOverrideCandidates(def.baseUrlEnvVars)[0]?.value ?? def.baseUrl;
}

/**
 * Check if a provider name is a local provider (no API key needed).
 * Replaces LOCAL_PROVIDERS set in model-parser.ts.
 */
export function isLocalTransport(providerName: string): boolean {
  if (!_localProvidersCache) {
    _localProvidersCache = new Set();
    for (const def of BUILTIN_PROVIDERS) {
      if (def.isLocal) {
        _localProvidersCache.add(def.name);
      }
    }
  }
  const lower = providerName.toLowerCase();
  if (_localProvidersCache.has(lower)) return true;
  // Runtime fallback — custom endpoints may declare isLocal
  const runtimeDef = getRuntimeProviders().get(providerName);
  return !!runtimeDef?.isLocal;
}

/**
 * Check if a provider supports direct API access.
 * Replaces DIRECT_API_PROVIDERS set in model-parser.ts.
 */
export function isDirectApiProvider(providerName: string): boolean {
  if (!_directApiProvidersCache) {
    _directApiProvidersCache = new Set();
    for (const def of BUILTIN_PROVIDERS) {
      if (def.isDirectApi) {
        _directApiProvidersCache.add(def.name);
      }
    }
  }
  const lower = providerName.toLowerCase();
  if (_directApiProvidersCache.has(lower)) return true;
  // Runtime fallback — custom endpoints are direct API by default
  const runtimeDef = getRuntimeProviders().get(providerName);
  return !!runtimeDef?.isDirectApi;
}

/**
 * Convert a ProviderDefinition to the RemoteProvider shape used by existing consumers.
 */
export function toRemoteProvider(def: ProviderDefinition): RemoteProvider {
  const baseUrl = getEffectiveBaseUrl(def);

  // Handle opencode-zen-go special case: transform base URL
  let effectiveBaseUrl = baseUrl;
  if (def.name === "opencode-zen-go" && def.baseUrlEnvVars) {
    const envOverride = process.env[def.baseUrlEnvVars[0]];
    if (envOverride) {
      effectiveBaseUrl = envOverride.replace("/zen", "/zen/go");
    }
  }

  return {
    name: def.name === "google" ? "gemini" : def.name,
    baseUrl: effectiveBaseUrl,
    apiPath: def.apiPath,
    apiKeyEnvVar: def.apiKeyEnvVar,
    prefixes: def.legacyPrefixes.map((lp) => lp.prefix),
    headers: def.headers,
    authScheme: def.authScheme,
  };
}

/**
 * Get all provider definitions (builtin + runtime-registered).
 *
 * Fast path: when no runtime providers are registered, returns BUILTIN_PROVIDERS
 * directly (no allocation). Once any custom endpoint is loaded, returns a fresh
 * array that concatenates builtin and runtime definitions.
 */
export function getAllProviders(): ProviderDefinition[] {
  const runtime = getRuntimeProviders();
  if (runtime.size === 0) return BUILTIN_PROVIDERS;
  return [...BUILTIN_PROVIDERS, ...runtime.values()];
}

/**
 * Get the shortest prefix for a provider (for @ syntax handler creation).
 * Replaces PROVIDER_TO_PREFIX in auto-route.ts.
 */
export function getShortestPrefix(providerName: string): string {
  const def = getProviderByName(providerName);
  return def?.shortestPrefix || providerName;
}

/**
 * Get API key env var info for a provider (for auto-route).
 * Replaces API_KEY_ENV_VARS in auto-route.ts.
 */
export function getApiKeyEnvVars(
  providerName: string
): { envVar: string; aliases?: string[] } | null {
  const def = getProviderByName(providerName);
  if (!def) return null;
  return {
    envVar: def.apiKeyEnvVar,
    aliases: def.apiKeyAliases,
  };
}

// NOTE: the sync readiness oracles isProviderAvailable / isProviderAvailableByName
// were DELETED in the async-credential-layer refactor. Provider readiness is now
// resolved on demand through the credential authority (auth/credentials/authority.ts
// → isAvailable), the single source of truth that also pulls from 1Password. The
// model selector calls credentials.isAvailable() directly.