Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Live, per-subscription model discovery.
*
* Some providers serve a dynamic models catalog — and per-model context windows — that
* the cloud catalog CANNOT know statically, because the answer depends on the
* caller's subscription tier. Kimi Code is the motivating case: `k3` advertises
* a 1M context window, but only on Allegretto or higher; a Moderato subscriber
* sending 1M tokens gets a hard 400. The same shape exists for other coding
* subscriptions.
*
* A provider opts in by declaring `modelDiscovery` in its ProviderDefinition.
* We then call the provider's own authenticated model-listing endpoint, which
* — because it is authenticated — answers for THIS user's subscription. That
* is strictly better than modelling tiers locally: tiers get renamed, added,
* and grandfathered, but the endpoint always reports what the key can do now.
*
* Design rules:
* - **Fail-soft, but not fail-silent.** `discoverProviderModels` returns an
* empty list on every failure path — discovery is an enhancement and must
* never block a launch or a picker. `discoverProviderModelsCatalog` is the same work
* reported as a {@link ModelsCatalogOutcome}, for the one caller that has to explain
* the emptiness instead of absorbing it. Neither ever rejects.
* - **Nothing hardcoded.** The endpoint is derived from the provider's own
* baseUrl (+ env overrides); model ids and windows come from the response.
* - **Cached.** One network call per provider per TTL, shared process-wide —
* the picker, the launcher, and the status line all read the same result.
*/
import { credentials } from "../auth/credentials/authority.js";
import { log } from "../logger.js";
import { VERSION } from "../version.js";
import { resolveRouteProfile } from "./connection-resolver.js";
import { isOptInWireId } from "./content-use.js";
import { compareByReleaseDateDesc } from "./model-ordering.js";
import type { ModelOffer, ModelsCatalogAxis, ModelsCatalogEntry } from "./model-resolvers/types.js";
import { getProviderByName } from "./provider-definitions.js";
import type { ReportedCapability } from "./transport/probe-discovery.js";
/** A model as reported by the provider's own live endpoint. */
export interface DiscoveredModel {
/** Wire id — exactly what goes in the request body's `model` field. */
id: string;
/** Human label from the provider (e.g. "K2.7 Coding"), if reported. */
displayName?: string;
/** Real context window for THIS subscription, if reported. */
contextWindow?: number;
/**
* ISO date (`YYYY-MM-DD`) derived from the endpoint's `created` timestamp,
* when it reports a plausible one.
*
* NOT an authoritative release date — it is whenever the provider added the
* model to this account's dynamic models catalog — but for a plan endpoint whose models the
* public catalog may not list at all, it is the only freshness signal there
* is, and it orders a dynamic models catalog correctly. The catalog's own `releaseDate` wins
* wherever it exists; this covers the rest.
*/
releaseDate?: string;
/**
* Ignore the CATALOG's release date for this row, ordering it by the version
* encoded in its id instead.
*
* For a dynamic models catalog of tuned VARIANTS the cloud catalog does not list,
* a catalog date is not a fresher signal — it is a date for a DIFFERENT model. Antigravity is
* the case: measured 2026-08-24, 6 of its 19 served ids had a catalog date and
* every one of those six was an OLD base model, while every new variant had
* none:
*
* dated gemini-2.5-flash 2025-04-17
* dated gemini-3-flash 2025-12-17
* UNDATED gemini-3.6-flash-high —
* UNDATED gemini-3.7-flash-tiered —
*
* `compareByReleaseDateDesc` puts undated rows after dated ones, so a 2025
* model sat at the top of the picker and the newest model on the plan sat at
* the bottom — the exact complaint that prompted this. With the catalog date
* suppressed the whole dynamic models catalog falls through to the version-parts rule and
* orders 3.7 > 3.6 > 3.5 > 3.1 > 3 > 2.5, which is what the user meant by
* "newest first".
*/
ignoreCatalogReleaseDate?: boolean;
/**
* The row's position in the provider's OWN model picker (0 = first), when the
* provider publishes one. When any row of a dynamic models catalog carries it,
* the claudish picker lists exactly the rows that do, in this order, instead
* of every row newest first.
*
* Antigravity is the case: `agy models` prints `agentModelSorts`, a curated
* subset in a curated order, and the picker is asked to match that list
* exactly. The rows WITHOUT it stay in the dynamic models catalog on purpose:
* the routing availability filter (`providerServesModel`) and
* `discoverContextWindow` read the same list, and a row missing there would
* read as "not served". Presentation only — routing never reads this field.
*/
providerOrder?: number;
/**
* What the PROVIDER said about whether this model answers chat turns, when it
* said anything. Set by the discovery fetcher that holds the evidence, and read
* by every caller that filters a dynamic models catalog for chat models.
*
* It exists because those callers used to strip each row to its bare `id`
* before judging it, and a bare id judged alone is `"unknown"` for exactly the
* ids a provider invents: Ollama's local `name:tag` builds, Devin's
* knob-encoded uids (`swe-1-7-medium`), Antigravity's tuned variants
* (`gemini-3.6-flash-high`). Once `unknown` stopped counting as chat, those
* rows vanished from the picker — measured 2026-09-23: Ollama 19 → 1,
* Devin 247 → 3, Antigravity 21 → 7 — although every one of those providers had
* stated what its models were. `undefined` is a silence and stays one.
*/
reported?: ReportedCapability;
/**
* Variant metadata, for providers that encode knobs INTO their model ids.
*
* Most endpoints report a flat list where each id is already the thing a
* human would choose, and leave all of this undefined. Devin does not: its
* dynamic models catalog is ~33 models multiplied out by reasoning tier, speed premium, and
* context window, and it publishes which is which. Carrying that here is what
* lets `providers/model-resolvers/` fold 170 ids into 42 rows and unfold them
* again at request time.
*/
groupLabel?: string;
family?: string;
costFactor?: number;
costTier?: number;
isFamilyDefault?: boolean;
isRecommended?: boolean;
axes?: ModelsCatalogAxis[];
offer?: ModelOffer;
/**
* Whether the model can call tools, when the endpoint says so.
*
* Ollama reports it (via its own capability list / name heuristics), and it
* genuinely varies there — a local embedding or vision-only pull cannot drive
* Claude Code. Muse Code reports it as `metadata["muse-code"].tool_call`
* (`muse-models.ts`). Undefined means "not reported", which callers read as
* yes, since every hosted dynamic models catalog in claudish is tool-capable.
*/
supportsTools?: boolean;
}
/** A discovered model in the shape the model-resolver seam consumes. */
export function toModelsCatalogEntry(model: DiscoveredModel): ModelsCatalogEntry {
const { id, ...rest } = model;
return { wireId: id, ...rest };
}
/**
* Declares that a provider can list its own models at runtime.
* `path` is appended to the provider's resolved baseUrl.
*/
export interface ModelDiscoveryDescriptor {
/** Path appended to the resolved baseUrl (e.g. "/models"). Unused by `devin-connect`. */
path: string;
/**
* Response shape.
* - `openai-models-list`: `{ data: [{ id, context_length?, display_name?,
* created? }] }`. Also accepts `context_window` / `max_context_length`
* spellings, since OpenAI-compatible endpoints disagree on the field name.
* `created` is unix seconds and feeds `DiscoveredModel.releaseDate`.
* - `devin-connect`: not an HTTP GET at all — two protobuf rpcs whose
* intersection is capability ∩ entitlement. Owned by
* `providers/devin/devin-models.ts`; `path` is ignored.
* - `ollama-tags`: Ollama's `{ models: [{ name, details, … }] }`. Owned by
* `providers/ollama-discovery.ts`, which also derives tool support.
* - `antigravity`: an OAuth POST to `v1internal:fetchAvailableModels`, not a
* GET, so `path` is ignored. Owned by `auth/antigravity-user.ts`. Exists
* because the response carries a per-subscription `maxTokens` that the
* shared catalog contradicts — see the branch below.
* - `muse-code-models`: Meta's `GET /muse-code/models`, signed with the key
* minted from the Muse Code login, whose rows carry `metadata["muse-code"]`
* (name, hidden flag, window, modalities). Owned by
* `providers/meta-muse/muse-models.ts`.
*/
format:
| "openai-models-list"
| "devin-connect"
| "ollama-tags"
| "antigravity"
| "muse-code-models";
}
/**
* What a registered fetcher answers with.
*
* It used to be a bare `DiscoveredModel[]`, and that shape could not express
* failure: `[]` was the only thing a fetcher could say, so the caller recorded
* `empty-models-catalog` for it — the one kind that means "the endpoint answered
* correctly and has nothing to offer". Every fetcher on this path swallows its
* own errors on the way in (`fetchOllamaModels` is documented "never throws";
* `getServedDevinModels` and `getServedAntigravityModels` both degrade to an
* empty list), so a STOPPED Ollama daemon and a logged-out Antigravity account
* both arrived as "the endpoint answered and listed nothing" about an endpoint
* that never answered. That is the same information loss the discriminated
* outcome below exists to remove, one layer further in.
*
* - `models` with a non-empty list is a served dynamic models catalog.
* - `models` with `[]` is a genuinely empty one — and `endpoint` is what makes
* it sayable: the notice can finally name the URL that answered.
* - `failed` carries any of the seven kinds. `provider` is filled in by the
* caller, which is the only place that knows it.
*
* Throwing is still fine: {@link discoverProviderModelsCatalog} maps a rejection to
* `unreachable` and never rejects itself.
*/
export type FetcherResult =
| { kind: "models"; models: DiscoveredModel[]; endpoint?: string }
| { kind: "failed"; failure: Omit<DiscoveryFailure, "provider"> };
/** A dynamic models catalog fetcher for a format this module does not know how to speak. */
export type ModelDiscoveryFetcher = (providerName: string) => Promise<FetcherResult>;
const _fetchers = new Map<string, ModelDiscoveryFetcher>();
/**
* Register a fetcher for a non-GET discovery format.
*
* This is the seam the devin branch predicted: "If a third such provider ever
* appears, replace this branch with a `registerModelDiscoveryFetcher(name, fn)`
* seam — not worth it for one." Antigravity was the third, so it exists now.
*
* The inversion is the point. Before, this generic module had to KNOW about
* Devin's protobuf rpcs, Antigravity's OAuth POST and Ollama's daemon shape,
* and adding provider #4 meant editing a file that has nothing to do with
* provider #4. Now each owner declares itself and this module knows none of
* them — the same dependency direction the merged provider table just took, and
* for the same reason: a registration cannot be forgotten in a second place,
* because there is no second place.
*
* Registration is idempotent by name; the last writer wins, so a test can
* substitute a fetcher without unregistering first.
*/
export function registerModelDiscoveryFetcher(
format: string,
fetcher: ModelDiscoveryFetcher
): void {
_fetchers.set(format, fetcher);
}
/** The fetcher for a format, or undefined when nothing claims it. */
export function getModelDiscoveryFetcher(format: string): ModelDiscoveryFetcher | undefined {
return _fetchers.get(format);
}
const CACHE_TTL_MS = 5 * 60 * 1000;
const FETCH_TIMEOUT_MS = 5000;
const _cache = new Map<string, { models: DiscoveredModel[]; expiresAt: number }>();
/**
* Why a discovery attempt produced nothing.
*
* `discoverProviderModels` is fail-soft by contract — it must never block a
* launch or a picker — but for a long time "fail-soft" also meant "fail
* SILENT": all five failure modes below collapsed into the same empty array
* behind a `--debug`-only log line. Callers could not tell "your API key was
* rejected" from "this provider genuinely publishes no models", so the picker
* rendered a rejected credential as a free-text prompt, which reads as a
* feature rather than an error. (Measured on qwen-token-plan: a 401 from Alibaba's
* plan host was indistinguishable in the UI from a provider with no list.)
*
* The kinds are ordered by what the user should do about them, not by HTTP
* status: `unauthorized` and `no-credentials` are setup problems the user can
* fix, `unreachable` and `http-error` are usually transient, `incomplete` means
* the answer arrived but cannot be trusted as an enumeration, and
* `empty-models-catalog` means the endpoint answered correctly with nothing to offer —
* the only kind where falling through to a catalog or free-text entry is the
* genuinely right response.
*/
export type DiscoveryFailureKind =
| "no-credentials"
| "unauthorized"
| "http-error"
| "unreachable"
| "malformed"
| "incomplete"
| "empty-models-catalog";
export interface DiscoveryFailure {
kind: DiscoveryFailureKind;
provider: string;
/** Full URL that was attempted, when discovery got as far as building one. */
endpoint?: string;
/** HTTP status, for `unauthorized` / `http-error`. */
status?: number;
/** Upstream message or exception text, already truncated for display. */
detail?: string;
}
/**
* Why a discovery attempt produced what it produced — the whole answer, in one
* value, handed to the caller rather than left in module state to be re-read.
*
* `discoverProviderModels` answers `[]` to all of "this provider declares no
* discovery", "its endpoint rejected your key", "it was unreachable", "it
* answered with garbage" and "it answered correctly with nothing", and no
* caller can tell them apart. The picker rendered every one of them as "here
* are fewer models", which is the complaint this type exists to answer.
*
* Three variants, because there are three different things to say:
*
* - `served` — a dynamic models catalog. **Non-empty by construction**: every path that ends up
* with zero models records a failure instead, so there is no `served` with
* `[]` to guard against downstream.
* - `failed` — one of the seven {@link DiscoveryFailureKind}s, with the failure
* captured AT THE CALL. Read it from here, never from
* {@link getDiscoveryFailure} afterwards: that map is module-global and its
* entry is deleted by the next successful call for the same provider, so a
* re-read races every concurrent caller.
* - `unsupported` — nothing was attempted, and nothing is wrong. ~25 pickable
* providers declare no `modelDiscovery`; for them the cloud catalog is the
* normal, correct answer and a notice would be noise on the majority case.
* `no-fetcher` is the exception that IS a bug — a declared format nothing
* claims is a packaging mistake, not a dynamic models catalog fact — which is why it is here
* rather than folded into `empty-models-catalog` as it used to be. A declared
* descriptor whose base URL does not resolve is NOT here: that is a setup
* fault the user can fix, so it is `failed{unreachable}` naming the variable.
*/
export type ModelsCatalogOutcome =
| {
kind: "served";
/** The models claudish may offer or pick: content-use opt-in ids excluded. */
models: DiscoveredModel[];
/**
* Opt-in wire ids the account also serves (`content-use.ts`). Never offered
* or picked; read only to confirm an id the user typed exactly. Absent when
* there are none.
*/
optInIds?: string[];
}
| { kind: "failed"; failure: DiscoveryFailure }
| { kind: "unsupported"; reason: "no-descriptor" | "no-fetcher" };
/**
* Last failure per provider.
*
* Deliberately NOT part of the `_cache` entry: successes are cached for a TTL
* while failures are re-attempted on every call, so the two have different
* lifetimes. Recorded on every failing path and CLEARED on success, so a stale
* reason can never outlive the condition that produced it — the same
* run-scoped, in-memory rationale as `recordOpFailure` in `onepassword.ts`.
*/
const _failures = new Map<string, DiscoveryFailure>();
/**
* Record a failure and hand it back as the outcome.
*
* Returns the outcome rather than `[]` so that every call site can stay exactly
* where it is — the recorded-failure side effect and the returned value are the
* same fact, written once.
*/
function recordFailure(failure: DiscoveryFailure): ModelsCatalogOutcome {
_failures.set(failure.provider, failure);
log(`[model-discovery:${failure.provider}] ${describeDiscoveryFailure(failure)}`);
return { kind: "failed", failure };
}
/**
* Why the last `discoverProviderModels(provider)` call returned nothing, or
* undefined if it succeeded (or was never called).
*/
export function getDiscoveryFailure(provider: string): DiscoveryFailure | undefined {
return _failures.get(provider);
}
/**
* Whether a header set actually carries a credential.
*
* Case-insensitive because the header name is chosen by each transport —
* `authorization` lowercase on some, `Authorization` on others, `x-api-key` on
* the Anthropic-shaped ones. A non-empty VALUE is required: an empty string is
* what an unresolved credential looks like, and it authenticates nothing.
*/
function hasAuthHeader(headers: Record<string, string>): boolean {
return Object.entries(headers).some(
([name, value]) =>
/^(authorization|x-api-key|api-key)$/i.test(name) && (value ?? "").trim().length > 0
);
}
/** Truncate upstream error text to one readable line. */
function oneLine(text: string, max = 200): string {
const flat = text.replace(/\s+/g, " ").trim();
return flat.length > max ? `${flat.slice(0, max)}…` : flat;
}
/**
* A discovery failure as a single human-readable sentence.
*
* Names the endpoint for anything network-shaped, because "check your API key"
* without saying WHICH host rejected it is exactly the advice that sent this
* bug's investigation to the wrong provider for hours — Alibaba serves several
* mutually-isolated plan hosts, and a key valid for one is rejected by all the
* others with an identical message.
*/
export function describeDiscoveryFailure(failure: DiscoveryFailure): string {
const { kind, endpoint, status, detail } = failure;
const at = endpoint ? ` at ${endpoint}` : "";
const because = detail ? ` — ${detail}` : "";
// Every optional field is guarded, `status` included. The GET path always has
// one for these two kinds, but a registered fetcher may now report either
// without it, and an interpolated `undefined` in a user-facing sentence is
// worse than a shorter sentence. Pinned by a test that asserts no rendered
// notice contains the substring.
const http = status === undefined ? "" : ` (HTTP ${status})`;
switch (kind) {
case "no-credentials":
return `no usable credentials${because}`;
case "unauthorized":
return `the API key was rejected${http}${at}${because}`;
case "http-error":
return status === undefined
? `the model list returned an error${at}${because}`
: `the model list returned HTTP ${status}${at}${because}`;
case "unreachable":
return `the model list was unreachable${at}${because}`;
case "malformed":
return `the model list was not valid JSON${at}`;
case "incomplete":
return `the model list could not be read as a complete list${at}${because}`;
case "empty-models-catalog":
return `the endpoint answered${at} but listed no models`;
}
}
/** Drop cached discovery (after a credential change / TUI hydrate-on-add). */
export function invalidateModelDiscovery(provider?: string): void {
if (provider) {
_cache.delete(provider);
_failures.delete(provider);
} else {
_cache.clear();
_failures.clear();
}
}
/**
* The model-list URL for a catalog-routed provider: its route profile's base
* URL in the route registry plus `/models` — the host its requests use, so
* discovery moves with the registry (OpenCode moved Zen to
* `opencode.ai/inference/v1` on 2026-10-12). Every registry base already ends
* in the API's version root. `undefined` — keep the definition's URL — when
* the user overrode the base URL, or no registry is cached.
*/
function registryModelsEndpoint(
providerName: string,
def: { baseUrlEnvVars?: string[] }
): string | undefined {
if ((def.baseUrlEnvVars ?? []).some((envVar) => process.env[envVar])) return undefined;
const profile = resolveRouteProfile(providerName)?.profile;
const base =
profile?.apis["chat-completions"]?.baseUrl ??
profile?.apis.responses?.baseUrl ??
profile?.apis["anthropic-messages"]?.baseUrl;
return base ? `${base.replace(/\/+$/, "")}/models` : undefined;
}
/**
* Resolve a provider's base URL: env override (in catalog order), else the
* catalog default. Mirrors localBaseUrl() but works for remote providers too.
*/
function resolveBaseUrl(catalogName: string): string | null {
const def = getProviderByName(catalogName);
if (!def) return null;
for (const envVar of def.baseUrlEnvVars ?? []) {
const v = process.env[envVar];
if (v) return v.replace(/\/+$/, "");
}
return (def.baseUrl || "").replace(/\/+$/, "") || null;
}
/** Pull the context window out of a model row, tolerating field-name drift. */
function readContextWindow(row: Record<string, unknown>): number | undefined {
for (const field of ["context_length", "context_window", "max_context_length"]) {
const v = row[field];
if (typeof v === "number" && Number.isFinite(v) && v > 0) return v;
}
return undefined;
}
/**
* Earliest/latest `created` values we will believe, as unix SECONDS:
* 2000-01-01 .. 2100-01-01. Anything outside is not a seconds-scale timestamp
* we can use — notably millisecond values (~1.7e12) land far past the ceiling
* and are rejected rather than silently read as the year 55000.
*/
const MIN_CREATED_SECONDS = 946_684_800;
const MAX_CREATED_SECONDS = 4_102_444_800;
/**
* Pull an ISO date out of a model row's `created` field (unix seconds).
*
* Deliberately strict-but-silent: absent, zero, non-numeric, or implausible
* values yield undefined rather than a bogus date. A wrong date would sort the
* picker wrongly and look authoritative doing it, whereas a missing one just
* falls back to the catalog / id ordering.
*/
function readCreatedDate(row: Record<string, unknown>): string | undefined {
const raw = row.created;
const seconds =
typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : Number.NaN;
if (!Number.isFinite(seconds)) return undefined;
if (seconds < MIN_CREATED_SECONDS || seconds > MAX_CREATED_SECONDS) return undefined;
const iso = new Date(seconds * 1000).toISOString();
return iso.slice(0, 10);
}
/**
* What a parse of an OpenAI-style `{ data: [...] }` list produced.
*
* `dropped` and `total` exist because the parser used to `continue` silently
* over rows it could not use, and a caller therefore could not tell "the server
* listed 28 models" from "the server listed 28 and we understood 25". The
* enumeration we hold is only the enumeration the server sent when nothing was
* dropped — and only a complete enumeration may deny a model.
*/
interface ParsedModelsList {
models: DiscoveredModel[];
/** Rows the parser could not use: not an object, or no usable `id`. */
dropped: number;
/** Rows the server sent, or null when the declared container was missing. */
total: number | null;
}
/** Parse an OpenAI-style `{ data: [...] }` model list. */
function parseOpenAIModelsList(body: unknown): ParsedModelsList {
const data = (body as { data?: unknown })?.data;
// A missing `data` is NOT an empty plan. Answering it with `[]` made the two
// indistinguishable, which is the collapse this whole contract exists to stop.
if (!Array.isArray(data)) return { models: [], dropped: 0, total: null };
const models: DiscoveredModel[] = [];
let dropped = 0;
for (const raw of data) {
if (!raw || typeof raw !== "object") {
dropped++;
continue;
}
const row = raw as Record<string, unknown>;
const id = row.id;
if (typeof id !== "string" || id.trim().length === 0) {
dropped++;
continue;
}
const displayName = typeof row.display_name === "string" ? row.display_name : undefined;
models.push({
id,
displayName,
contextWindow: readContextWindow(row),
releaseDate: readCreatedDate(row),
});
}
return { models, dropped, total: data.length };
}
/**
* Top-level fields that would mean "there is more of this list elsewhere".
*
* A guard against a FUTURE paginating endpoint rather than a description of
* today's: the Token Plan list's measured key union is `created, id, object,
* owned_by`, with no continuation field at all. It costs nothing now and is the
* only thing that would notice the day one appears.
*/
const CONTINUATION_FIELDS = ["has_more", "next", "next_page", "next_page_token"] as const;
function describeContinuation(body: unknown): string | null {
if (!body || typeof body !== "object") return null;
const root = body as Record<string, unknown>;
for (const field of CONTINUATION_FIELDS) {
const value = root[field];
const signalled = field === "has_more" ? value === true : Boolean(value);
if (signalled) return `${field}: ${JSON.stringify(value)}`;
}
return null;
}
/**
* Why this 200 does not establish a COMPLETE list, or null when it does.
*
* The conditions, in order: the container is present and is an array; no
* continuation is signalled; nothing was dropped in parsing; and at least one
* model came out. (HTTP 200 with a body that parses is settled before this is
* called.)
*
* Note what is deliberately NOT here: any comparison of a count to a previous
* count or to a constant. Alibaba's coverage is reported as 20, 31, 24, 52 and
* 25 by five different sources, so a count rule would encode a number the
* vendor itself does not agree on.
*
* And note the limit, which is real: these endpoints publish no total, no
* pagination and no continuation signal, so a well-formed non-empty SUBSET is
* indistinguishable from a complete response. Completeness here is DETECTED,
* not proven — an undetectably partial answer can still be accepted.
*/
function describeIncompleteness(body: unknown, parsed: ParsedModelsList): string | null {
if (parsed.total === null) return "the response carried no `data` array";
const continuation = describeContinuation(body);
if (continuation) return `the endpoint signalled more results (${continuation})`;
if (parsed.dropped > 0) return `${parsed.dropped} of ${parsed.total} entries were unparseable`;
if (parsed.models.length === 0) return "the endpoint listed no models";
return null;
}
/**
* The non-GET half: a format this module cannot speak itself, served by a
* registered fetcher.
*
* Devin's dynamic models catalog is two protobuf rpcs (capability ∩
* entitlement); Antigravity's is an OAuth POST; Ollama's is its daemon's own
* listing shape. The imports are DYNAMIC to keep the codec and the OAuth path
* off the cold-start path, and this module deliberately knows NONE of them by
* name — the builtin bundle is imported on first miss, which inverts the
* dependency so that adding provider #4 means editing provider #4.
*
* Never rejects: the dynamic import and the fetcher call are both inside the
* `try`, and both can throw.
*/
async function discoverViaFetcher(
providerName: string,
format: string
): Promise<ModelsCatalogOutcome> {
let result: FetcherResult;
try {
let fetcher = getModelDiscoveryFetcher(format);
if (!fetcher) {
await import("./model-discovery-builtins.js");
fetcher = getModelDiscoveryFetcher(format);
}
if (!fetcher) {
// A declared format nothing claims. This is a PACKAGING bug — a
// definition opted into a format whose owner was never bundled — not a
// statement about the user's dynamic models catalog, so it is
// `unsupported`, not the `empty-models-catalog` it used to be recorded as.
// It renders nothing and is caught by a build-integrity test rather than
// shown to the user.
log(`[model-discovery:${providerName}] no fetcher claims format "${format}"`);
return { kind: "unsupported", reason: "no-fetcher" };
}
result = await fetcher(providerName);
} catch (e: unknown) {
return recordFailure({
kind: "unreachable",
provider: providerName,
detail: oneLine((e as Error)?.message ?? String(e)),
});
}
if (result.kind === "failed") {
return recordFailure({ ...result.failure, provider: providerName });
}
const models = result.models;
if (models.length === 0) {
// A reachable endpoint that listed nothing — and now it can say WHERE,
// because the fetcher reports the URL it asked.
return recordFailure({
kind: "empty-models-catalog",
provider: providerName,
endpoint: result.endpoint,
});
}
_failures.delete(providerName);
log(`[model-discovery:${providerName}] discovered ${models.length} models`);
_cache.set(providerName, { models, expiresAt: Date.now() + CACHE_TTL_MS });
return { kind: "served", models };
}
/**
* List the models this provider serves for the CURRENT credentials, as a
* discriminated outcome — see {@link ModelsCatalogOutcome}.
*
* **This function NEVER REJECTS.** Every `await` is inside a `try`, including
* the dynamic import of the builtin fetcher bundle and the fetcher call itself,
* and a throw becomes `failed{kind:"unreachable"}`. Two of those awaits used to
* be bare: Devin speaks protobuf rpcs and Antigravity does an OAuth POST, so a
* rejection propagated out of the picker. A line-oriented prompt survives that;
* a live renderer with no stderr does not — it leaves a progress indicator
* running against a promise that never settles. Callers may therefore have no
* rejection branch, and a Tier-1 test registers a throwing fetcher to pin it.
*/
export async function discoverProviderModelsCatalog(
providerName: string
): Promise<ModelsCatalogOutcome> {
const outcome = await discoverEveryServedModel(providerName);
if (outcome.kind !== "served") return outcome;
// The single discovery entry, so this is the choke point for dynamic models
// catalogs: everything that offers or picks a model reads `models`, and a
// content-use opt-in id is never one of them (`content-use.ts`).
const models = outcome.models.filter((model) => !isOptInWireId(model.id));
if (models.length === outcome.models.length) return outcome;
const optInIds = outcome.models.filter((model) => isOptInWireId(model.id)).map((m) => m.id);
return { kind: "served", models, optInIds };
}
/**
* Every model the account serves, opt-in ids included, for the EXACT-id readers:
* whether a typed id is entitled (`providerServesModel`) and its served window
* (`discoverContextWindow`). `optIn` holds the content-use opt-in ids, which
* nothing may offer or pick. Fail-soft like {@link discoverProviderModels}: both
* lists are empty on any failure. Shares the one discovery cache.
*/
export async function discoverProviderServedIds(
providerName: string
): Promise<{ served: DiscoveredModel[]; optIn: DiscoveredModel[] }> {
const outcome = await discoverEveryServedModel(providerName);
if (outcome.kind !== "served") return { served: [], optIn: [] };
return {
served: outcome.models.filter((model) => !isOptInWireId(model.id)),
optIn: outcome.models.filter((model) => isOptInWireId(model.id)),
};
}
/** The discovery itself: the full list the provider returned, cached unsplit. Never rejects. */
async function discoverEveryServedModel(providerName: string): Promise<ModelsCatalogOutcome> {
const cached = _cache.get(providerName);
if (cached && cached.expiresAt > Date.now()) return { kind: "served", models: cached.models };
const def = getProviderByName(providerName);
const descriptor = def?.modelDiscovery;
if (!def || !descriptor) return { kind: "unsupported", reason: "no-descriptor" };
if (descriptor.format !== "openai-models-list") {
return await discoverViaFetcher(providerName, descriptor.format);
}
const baseUrl = resolveBaseUrl(providerName);
if (!baseUrl) {
// This used to return [] with nothing recorded, i.e. "this plan lists no
// models" — a configuration fault reported as an entitlement fact. It is a
// `failed` outcome, not `unsupported`: the provider DID declare discovery,
// so the user has something to fix, and the notice names where to fix it.
const overrides = (def.baseUrlEnvVars ?? []).join(", ");
return recordFailure({
kind: "unreachable",
provider: providerName,
detail: `no base URL resolved — check ${overrides || "the provider's baseUrl"}`,
});
}
const definitionEndpoint = `${baseUrl}${descriptor.path}`;
let endpoint = registryModelsEndpoint(providerName, def) ?? definitionEndpoint;
// Auth via the credential authority — it owns OAuth-vs-API-key precedence
// (Kimi Coding prefers an OAuth token over a stale KIMI_CODING_API_KEY) and
// mints any provider-specific platform headers.
//
// A LOCAL provider deliberately does NOT go through it. LM Studio and a
// localhost Ollama serve unauthenticated; a key is the exception, wanted only
// when the user has exposed the daemon on their network. Asking the authority
// would send it hunting through the op:// chain for a key that usually does
// not exist — measured: listing LM Studio models opened a 1Password handshake
// and, on a locked Mac, a 30-second unlock wait, to discover nothing. Reading
// the env var directly is both correct and free.
let headers: Record<string, string> = {};
if (def.isLocal) {
const key = def.apiKeyEnvVar ? process.env[def.apiKeyEnvVar] : undefined;
if (key) headers = { Authorization: `Bearer ${key}` };
} else {
try {
const auth = await credentials.getRequestAuth(providerName, { model: "" });
headers = { ...auth.headers };
} catch (e: unknown) {
return recordFailure({
kind: "no-credentials",
provider: providerName,
endpoint,
detail: oneLine((e as Error)?.message ?? ""),
});
}
// The authority does not always THROW for a missing key — for several
// providers it returns headers with no auth on them, which upstream then
// answers with the same 401 a wrong key produces. Distinguishing the two
// matters: "you have not set a key" and "your key was rejected" have
// different fixes, and reporting the latter for the former sends the user
// hunting for a typo in a variable they never defined. Checking here also
// skips a round-trip that cannot succeed.
if (!hasAuthHeader(headers)) {
return recordFailure({ kind: "no-credentials", provider: providerName, endpoint });
}
}
// Identify ourselves, and honour the definition's own headers.
//
// `getRequestAuth` mints AUTH headers only, so a discovery request went out with
// whatever User-Agent the runtime defaults to. Measured 2026-08-18: OpenCode
// Zen Go answers such a request with `403 error code: 1010` — Cloudflare's
// browser-integrity block, not an auth failure — while the identical request
// carrying a User-Agent returns 200 with 26 models. Without this, adding a
// `modelDiscovery` entry for that provider would look like a broken endpoint
// and be classified `unauthorized`, sending the user to check a working key.
//
// `def.headers` is applied AFTER, so a provider that needs a specific value
// still wins; auth headers are applied last so nothing can displace them.
headers = {
"User-Agent": `claudish/${VERSION}`,
...(def.headers ?? {}),
...headers,
};
const fetchList = (url: string) =>
fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
let response: Response;
try {
response = await fetchList(endpoint);
// The registry publishes API bases, not a model-list URL, so the registry
// endpoint is DERIVED (`<chat base>/models`). That holds for Zen
// (`inference/v1`) but not for Zen Go, whose APIs split by family
// (`inference/go/openai/v1`) while its list sits at `inference/go/v1/models`.
// Measured 2026-10-20, one key: the derived URL answers 404, the
// definition's `zen/go/v1/models` answers 200 with 37 models. A 404 says
// "no list at this address", never anything about entitlement, so the
// definition's URL gets one try before the failure is recorded.
if (response.status === 404 && endpoint !== definitionEndpoint) {
endpoint = definitionEndpoint;
response = await fetchList(endpoint);
}
} catch (e: unknown) {
return recordFailure({
kind: "unreachable",
provider: providerName,
endpoint,
detail: oneLine((e as Error)?.message ?? ""),
});
}
if (!response.ok) {
// 401/403 is split out because it is the only status the USER can act on,
// and the action is specific: fix the credential. Everything else is
// infrastructure and usually transient.
const unauthorized = response.status === 401 || response.status === 403;
// Body is read best-effort — the upstream message is often the only thing
// that distinguishes "key rejected" from "key valid, plan expired", and
// Alibaba's plan hosts do exactly that.
let detail = "";
try {
detail = oneLine(await response.text());
} catch {
/* body unavailable — the status alone is still actionable */
}
return recordFailure({
kind: unauthorized ? "unauthorized" : "http-error",
provider: providerName,
endpoint,
status: response.status,
detail,
});
}
let body: unknown;
try {
body = await response.json();
} catch {
return recordFailure({ kind: "malformed", provider: providerName, endpoint });
}
const parsed = parseOpenAIModelsList(body);
const incomplete = describeIncompleteness(body, parsed);
if (incomplete) {
// Not cached, and nothing returned. A list that fails the completeness
// checks is one we could not trust: shown as though it were the account's
// dynamic models catalog, it is the confident-looking wrong answer, and
// handed to `providerServesModel` it would DENY every model the missing
// rows or pages held. `[]` plus a recorded failure reads as `unknown`
// there, so an untrusted list confirms nothing and denies nothing.
//
// `empty-models-catalog` stays its own KIND rather than folding into
// `incomplete`: "the endpoint answered with nothing to offer" has its own
// sentence, and the picker already treats it differently.
return recordFailure({
kind: parsed.models.length === 0 ? "empty-models-catalog" : "incomplete",
provider: providerName,
endpoint,
detail: incomplete,
});
}
const models = parsed.models;
_failures.delete(providerName);
log(
`[model-discovery:${providerName}] discovered ${models.length} models from ${endpoint}: ` +
models.map((m) => `${m.id}(${m.contextWindow ?? "?"})`).join(", ")
);
_cache.set(providerName, { models, expiresAt: Date.now() + CACHE_TTL_MS });
return { kind: "served", models };
}
/**
* List the models this provider serves for the CURRENT credentials.
*
* Returns [] when the provider declares no `modelDiscovery`, has no usable
* credentials, or the endpoint is unreachable/malformed/incomplete — callers
* fall back to the cloud models catalog. Every one of those except "declares no
* `modelDiscovery`" records a reason for `getDiscoveryFailure`, so `[]` is
* never silently read as "the plan lists nothing".
*
* The fail-soft shape every non-picker caller wants (the launcher, the status
* line, `discoverContextWindow`): discovery is an enhancement and must never
* block a launch. A caller that needs to TELL the user why there is nothing —
* i.e. the picker — calls {@link discoverProviderModelsCatalog} instead and keeps the
* distinction. Both share one cache, so asking twice costs one request.
*/
export async function discoverProviderModels(providerName: string): Promise<DiscoveredModel[]> {
const outcome = await discoverProviderModelsCatalog(providerName);
return outcome.kind === "served" ? outcome.models : [];
}
/**
* Real context window for one model on one provider, from live discovery.
* Returns undefined when discovery is unavailable or the model isn't listed —
* callers fall back to the cloud catalog.
*/
export async function discoverContextWindow(
providerName: string,
modelId: string
): Promise<number | undefined> {
// Exact-id lookup: an opt-in id the user typed still gets its served window.
const { served, optIn } = await discoverProviderServedIds(providerName);
const match = [...served, ...optIn].find((m) => m.id.toLowerCase() === modelId.toLowerCase());
return match?.contextWindow;
}
/**
* Rank a dynamic models catalog for presentation, largest context window first,
* then NEWEST. The head of this list is the picker's default and the first model
* a probe tries.
*
* Deliberately a RULE rather than a pinned model id: pinning "k3" today would
* rot into exactly the `fixedModel: "kimi-for-coding"` bug this replaces —
* stale the moment the provider ships its next model. A capability-ordered
* list upgrades itself.
*
* The tie-break used to be alphabetical, "for determinism", and on a plan whose
* whole catalog shares one window that decided everything: Antigravity serves 21
* models at 1M, so the head of the list was `gemini-2.5-flash` and the newest
* model on the plan sat near the bottom (measured 2026-09-19). Alphabetical order
* on version numbers reads oldest-first, which is the opposite of what both the
* picker and a probe want. `compareByReleaseDateDesc` is the comparator the
* picker already uses: release date first, then the version encoded in the id
* (3.8 above 2.5), then the id, so it stays deterministic.
*/
export function rankDiscoveredModels(models: DiscoveredModel[]): DiscoveredModel[] {
return [...models].sort((a, b) => {
const diff = (b.contextWindow ?? 0) - (a.contextWindow ?? 0);
return diff !== 0 ? diff : compareByReleaseDateDesc(a, b);
});
}