Skip to content

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

feat(picker): a discovery OUTCOME, so an empty list can say why

Jack Rudenkoc6268660434b
diff --git a/packages/cli/src/model-selector-discovery.test.ts b/packages/cli/src/model-selector-discovery.test.ts
new file mode 100644
index 00000000..0b058fab
--- /dev/null
+++ b/packages/cli/src/model-selector-discovery.test.ts
@@ -0,0 +1,529 @@
+/**
+ * The picker's discovery outcome — `buildDiscoveredModelOutcome`, the notice
+ * formatter behind it, and the chat-capability chokepoint both doors return
+ * through.
+ *
+ * The defect these pin: `buildDiscoveredModelRows` returned `[]` for five
+ * distinguishable states — a rejected key, an unreachable endpoint, a genuinely
+ * empty roster, a roster where nothing was chat-capable, and a roster that
+ * collapsed to nothing — and the caller fell through to the cloud catalog for
+ * all of them in silence. The user saw "fewer model names, like the provider
+ * does not have any models". So every test here is a state that used to be
+ * indistinguishable from the other four.
+ *
+ * Offline by construction: `globalThis.fetch`, `credentials.getRequestAuth` and
+ * the `CatalogClient` are all substituted directly. No `mock.module()` — it
+ * bleeds into sibling Bun test files.
+ *
+ * Nothing here asserts a price, a context window or a capability flag: those
+ * come from the on-disk model catalog, which is warm on a dev machine and cold
+ * on a fresh clone. Ids, counts and outcome kinds are the assertions.
+ *
+ * Run: bun test packages/cli/src/model-selector-discovery.test.ts
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+
+import { credentials } from "./auth/credentials/authority.js";
+import {
+ _rosterCollapse,
+ buildDiscoveredModelOutcome,
+ buildDiscoveredModelRows,
+ formatDiscoveryFailureNotice,
+ toPickerRows,
+ warnDiscoveryFailure,
+} from "./model-selector.js";
+import type { ModelInfo } from "./model-selector.js";
+import type { CatalogClient, CatalogModel } from "./providers/model-catalog.js";
+import {
+ type DiscoveryFailure,
+ type DiscoveryFailureKind,
+ describeDiscoveryFailure,
+ invalidateModelDiscovery,
+} from "./providers/model-discovery.js";
+import type { ProviderDefinition } from "./providers/provider-definitions.js";
+import { clearRuntimeRegistry, registerRuntimeProvider } from "./providers/runtime-providers.js";
+
+const PROVIDER = "picker-outcome-test";
+const DISPLAY_NAME = "Picker Outcome Test";
+const ENV_VAR = "PICKER_OUTCOME_TEST_API_KEY";
+const KEY_URL = "https://picker-outcome.invalid/key";
+
+const realFetch = globalThis.fetch;
+const realGetRequestAuth = credentials.getRequestAuth;
+const realCollapse = _rosterCollapse.collapse;
+
+function defineProvider(overrides: Partial<ProviderDefinition> = {}): ProviderDefinition {
+ return {
+ name: PROVIDER,
+ displayName: DISPLAY_NAME,
+ transport: "openai",
+ baseUrl: "https://picker-outcome.invalid",
+ apiPath: "/v1/chat/completions",
+ apiKeyEnvVar: ENV_VAR,
+ apiKeyDescription: "Offline test key",
+ apiKeyUrl: KEY_URL,
+ shortcuts: [],
+ legacyPrefixes: [],
+ modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
+ createHandler: { kind: "none", reason: "virtual", note: "Offline test fixture" },
+ isDirectApi: true,
+ ...overrides,
+ };
+}
+
+/** The provider's live endpoint answers with exactly these ids. */
+function serves(ids: string[]): void {
+ globalThis.fetch = mock(
+ async () =>
+ new Response(JSON.stringify({ data: ids.map((id) => ({ id })) }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ })
+ ) as unknown as typeof fetch;
+}
+
+function rejectsWith(status: number): void {
+ globalThis.fetch = mock(
+ async () => new Response(JSON.stringify({ error: "rejected" }), { status })
+ ) as unknown as typeof fetch;
+}
+
+/** A CatalogClient that answers from memory. `null` rows means "catalog fails". */
+function stubCatalog(rows: CatalogModel[] | null): CatalogClient {
+ return {
+ async modelsByVendor() {
+ if (rows === null) throw new Error("catalog unavailable");
+ return rows;
+ },
+ async vendorsForModel() {
+ return null;
+ },
+ async searchModels() {
+ return [];
+ },
+ };
+}
+
+const CATALOG_ROWS: CatalogModel[] = [
+ { modelId: "catalog-chat-1", displayName: "Catalog Chat 1", provider: "moonshotai" },
+ { modelId: "catalog-chat-2", displayName: "Catalog Chat 2", provider: "moonshotai" },
+];
+
+beforeEach(() => {
+ invalidateModelDiscovery();
+ clearRuntimeRegistry();
+ registerRuntimeProvider(defineProvider());
+ credentials.getRequestAuth = mock(async () => ({
+ headers: { Authorization: "Bearer offline-test-token" },
+ }));
+ globalThis.fetch = mock(async () => {
+ throw new Error("Unexpected fetch call");
+ }) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+ invalidateModelDiscovery();
+ clearRuntimeRegistry();
+ globalThis.fetch = realFetch;
+ credentials.getRequestAuth = realGetRequestAuth;
+ _rosterCollapse.collapse = realCollapse;
+});
+
+describe("buildDiscoveredModelOutcome — all five states, told apart", () => {
+ test("STATE A · a healthy roster is `rows`, non-empty, with servedCount === chatCount", async () => {
+ serves(["alpha-chat", "beta-chat", "gamma-chat"]);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ expect(outcome.kind).toBe("rows");
+ if (outcome.kind !== "rows") throw new Error("unreachable");
+ expect(outcome.rows.map((r) => r.id).sort()).toEqual(["alpha-chat", "beta-chat", "gamma-chat"]);
+ expect(outcome.rows.length).toBeGreaterThan(0);
+ expect(outcome.servedCount).toBe(3);
+ expect(outcome.chatCount).toBe(3);
+ });
+
+ test("a PARTIALLY filtered roster keeps the two counts apart — the fact discarded today", async () => {
+ serves(["alpha-chat", "text-embedding-3-large", "whisper-1"]);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ expect(outcome.kind).toBe("rows");
+ if (outcome.kind !== "rows") throw new Error("unreachable");
+ expect(outcome.rows.map((r) => r.id)).toEqual(["alpha-chat"]);
+ expect(outcome.servedCount).toBe(3);
+ expect(outcome.chatCount).toBe(1);
+ expect(outcome.chatCount).toBeLessThan(outcome.servedCount);
+ });
+
+ test("STATE B · served N, none chat-capable → all-filtered with the count and ≤3 sample ids", async () => {
+ // Invisible today: the provider is healthy, the key is fine, and the picker
+ // silently shows the cloud catalog instead. The sample ids are what make the
+ // notice self-explaining — they are usually embeddings or route wildcards.
+ serves(["text-embedding-3-large", "whisper-1", "dall-e-3", "nomic-embed-text"]);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ expect(outcome.kind).toBe("all-filtered");
+ if (outcome.kind !== "all-filtered") throw new Error("unreachable");
+ expect(outcome.servedCount).toBe(4);
+ expect(outcome.sampleIds.length).toBe(3);
+ for (const id of outcome.sampleIds) {
+ expect(["text-embedding-3-large", "whisper-1", "dall-e-3", "nomic-embed-text"]).toContain(id);
+ }
+ expect(outcome.fallbackRows.map((r) => r.id).sort()).toEqual([
+ "catalog-chat-1",
+ "catalog-chat-2",
+ ]);
+ });
+
+ test("STATE C · a genuinely empty roster is its own variant, carrying the failure", async () => {
+ serves([]);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ expect(outcome.kind).toBe("empty-roster");
+ if (outcome.kind !== "empty-roster") throw new Error("unreachable");
+ expect(outcome.failure.kind).toBe("empty-roster");
+ expect(outcome.failure.endpoint).toContain("/v1/models");
+ expect(outcome.fallbackRows.length).toBe(2);
+ });
+
+ test("STATE D · a rejected key is `failed` — a DIFFERENT variant from empty-roster", async () => {
+ rejectsWith(401);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ expect(outcome.kind).toBe("failed");
+ if (outcome.kind !== "failed") throw new Error("unreachable");
+ expect(outcome.failure.kind).toBe("unauthorized");
+ expect(outcome.failure.status).toBe(401);
+ // The whole point of the split: a 401 and an empty list are not the same
+ // thing, and the type no longer lets a renderer treat them as one.
+ expect(outcome.kind).not.toBe("empty-roster");
+ expect(outcome.notice.join("")).toContain(DISPLAY_NAME);
+ expect(outcome.notice.join("")).toContain(ENV_VAR);
+ expect(outcome.fallbackRows.map((r) => r.id).sort()).toEqual([
+ "catalog-chat-1",
+ "catalog-chat-2",
+ ]);
+ });
+
+ test("STATE E · a roster that collapses to nothing is collapsed-empty, never rows:[]", async () => {
+ // Unreachable through the one shipped resolver (every entry lands in a group
+ // and every group yields a choice), and modelled anyway: `{kind:"rows",
+ // rows: []}` would be an empty panel with no explanation — the exact defect
+ // class this type exists to remove, reintroduced inside it.
+ _rosterCollapse.collapse = () => [];
+ serves(["alpha-chat", "beta-chat"]);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ expect(outcome.kind).toBe("collapsed-empty");
+ if (outcome.kind !== "collapsed-empty") throw new Error("unreachable");
+ expect(outcome.servedCount).toBe(2);
+ expect(outcome.chatCount).toBe(2);
+ expect(outcome.fallbackRows.length).toBe(2);
+ });
+
+ test("a provider with no modelDiscovery is `unsupported`, which renders nothing", async () => {
+ clearRuntimeRegistry();
+ registerRuntimeProvider(defineProvider({ modelDiscovery: undefined }));
+
+ expect(
+ await buildDiscoveredModelOutcome(PROVIDER, DISPLAY_NAME, stubCatalog(CATALOG_ROWS))
+ ).toEqual({ kind: "unsupported", reason: "no-descriptor" });
+ });
+
+ test("`rows` is non-empty on every path that produces it", async () => {
+ // The invariant `rows: [ModelInfo, ...ModelInfo[]]` states at the type level;
+ // this asserts it at runtime across every shape that reaches the branch.
+ for (const ids of [["only-one"], ["a-chat", "b-chat"], ["a-chat", "whisper-1"]]) {
+ invalidateModelDiscovery();
+ serves(ids);
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+ expect(outcome.kind).toBe("rows");
+ if (outcome.kind !== "rows") throw new Error("unreachable");
+ expect(outcome.rows.length).toBeGreaterThan(0);
+ }
+ });
+});
+
+describe("buildDiscoveredModelOutcome — the fallback leg", () => {
+ test("a failing catalog leaves fallbackRows empty instead of rejecting", async () => {
+ rejectsWith(500);
+
+ const outcome = await buildDiscoveredModelOutcome(PROVIDER, DISPLAY_NAME, stubCatalog(null));
+
+ expect(outcome.kind).toBe("failed");
+ if (outcome.kind !== "failed") throw new Error("unreachable");
+ expect(outcome.fallbackRows).toEqual([]);
+ // With nothing to show, "manual model entry" is finally the true sentence.
+ expect(outcome.notice.join("")).toContain("Falling back to manual model entry.");
+ });
+
+ test("with catalog rows in hand the notice names the catalog, not manual entry", async () => {
+ rejectsWith(401);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog(CATALOG_ROWS)
+ );
+
+ if (outcome.kind !== "failed") throw new Error("unreachable");
+ const notice = outcome.notice.join("");
+ expect(notice).toContain("cloud-catalog entries below — not its live roster.");
+ expect(notice).not.toContain("Falling back to manual model entry.");
+ });
+
+ test("the catalog fallback is chat-filtered too, via the same chokepoint", async () => {
+ rejectsWith(401);
+
+ const outcome = await buildDiscoveredModelOutcome(
+ PROVIDER,
+ DISPLAY_NAME,
+ stubCatalog([
+ ...CATALOG_ROWS,
+ { modelId: "gpt-image-2.5-flare", displayName: "Image", provider: "openai" },
+ ])
+ );
+
+ if (outcome.kind !== "failed") throw new Error("unreachable");
+ expect(outcome.fallbackRows.map((r) => r.id)).not.toContain("gpt-image-2.5-flare");
+ });
+});
+
+describe("buildDiscoveredModelRows stays the wrapper the classic path uses", () => {
+ test("rows on success, [] for every other outcome", async () => {
+ serves(["alpha-chat"]);
+ expect(
+ (await buildDiscoveredModelRows(PROVIDER, DISPLAY_NAME, stubCatalog(CATALOG_ROWS))).map(
+ (r) => r.id
+ )
+ ).toEqual(["alpha-chat"]);
+
+ invalidateModelDiscovery();
+ rejectsWith(401);
+ expect(
+ await buildDiscoveredModelRows(PROVIDER, DISPLAY_NAME, stubCatalog(CATALOG_ROWS))
+ ).toEqual([]);
+ });
+
+ test("the failure is still RECORDED, so warnDiscoveryFailure can find it afterwards", async () => {
+ // The classic path throws the outcome away and asks the module-global map
+ // why the list was empty. Moving the classification must not break that.
+ rejectsWith(401);
+ await buildDiscoveredModelRows(PROVIDER, DISPLAY_NAME, stubCatalog(CATALOG_ROWS));
+
+ const stderr = spyOn(process.stderr, "write").mockImplementation(() => true);
+ try {
+ warnDiscoveryFailure(PROVIDER, DISPLAY_NAME, {
+ apiKeyEnvVar: ENV_VAR,
+ apiKeyUrl: KEY_URL,
+ });
+ expect(stderr.mock.calls.length).toBeGreaterThan(0);
+ expect(stderr.mock.calls.map(([c]) => String(c)).join("")).toContain("HTTP 401");
+ } finally {
+ stderr.mockRestore();
+ }
+ });
+});
+
+describe("formatDiscoveryFailureNotice", () => {
+ const def = { apiKeyEnvVar: ENV_VAR, apiKeyUrl: KEY_URL };
+
+ function failure(kind: DiscoveryFailureKind): DiscoveryFailure {
+ return {
+ kind,
+ provider: PROVIDER,
+ endpoint: "https://picker-outcome.invalid/v1/models",
+ status: kind === "unauthorized" || kind === "http-error" ? 401 : undefined,
+ detail: "upstream said no",
+ };
+ }
+
+ test.each(["unauthorized", "no-credentials"] as const)(
+ "%s earns the env var and the key URL — the two actionable kinds",
+ (kind) => {
+ const text = formatDiscoveryFailureNotice(DISPLAY_NAME, failure(kind), def).join("");
+
+ expect(text).toContain(DISPLAY_NAME);
+ expect(text).toContain(ENV_VAR);
+ expect(text).toContain(KEY_URL);
+ expect(text).toContain("Falling back to manual model entry.");
+ }
+ );
+
+ test.each(["http-error", "unreachable", "malformed"] as const)(
+ "%s omits credential guidance, because there is no credential step to take",
+ (kind) => {
+ const text = formatDiscoveryFailureNotice(DISPLAY_NAME, failure(kind), def).join("");
+
+ expect(text).toContain(DISPLAY_NAME);
+ expect(text).not.toContain(ENV_VAR);
+ expect(text).not.toContain(KEY_URL);
+ expect(text).toContain("Falling back to manual model entry.");
+ }
+ );
+
+ test("the three fallbacks produce three different final lines", () => {
+ const lines = (f: Parameters<typeof formatDiscoveryFailureNotice>[3]) =>
+ formatDiscoveryFailureNotice(DISPLAY_NAME, failure("unauthorized"), def, f).join("");
+
+ expect(lines("manual-entry")).toContain("Falling back to manual model entry.");
+ expect(lines("catalog")).toContain(
+ `Showing ${DISPLAY_NAME}'s cloud-catalog entries below — not its live roster.`
+ );
+ // "unknown" means nothing has decided yet, so it claims nothing.
+ expect(lines("unknown")).not.toContain("Falling back");
+ expect(lines("unknown")).not.toContain("cloud-catalog");
+ });
+
+ test("the default is byte-identical to what warnDiscoveryFailure writes to stderr", async () => {
+ // The coupling between the formatter and the sink, asserted rather than
+ // assumed: the classic path's wording must not drift when the TUI's does.
+ rejectsWith(401);
+ await buildDiscoveredModelRows(PROVIDER, DISPLAY_NAME, stubCatalog(null));
+
+ const stderr = spyOn(process.stderr, "write").mockImplementation(() => true);
+ let written: string;
+ try {
+ warnDiscoveryFailure(PROVIDER, DISPLAY_NAME, def);
+ written = stderr.mock.calls.map(([chunk]) => String(chunk)).join("");
+ } finally {
+ stderr.mockRestore();
+ }
+
+ const recorded: DiscoveryFailure = {
+ kind: "unauthorized",
+ provider: PROVIDER,
+ endpoint: "https://picker-outcome.invalid/v1/models",
+ status: 401,
+ detail: '{"error":"rejected"}',
+ };
+ expect(written).toBe(formatDiscoveryFailureNotice(DISPLAY_NAME, recorded, def).join(""));
+ });
+});
+
+describe("no rendered notice interpolates `undefined`", () => {
+ const KINDS: DiscoveryFailureKind[] = [
+ "no-credentials",
+ "unauthorized",
+ "http-error",
+ "unreachable",
+ "malformed",
+ "empty-roster",
+ ];
+
+ test("every kind × endpoint × status × detail × fallback", () => {
+ // The `empty-roster` records on the fetcher half carried no endpoint for
+ // years, so any copy that names one renders the literal string `undefined`
+ // to the user. Exhaustive rather than representative, because the optional
+ // fields are independent and a single missed guard is invisible in review.
+ let checked = 0;
+ for (const kind of KINDS) {
+ for (const endpoint of [undefined, "https://picker-outcome.invalid/v1/models"]) {
+ for (const status of [undefined, 401, 500]) {
+ for (const detail of [undefined, "", "upstream said no"]) {
+ const f: DiscoveryFailure = { kind, provider: PROVIDER, endpoint, status, detail };
+
+ expect(describeDiscoveryFailure(f)).not.toContain("undefined");
+
+ for (const fallback of ["manual-entry", "catalog", "unknown"] as const) {
+ for (const def of [
+ { apiKeyEnvVar: ENV_VAR, apiKeyUrl: KEY_URL },
+ { apiKeyEnvVar: "", apiKeyUrl: "" },
+ ]) {
+ const text = formatDiscoveryFailureNotice(DISPLAY_NAME, f, def, fallback).join("");
+ expect(text).not.toContain("undefined");
+ checked++;
+ }
+ }
+ }
+ }
+ }
+ }
+ expect(checked).toBe(KINDS.length * 2 * 3 * 3 * 3 * 2);
+ });
+});
+
+describe("toPickerRows — one chat-capability chokepoint for both doors", () => {
+ const row = (id: string): ModelInfo => ({
+ id,
+ name: id,
+ description: id,
+ provider: "test",
+ });
+
+ test("drops real non-chat ids", () => {
+ // `gpt-image-2.5-flare` is the model F1 observed being selected by pressing
+ // Enter twice at launch: the catalog paths applied no capability filter at
+ // all, only the live-discovery path did.
+ const dropped = [
+ "gpt-image-2.5-flare",
+ "text-embedding-3-large",
+ "whisper-1",
+ "dall-e-3",
+ "tts-1-hd",
+ "nomic-embed-text",
+ "bge-m3",
+ "gemini/*",
+ ];
+
+ expect(toPickerRows(dropped.map(row))).toEqual([]);
+ });
+
+ test("keeps real chat ids", () => {
+ const kept = [
+ "claude-opus-5",
+ "gpt-5.2-codex",
+ "gemini-3-pro",
+ "kimi-k3",
+ "deepseek-v3",
+ "llama3.2",
+ "MiniMax-M2",
+ ];
+
+ expect(
+ toPickerRows(kept.map(row))
+ .map((r) => r.id)
+ .sort()
+ ).toEqual([...kept].sort());
+ });
+
+ test("dedupes by id while filtering", () => {
+ expect(
+ toPickerRows([row("claude-opus-5"), row("claude-opus-5"), row("whisper-1")]).map((r) => r.id)
+ ).toEqual(["claude-opus-5"]);
+ });
+});
diff --git a/packages/cli/src/model-selector.ts b/packages/cli/src/model-selector.ts
index bfcc5eda..db791071 100644
--- a/packages/cli/src/model-selector.ts
+++ b/packages/cli/src/model-selector.ts
@@ -31,8 +31,10 @@ import {
} from "./providers/model-catalog.js";
import {
type DiscoveredModel,
+ type DiscoveryFailure,
+ type RosterOutcome,
describeDiscoveryFailure,
- discoverProviderModels,
+ discoverProviderRoster,
getDiscoveryFailure,
rankDiscoveredModels,
toRosterEntry,
@@ -436,6 +438,28 @@ function sortModelsNewestFirst(models: ModelInfo[]): ModelInfo[] {
return [...models].sort(compareByReleaseDateDesc);
}
+/**
+ * Catalog models → picker rows: drop what cannot serve a chat completion, then
+ * dedupe, then order newest-first.
+ *
+ * **A chokepoint, not a site fix.** Pressing Enter twice at launch selected
+ * `gpt-image-2.5-flare`, an image-generation model: `isChatCapable` was applied
+ * inside `buildDiscoveredModelOutcome` and nowhere else, so every catalog path —
+ * `searchModels`, `modelsByVendor`, the top-100 default list — applied no
+ * capability filter at all. The same class of leak has been patched
+ * twice before at the site where it was noticed (`probe-discovery.ts:498`, then
+ * `pplx-embed`, then `bge`), and recurred each time, because a list is made in
+ * more than one place. Every list either UI can render now returns through here.
+ *
+ * Honest limit: `isChatCapable` is name-based, so `gemini-3.5-transcribe` still
+ * gets through (`transcribe` is in none of its patterns). Adding a pattern has a
+ * real false-positive risk on model names, and the catalog's own modality field
+ * can answer it properly — that is a models-index issue, not a CLI regex.
+ */
+export function toPickerRows(models: ModelInfo[]): ModelInfo[] {
+ return sortModelsNewestFirst(dedupeModels(models.filter((m) => isChatCapable(m.id))));
+}
+
/**
* Get free models. Free model discovery used to come from OpenCode Zen
* (via models.dev), which has been removed. Free models now live in the
@@ -633,7 +657,7 @@ async function fetchPickerModels(
const vendorModels = await catalog.modelsByVendor(firebaseSlug);
const infos = dedupeByProviderSpec(
providerSlug,
- sortModelsNewestFirst(dedupeModels(vendorModels.map(catalogModelToModelInfo)))
+ toPickerRows(vendorModels.map(catalogModelToModelInfo))
);
if (!searchTerm) return infos;
const needle = searchTerm.toLowerCase();
@@ -642,10 +666,12 @@ async function fetchPickerModels(
if (searchTerm) {
const found = await catalog.searchModels(searchTerm, 100);
- return sortModelsNewestFirst(dedupeModels(found.map(catalogModelToModelInfo)));
+ return toPickerRows(found.map(catalogModelToModelInfo));
}
- return defaultModels;
+ // The default list too, and this is the branch F1 actually observed: two
+ // Enters at launch is "All providers" with no term, which lands here.
+ return toPickerRows(defaultModels);
}
/**
@@ -1173,7 +1199,7 @@ async function loadModelsForPickerProvider(
const vendorModels = await catalog.modelsByVendor(firebaseSlug);
return dedupeByProviderSpec(
providerValue,
- sortModelsNewestFirst(dedupeModels(vendorModels.map(catalogModelToModelInfo)))
+ toPickerRows(vendorModels.map(catalogModelToModelInfo))
);
} catch {
return [];
@@ -1280,6 +1306,63 @@ function describeOffer(offer: ModelOffer | undefined): string | undefined {
return `FREE until ${until}`;
}
+/**
+ * Which list the user is about to be shown instead of the live roster.
+ *
+ * The caller that writes the notice is not always the caller that knows this.
+ * `warnDiscoveryFailure` runs at the point discovery fails, BEFORE the
+ * catalog/free-text decision is taken further down `selectModelFromProvider`,
+ * so it can only state the default. A renderer that resolves both legs before
+ * drawing anything knows the real answer and says it.
+ *
+ * `"unknown"` emits no provenance line at all, which is the honest output when
+ * nothing has decided yet — better than naming a fallback that may not happen.
+ */
+export type FallbackTaken = "manual-entry" | "catalog" | "unknown";
+
+/**
+ * A discovery failure as the lines a presenter should show, newest line last.
+ *
+ * Pure: no I/O, no read of the module-global failure map. Split out of
+ * `warnDiscoveryFailure` so the same words can go to stderr (the classic
+ * inquirer path) and into render state (the OpenTUI picker, which must not
+ * write to a terminal it is drawing on). The wording is deliberately unchanged —
+ * it was measured against a real 401 and found to be complete; what was wrong
+ * was its presentation, not its content.
+ *
+ * Each string carries its own newlines, so a presenter that writes them
+ * verbatim reproduces today's stderr byte for byte.
+ */
+export function formatDiscoveryFailureNotice(
+ displayName: string,
+ failure: DiscoveryFailure,
+ def: Pick<ProviderDefinition, "apiKeyEnvVar" | "apiKeyUrl">,
+ fallback: FallbackTaken = "manual-entry"
+): string[] {
+ const lines = [
+ `\n⚠ ${displayName} could not list its models: ${describeDiscoveryFailure(failure)}\n`,
+ ];
+
+ // A credential problem is the one case with a concrete next step, so name the
+ // exact env var and where a key comes from. Naming the variable matters more
+ // than it looks: a provider's key is frequently shadowed by a stale value in
+ // the shell, and "check your API key" gives no clue which name to inspect.
+ if (failure.kind === "unauthorized" || failure.kind === "no-credentials") {
+ if (def.apiKeyEnvVar) {
+ lines.push(
+ ` Check ${def.apiKeyEnvVar} (a value in your shell overrides stored credentials).\n`
+ );
+ }
+ if (def.apiKeyUrl) lines.push(` Get a key: ${def.apiKeyUrl}\n`);
+ }
+
+ if (fallback === "manual-entry") lines.push(" Falling back to manual model entry.\n\n");
+ else if (fallback === "catalog") {
+ lines.push(` Showing ${displayName}'s cloud-catalog entries below — not its live roster.\n\n`);
+ }
+ return lines;
+}
+
/**
* Tell the user why a discovery provider offered no list, on stderr, before the
* picker degrades to the catalog / free-text path.
@@ -1291,6 +1374,12 @@ function describeOffer(offer: ModelOffer | undefined): string | undefined {
* `empty-roster` is deliberately silent: an endpoint that answers correctly
* with nothing chat-capable is not an error, and the free-text prompt that
* follows is the right affordance for it. Only actionable failures are named.
+ * (That judgement is right for stderr, where a notice scrolls past; a rendered
+ * panel can afford to say it in one dim row, and the picker does.)
+ *
+ * Reads the module-global failure map rather than taking a failure, because its
+ * call site has already thrown the outcome away. New callers should prefer
+ * `buildDiscoveredModelOutcome`, which carries the failure with it.
*
* Exported for unit tests.
*/
@@ -1302,60 +1391,199 @@ export function warnDiscoveryFailure(
const failure = getDiscoveryFailure(provider);
if (!failure || failure.kind === "empty-roster") return;
- process.stderr.write(
- `\n⚠ ${displayName} could not list its models: ${describeDiscoveryFailure(failure)}\n`
- );
+ // Default `fallback`, i.e. "Falling back to manual model entry." — which is
+ // not always what happens next (the catalog usually answers), but this call
+ // site runs before that is decided and cannot know. Correcting the string is
+ // a follow-up with a named trigger: when `selectModelClassic` is deleted,
+ // this function and the assertion on that sentence go with it.
+ for (const line of formatDiscoveryFailureNotice(displayName, failure, def)) {
+ process.stderr.write(line);
+ }
+}
- // A credential problem is the one case with a concrete next step, so name the
- // exact env var and where a key comes from. Naming the variable matters more
- // than it looks: a provider's key is frequently shadowed by a stale value in
- // the shell, and "check your API key" gives no clue which name to inspect.
- if (failure.kind === "unauthorized" || failure.kind === "no-credentials") {
- if (def.apiKeyEnvVar) {
- process.stderr.write(
- ` Check ${def.apiKeyEnvVar} (a value in your shell overrides stored credentials).\n`
- );
- }
- if (def.apiKeyUrl) process.stderr.write(` Get a key: ${def.apiKeyUrl}\n`);
+/**
+ * Roster → picker rows, as an injectable step.
+ *
+ * A seam, not a design: `collapseRoster` folding a non-empty roster to `[]` is
+ * the one state behind `PickerDiscoveryOutcome.collapsed-empty`, and the single
+ * shipped resolver cannot produce it (every entry lands in a group and every
+ * group yields a choice), so the variant is otherwise untestable. The
+ * alternative, `mock.module()` on the resolver registry, bleeds into sibling Bun
+ * test files and is banned here. Replace the property in a test and restore it;
+ * the same shape the discovery tests already use on `credentials.getRequestAuth`.
+ */
+export const _rosterCollapse = { collapse: collapseRoster };
+
+/**
+ * What one discovery provider's model list actually is — all five states that
+ * used to be the same empty array, plus the one where nothing was attempted.
+ *
+ * `buildDiscoveredModelRows` returned `[]` for a rejected API key, an
+ * unreachable endpoint, a genuinely empty roster, a roster where nothing was
+ * chat-capable, and a roster that collapsed to nothing — and its caller fell
+ * through to the cloud catalog for all of them, silently. The user's report was
+ * *"it just shows fewer model names, like the provider does not have any
+ * models"*: information destroyed at a return statement, which no amount of UI
+ * can recover. Hence a discriminated union produced where the information still
+ * exists.
+ *
+ * - `rows` is **non-empty by construction** — the type says so, and the three
+ * empty cases below exist precisely so it can.
+ * - `servedCount` / `chatCount` make a PARTIAL filter visible too: today the
+ * difference between "served 40" and "40 of which 12 are chat models" is
+ * discarded.
+ * - `fallbackRows` rides along on the four recoverable variants, resolved
+ * CONCURRENTLY with discovery rather than after it (§3.6 of the design): a
+ * serial second fetch would put the feature's worst latency on exactly the
+ * path the complaint is about. Empty when the catalog has nothing either, in
+ * which case the only remaining affordance is free-text entry.
+ * - `unsupported` is not a failure. ~25 pickable providers declare no
+ * `modelDiscovery`; for them the catalog list is the normal, correct UI and a
+ * notice would be noise on the majority case.
+ */
+export type PickerDiscoveryOutcome =
+ | { kind: "rows"; rows: [ModelInfo, ...ModelInfo[]]; servedCount: number; chatCount: number }
+ | { kind: "all-filtered"; servedCount: number; sampleIds: string[]; fallbackRows: ModelInfo[] }
+ | { kind: "collapsed-empty"; servedCount: number; chatCount: number; fallbackRows: ModelInfo[] }
+ | { kind: "empty-roster"; failure: DiscoveryFailure; fallbackRows: ModelInfo[] }
+ | { kind: "failed"; failure: DiscoveryFailure; notice: string[]; fallbackRows: ModelInfo[] }
+ | { kind: "unsupported"; reason: "no-descriptor" | "no-base-url" | "no-fetcher" };
+
+/**
+ * One discovery provider's list, with the reason when there isn't one.
+ *
+ * Starts both legs at once — the live roster and the cloud-catalog fallback —
+ * and returns one settled answer, so a view has one state and one affordance per
+ * provider instead of two spinners to reconcile. The catalog leg costs a lookup
+ * a healthy roster does not need; that is cheaper than doubling the wait on the
+ * failure path, and `catalog.modelsByVendor` caches.
+ */
+export async function buildDiscoveredModelOutcome(
+ provider: string,
+ displayName: string,
+ catalog: CatalogClient
+): Promise<PickerDiscoveryOutcome> {
+ const [rosterResult, fallbackResult] = await Promise.allSettled([
+ discoverProviderRoster(provider),
+ loadModelsForPickerProvider(provider, catalog),
+ ]);
+
+ const fallbackRows = fallbackResult.status === "fulfilled" ? fallbackResult.value : [];
+ // `discoverProviderRoster` never rejects by contract, but a contract is not a
+ // type: honour it rather than asserting it, so a future regression there shows
+ // up as a named failure instead of an unhandled rejection behind a renderer.
+ const roster: RosterOutcome =
+ rosterResult.status === "fulfilled"
+ ? rosterResult.value
+ : {
+ kind: "failed",
+ failure: {
+ kind: "unreachable",
+ provider,
+ detail: String((rosterResult.reason as Error)?.message ?? rosterResult.reason),
+ },
+ };
+
+ if (roster.kind === "unsupported") return { kind: "unsupported", reason: roster.reason };
+
+ if (roster.kind === "failed") {
+ const { failure } = roster;
+ // `empty-roster` is its own variant rather than a `failed` with a kind to
+ // switch on, because it is not an error: the endpoint answered. It renders
+ // in the NOTICE tier, visibly distinct from a rejected key.
+ if (failure.kind === "empty-roster") return { kind: "empty-roster", failure, fallbackRows };
+ const def = getProviderByName(provider);
+ const notice = formatDiscoveryFailureNotice(
+ displayName,
+ failure,
+ // A runtime custom endpoint may not be in the definition table at all;
+ // empty strings suppress the two guidance lines, which is right — there is
+ // no env var or key URL to name.
+ def ?? { apiKeyEnvVar: "", apiKeyUrl: "" },
+ fallbackRows.length > 0 ? "catalog" : "manual-entry"
+ );
+ return { kind: "failed", failure, notice, fallbackRows };
+ }
+
+ const served = rankDiscoveredModels(roster.models);
+ const servedCount = served.length;
+ const discovered = served.filter((m) => isChatCapable(m.id));
+ const chatCount = discovered.length;
+ if (chatCount === 0) {
+ // Served N, none of them chat-capable. Invisible today, and self-explaining
+ // only if the ids come with it — they are usually embeddings or wildcard
+ // routes, which a reader recognises at a glance.
+ return {
+ kind: "all-filtered",
+ servedCount,
+ sampleIds: served
+ .filter((m) => !isChatCapable(m.id))
+ .slice(0, 3)
+ .map((m) => m.id),
+ fallbackRows,
+ };
}
- process.stderr.write(" Falling back to manual model entry.\n\n");
+
+ const [head, ...tail] = buildRowsFromDiscovered(provider, displayName, discovered, fallbackRows);
+ if (head === undefined) {
+ // Unreachable through the one shipped resolver, and deliberately still
+ // modelled: `{kind:"rows", rows: []}` would be an empty panel with no
+ // explanation, which is the exact defect class this type removes. Destructured
+ // rather than length-checked so the non-empty tuple needs no cast to assert.
+ return { kind: "collapsed-empty", servedCount, chatCount, fallbackRows };
+ }
+ return { kind: "rows", rows: [head, ...tail], servedCount, chatCount };
}
+/**
+ * The picker rows for a provider's live roster, or `[]` for any of the six
+ * reasons there isn't one.
+ *
+ * A wrapper over {@link buildDiscoveredModelOutcome} since the outcome type
+ * landed. The classic inquirer path keeps using it and keeps asking
+ * `warnDiscoveryFailure` why the list was empty afterwards — which still works,
+ * because every failure is still recorded in `model-discovery.ts`'s map.
+ */
export async function buildDiscoveredModelRows(
provider: string,
displayName: string,
catalog: CatalogClient
): Promise<ModelInfo[]> {
- const discovered = rankDiscoveredModels(await discoverProviderModels(provider)).filter((m) =>
- isChatCapable(m.id)
- );
- if (discovered.length === 0) return [];
+ const outcome = await buildDiscoveredModelOutcome(provider, displayName, catalog);
+ return outcome.kind === "rows" ? outcome.rows : [];
+}
+/**
+ * Chat-capable discovered models → picker rows. Pure; no I/O.
+ *
+ * `catalogRows` is the vendor catalog's list for this provider, already fetched
+ * by the caller. A per-token discovery provider should show the real rate, and
+ * neither the live endpoint nor the slim catalog reports one — so the price
+ * comes from there. Flat-rate providers (every discovery provider today) ignore
+ * it entirely.
+ */
+function buildRowsFromDiscovered(
+ provider: string,
+ displayName: string,
+ discovered: DiscoveredModel[],
+ catalogRows: ModelInfo[]
+): ModelInfo[] {
const subscription = isSubscriptionProvider(provider);
const local = getProviderByName(provider)?.isLocal === true;
// Neither a flat-rate plan nor a local daemon charges per token, and the
// vendor catalog has nothing to say about either — Firebase does not list a
// model someone pulled onto their own machine.
const flatRate = subscription || local;
- // A per-token discovery provider should show the real rate; the live endpoint
- // doesn't report one and the slim catalog carries no prices, so ask the
- // vendor catalog. Skipped for flat-rate providers, which is every discovery
- // provider today, so nothing pays for this lookup.
const pricingById = flatRate
? new Map<string, ModelInfo["pricing"]>()
- : new Map(
- (await loadModelsForPickerProvider(provider, catalog)).map((m) => [
- m.id.toLowerCase(),
- m.pricing,
- ])
- );
+ : new Map(catalogRows.map((m) => [m.id.toLowerCase(), m.pricing]));
// Fold variant explosions into the rows a human actually picks. Identity for
// every provider without a resolver, so this is a no-op except for Devin,
// where 167 served uids are ~39 real choices multiplied out by reasoning tier
// and speed premium. The chosen id is always a real wire id, so it still
// round-trips through buildExplicitModelSpec and argv unchanged.
- const choices = collapseRoster(provider, discovered.map(toRosterEntry));
+ const choices = _rosterCollapse.collapse(provider, discovered.map(toRosterEntry));
const discoveredById = new Map(discovered.map((m) => [m.id, m]));
// The live endpoint decides WHICH models appear (entitlement) and overrides
diff --git a/packages/cli/src/providers/model-discovery-builtins.ts b/packages/cli/src/providers/model-discovery-builtins.ts
index c9232330..cd092045 100644
--- a/packages/cli/src/providers/model-discovery-builtins.ts
+++ b/packages/cli/src/providers/model-discovery-builtins.ts
@@ -18,26 +18,77 @@
* property the original dynamic `import()` calls existed to protect.
*/
-import type { DiscoveredModel } from "./model-discovery.js";
+import type { FetcherResult } from "./model-discovery.js";
import { registerModelDiscoveryFetcher } from "./model-discovery.js";
+/**
+ * Upstream error text as one readable line.
+ *
+ * A private copy rather than an import: `model-discovery.ts`'s `oneLine` is
+ * module-private there, and exporting it to share four lines would widen that
+ * module's surface for no gain.
+ */
+function oneLine(text: string, max = 200): string {
+ const flat = text.replace(/\s+/g, " ").trim();
+ return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
/**
* Devin's roster is capability ∩ entitlement over two protobuf rpcs.
*
* Carries the full variant metadata, not just id/name/window: the picker folds
* ~170 uids into ~42 rows and needs the group label, the cost multiplier, the
* promo and the vendor's own default flag to do it.
+ *
+ * **Honest limit on the classification.** `getServedDevinModels` catches its own
+ * rpc errors and returns `rosterCache ?? []` (devin-models.ts:411-414), and
+ * `postUnary` answers `null` rather than throwing, so a failed rpc still arrives
+ * here as an empty list and is reported as `empty-roster`. What this DOES
+ * distinguish is the two states that are knowable without touching that module:
+ * no credential at all, and a throw from anywhere in the chain.
*/
-async function fetchDevinRoster(): Promise<DiscoveredModel[]> {
- const { getServedDevinModels } = await import("./devin/devin-models.js");
- const served = await getServedDevinModels();
- if (served.length === 0) return [];
+async function fetchDevinRoster(): Promise<FetcherResult> {
+ let endpoint: string | undefined;
+ try {
+ const { readDevinApiKey, readDevinServerUrl } = await import("./devin/devin-credentials.js");
+ endpoint = readDevinServerUrl();
+ // A logged-out account is a CREDENTIAL problem, and it is the kind that
+ // earns a "how to fix it" line. Reporting it as an empty roster says the
+ // subscription serves no models, which is a claim about Devin rather than
+ // about this machine.
+ if (!readDevinApiKey()) {
+ return {
+ kind: "failed",
+ failure: {
+ kind: "no-credentials",
+ endpoint,
+ // The definition's own `apiKeyDescription`, verbatim: there is no
+ // `claudish login devin` to point at — the token is the Devin CLI's,
+ // and claudish only reads it.
+ detail: "no Devin CLI session token (~/.local/share/devin/credentials.toml)",
+ },
+ };
+ }
+
+ const { getServedDevinModels } = await import("./devin/devin-models.js");
+ const served = await getServedDevinModels();
+ if (served.length === 0) return { kind: "models", models: [], endpoint };
- const { devinRosterEntry } = await import("./model-resolvers/devin.js");
- return served.map((model) => {
- const { wireId, ...rest } = devinRosterEntry(model);
- return { id: wireId, ...rest };
- });
+ const { devinRosterEntry } = await import("./model-resolvers/devin.js");
+ return {
+ kind: "models",
+ endpoint,
+ models: served.map((model) => {
+ const { wireId, ...rest } = devinRosterEntry(model);
+ return { id: wireId, ...rest };
+ }),
+ };
+ } catch (err: unknown) {
+ return {
+ kind: "failed",
+ failure: { kind: "unreachable", endpoint, detail: oneLine(String(err)) },
+ };
+ }
}
/**
@@ -66,45 +117,94 @@ function isUndeclaredEditorInternal(id: string): boolean {
* in the catalog. `resolveDiscoveredContextLength` already prefers a discovered
* window over the catalog; this is what gives it one to prefer.
*/
-async function fetchAntigravityRoster(): Promise<DiscoveredModel[]> {
- const { getValidAntigravityAccessToken } = await import("../auth/antigravity-token.js");
- const { setupAntigravityUser, getServedAntigravityModels } = await import(
- "../auth/antigravity-user.js"
- );
- const token = await getValidAntigravityAccessToken();
- if (!token) return [];
+async function fetchAntigravityRoster(): Promise<FetcherResult> {
+ let endpoint: string | undefined;
+ try {
+ const { getValidAntigravityAccessToken } = await import("../auth/antigravity-token.js");
+ const { setupAntigravityUser, getServedAntigravityModels, antigravityHost } = await import(
+ "../auth/antigravity-user.js"
+ );
+ endpoint = `${antigravityHost()}/v1internal:fetchAvailableModels`;
+ const token = await getValidAntigravityAccessToken();
+ // No token is exactly "logged out", which is one of the two kinds that earns
+ // the env-var / key-URL guidance. It used to read as an empty roster, i.e.
+ // "your subscription serves nothing".
+ if (!token) {
+ return {
+ kind: "failed",
+ failure: {
+ kind: "no-credentials",
+ endpoint,
+ detail: "not signed in — run `claudish login antigravity`",
+ },
+ };
+ }
- const { projectId } = await setupAntigravityUser(token);
- const { servedIds, meta, excludedIds } = await getServedAntigravityModels(token, projectId);
- // Declared first, guess second. `excludedIds` is the backend's own verdict —
- // internal flags, per-feature role bindings, and retired ids (which look
- // entirely normal but answer 400).
- const declaredExcluded = excludedIds ?? new Set<string>();
- const selectable = servedIds.filter(
- (id) => !declaredExcluded.has(id) && !isUndeclaredEditorInternal(id)
- );
- return selectable.map((id) => {
- const m = meta[id];
- // contextWindow is left UNSET when the backend reported none
- // (gemini-3.1-flash-image does), so the catalog still gets its turn rather
- // than the row rendering a fabricated 0 as "N/A".
- // Every id here is a tuned variant (`-high`, `-tiered`) the catalog does not
- // carry; see `ignoreCatalogReleaseDate` for the ordering this protects.
- return m?.contextWindow
- ? { id, contextWindow: m.contextWindow, ignoreCatalogReleaseDate: true }
- : { id, ignoreCatalogReleaseDate: true };
- });
+ const { projectId } = await setupAntigravityUser(token);
+ const { servedIds, meta, excludedIds } = await getServedAntigravityModels(token, projectId);
+ // Declared first, guess second. `excludedIds` is the backend's own verdict —
+ // internal flags, per-feature role bindings, and retired ids (which look
+ // entirely normal but answer 400).
+ const declaredExcluded = excludedIds ?? new Set<string>();
+ const selectable = servedIds.filter(
+ (id) => !declaredExcluded.has(id) && !isUndeclaredEditorInternal(id)
+ );
+ return {
+ kind: "models",
+ endpoint,
+ models: selectable.map((id) => {
+ const m = meta[id];
+ // contextWindow is left UNSET when the backend reported none
+ // (gemini-3.1-flash-image does), so the catalog still gets its turn rather
+ // than the row rendering a fabricated 0 as "N/A".
+ // Every id here is a tuned variant (`-high`, `-tiered`) the catalog does not
+ // carry; see `ignoreCatalogReleaseDate` for the ordering this protects.
+ return m?.contextWindow
+ ? { id, contextWindow: m.contextWindow, ignoreCatalogReleaseDate: true }
+ : { id, ignoreCatalogReleaseDate: true };
+ }),
+ };
+ } catch (err: unknown) {
+ return {
+ kind: "failed",
+ failure: { kind: "unreachable", endpoint, detail: oneLine(String(err)) },
+ };
+ }
}
-/** Ollama's daemon speaks its own listing shape and carries capability data no OpenAI list has. */
-async function fetchOllamaRoster(): Promise<DiscoveredModel[]> {
- const { fetchOllamaModels } = await import("./ollama-discovery.js");
- const installed = await fetchOllamaModels({ enrichCapabilities: false });
- return installed.map((model) => ({
- id: model.name,
- displayName: model.name,
- supportsTools: model.supportsTools,
- }));
+/**
+ * Ollama's daemon speaks its own listing shape and carries capability data no OpenAI list has.
+ *
+ * `throwOnError` is what makes "the daemon is not running" distinguishable from
+ * "the daemon is running and nothing is pulled". `fetchOllamaModels` is
+ * documented as never throwing, and every other caller still gets that; only
+ * this one opts in, because only this one has somewhere to report the
+ * difference. Both states used to be `empty-roster`, so a stopped daemon read as
+ * "this provider has no models" — the complaint, restated.
+ */
+async function fetchOllamaRoster(): Promise<FetcherResult> {
+ const { fetchOllamaModels, ollamaBaseUrl } = await import("./ollama-discovery.js");
+ const endpoint = `${ollamaBaseUrl()}/api/tags`;
+ try {
+ const installed = await fetchOllamaModels({
+ enrichCapabilities: false,
+ throwOnError: true,
+ });
+ return {
+ kind: "models",
+ endpoint,
+ models: installed.map((model) => ({
+ id: model.name,
+ displayName: model.name,
+ supportsTools: model.supportsTools,
+ })),
+ };
+ } catch (err: unknown) {
+ return {
+ kind: "failed",
+ failure: { kind: "unreachable", endpoint, detail: oneLine(String(err)) },
+ };
+ }
}
registerModelDiscoveryFetcher("devin-connect", fetchDevinRoster);
diff --git a/packages/cli/src/providers/model-discovery-roster.test.ts b/packages/cli/src/providers/model-discovery-roster.test.ts
new file mode 100644
index 00000000..8dc6d0ac
--- /dev/null
+++ b/packages/cli/src/providers/model-discovery-roster.test.ts
@@ -0,0 +1,360 @@
+/**
+ * `discoverProviderRoster` — the discriminated outcome behind the empty array.
+ *
+ * `discoverProviderModels` answers `[]` for six structurally different things,
+ * and its callers could not tell them apart. These tests pin which outcome each
+ * condition produces, and in particular the three the fetcher half could not
+ * express at all before: a failing fetcher, a reachable-but-empty one, and a
+ * declared format nothing claims.
+ *
+ * Offline by construction: `globalThis.fetch` and `credentials.getRequestAuth`
+ * are replaced directly rather than through `mock.module()`, which bleeds into
+ * sibling Bun test files.
+ *
+ * Run: bun test packages/cli/src/providers/model-discovery-roster.test.ts
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { credentials } from "../auth/credentials/authority.js";
+import {
+ type FetcherResult,
+ type ModelDiscoveryDescriptor,
+ discoverProviderModels,
+ discoverProviderRoster,
+ getDiscoveryFailure,
+ invalidateModelDiscovery,
+ registerModelDiscoveryFetcher,
+} from "./model-discovery.js";
+import type { ProviderDefinition } from "./provider-definitions.js";
+import { clearRuntimeRegistry, registerRuntimeProvider } from "./runtime-providers.js";
+
+const realFetch = globalThis.fetch;
+const realGetRequestAuth = credentials.getRequestAuth;
+
+/**
+ * A provider definition that can never reach the network by accident: its host
+ * is `.invalid`, it builds no handler, and every test that lets it get as far as
+ * a request stubs `fetch` first.
+ */
+function defineProvider(
+ name: string,
+ overrides: Partial<ProviderDefinition> = {}
+): ProviderDefinition {
+ return {
+ name,
+ displayName: `Roster Test (${name})`,
+ transport: "openai",
+ baseUrl: "https://roster-test.invalid",
+ apiPath: "/v1/chat/completions",
+ apiKeyEnvVar: "ROSTER_TEST_API_KEY",
+ apiKeyDescription: "Offline test key",
+ apiKeyUrl: "https://roster-test.invalid/key",
+ shortcuts: [],
+ legacyPrefixes: [],
+ modelDiscovery: { path: "/v1/models", format: "openai-models-list" },
+ createHandler: { kind: "none", reason: "virtual", note: "Offline test fixture" },
+ isDirectApi: true,
+ ...overrides,
+ };
+}
+
+/** A format name no shipped provider declares, so the registry stays honest. */
+function testFormat(name: string): ModelDiscoveryDescriptor["format"] {
+ return name as ModelDiscoveryDescriptor["format"];
+}
+
+function stubResponse(body: string, status = 200): void {
+ globalThis.fetch = mock(
+ async () => new Response(body, { status, headers: { "Content-Type": "application/json" } })
+ ) as unknown as typeof fetch;
+}
+
+beforeEach(() => {
+ invalidateModelDiscovery();
+ clearRuntimeRegistry();
+ credentials.getRequestAuth = mock(async () => ({
+ headers: { Authorization: "Bearer offline-test-token" },
+ }));
+ globalThis.fetch = mock(async () => {
+ throw new Error("Unexpected fetch call");
+ }) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+ invalidateModelDiscovery();
+ clearRuntimeRegistry();
+ globalThis.fetch = realFetch;
+ credentials.getRequestAuth = realGetRequestAuth;
+});
+
+describe("discoverProviderRoster — the GET half", () => {
+ test("a non-empty roster is `served`, and `served.models` is never empty", async () => {
+ stubResponse(JSON.stringify({ data: [{ id: "k3", context_length: 1_048_576 }] }));
+
+ const outcome = await discoverProviderRoster("kimi-coding");
+
+ expect(outcome.kind).toBe("served");
+ if (outcome.kind !== "served") throw new Error("unreachable");
+ expect(outcome.models.map((m) => m.id)).toEqual(["k3"]);
+ expect(outcome.models.length).toBeGreaterThan(0);
+ expect(getDiscoveryFailure("kimi-coding")).toBeUndefined();
+ });
+
+ test.each([
+ [401, "unauthorized"],
+ [403, "unauthorized"],
+ [500, "http-error"],
+ [404, "http-error"],
+ ] as const)("HTTP %i is failed{%s}", async (status, kind) => {
+ stubResponse(JSON.stringify({ error: "rejected" }), status);
+
+ const outcome = await discoverProviderRoster("kimi-coding");
+
+ expect(outcome).toMatchObject({
+ kind: "failed",
+ failure: { kind, provider: "kimi-coding", status },
+ });
+ });
+
+ test("a fetch rejection is failed{unreachable} carrying the message", async () => {
+ globalThis.fetch = mock(async () => {
+ throw new Error("Offline");
+ }) as unknown as typeof fetch;
+
+ expect(await discoverProviderRoster("kimi-coding")).toMatchObject({
+ kind: "failed",
+ failure: { kind: "unreachable", provider: "kimi-coding", detail: "Offline" },
+ });
+ });
+
+ test("a non-JSON 200 is failed{malformed}", async () => {
+ globalThis.fetch = mock(
+ async () => new Response("{not-json", { status: 200 })
+ ) as unknown as typeof fetch;
+
+ expect(await discoverProviderRoster("kimi-coding")).toMatchObject({
+ kind: "failed",
+ failure: { kind: "malformed", provider: "kimi-coding" },
+ });
+ });
+
+ test("an empty data array is failed{empty-roster}, not `served` with []", async () => {
+ stubResponse(JSON.stringify({ data: [] }));
+
+ const outcome = await discoverProviderRoster("kimi-coding");
+
+ expect(outcome).toMatchObject({
+ kind: "failed",
+ failure: { kind: "empty-roster", provider: "kimi-coding" },
+ });
+ // The GET half has always had a URL to name, and still does.
+ if (outcome.kind !== "failed") throw new Error("unreachable");
+ expect(outcome.failure.endpoint).toContain("/v1/models");
+ });
+
+ test("blank credentials are failed{no-credentials} without a request", async () => {
+ const fetchMock = mock(async () => new Response("should not be called"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+ credentials.getRequestAuth = mock(async () => ({ headers: { authorization: " " } }));
+
+ expect(await discoverProviderRoster("kimi-coding")).toMatchObject({
+ kind: "failed",
+ failure: { kind: "no-credentials", provider: "kimi-coding" },
+ });
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+});
+
+describe("discoverProviderRoster — `unsupported` is not a failure", () => {
+ test.each(["openrouter", "not-a-real-provider"])(
+ "%s declares no discovery, so nothing is attempted or recorded",
+ async (provider) => {
+ const fetchMock = mock(async () => new Response("should not be called"));
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+ expect(await discoverProviderRoster(provider)).toEqual({
+ kind: "unsupported",
+ reason: "no-descriptor",
+ });
+ expect(fetchMock).not.toHaveBeenCalled();
+ // Nothing to explain to the user, so nothing is recorded for the classic
+ // path's warning to pick up either.
+ expect(getDiscoveryFailure(provider)).toBeUndefined();
+ }
+ );
+
+ test("a declared descriptor with no resolvable base URL is unsupported{no-base-url}", async () => {
+ const provider = defineProvider("roster-no-base-url-test", {
+ baseUrl: "",
+ baseUrlEnvVars: [],
+ });
+ registerRuntimeProvider(provider);
+
+ expect(await discoverProviderRoster(provider.name)).toEqual({
+ kind: "unsupported",
+ reason: "no-base-url",
+ });
+ expect(getDiscoveryFailure(provider.name)).toBeUndefined();
+ });
+
+ test("a declared format nothing claims is unsupported{no-fetcher}, not an empty roster", async () => {
+ // This is a PACKAGING bug — a definition opted into a format whose owner was
+ // never bundled. It used to be recorded as `empty-roster`, i.e. as a claim
+ // about the user's subscription.
+ const provider = defineProvider("roster-unclaimed-format-test", {
+ modelDiscovery: { path: "", format: testFormat("roster-unclaimed-format") },
+ });
+ registerRuntimeProvider(provider);
+
+ expect(await discoverProviderRoster(provider.name)).toEqual({
+ kind: "unsupported",
+ reason: "no-fetcher",
+ });
+ expect(getDiscoveryFailure(provider.name)).toBeUndefined();
+ });
+});
+
+describe("discoverProviderRoster — the fetcher half can finally classify", () => {
+ test("a fetcher reporting failure surfaces as failed with ITS kind, not empty-roster", async () => {
+ const format = testFormat("roster-failing-fetcher");
+ registerModelDiscoveryFetcher(format, async (): Promise<FetcherResult> => {
+ return {
+ kind: "failed",
+ failure: {
+ kind: "unreachable",
+ endpoint: "http://localhost:11434/api/tags",
+ detail: "connect ECONNREFUSED",
+ },
+ };
+ });
+ const provider = defineProvider("roster-failing-fetcher-test", {
+ modelDiscovery: { path: "", format },
+ });
+ registerRuntimeProvider(provider);
+
+ const outcome = await discoverProviderRoster(provider.name);
+
+ expect(outcome).toMatchObject({
+ kind: "failed",
+ failure: {
+ kind: "unreachable",
+ // The caller fills in the provider — the fetcher cannot know its own
+ // registration name.
+ provider: provider.name,
+ endpoint: "http://localhost:11434/api/tags",
+ detail: "connect ECONNREFUSED",
+ },
+ });
+ expect(getDiscoveryFailure(provider.name)?.kind).toBe("unreachable");
+ });
+
+ test("a fetcher reporting no-credentials earns the credential kind", async () => {
+ const format = testFormat("roster-logged-out-fetcher");
+ registerModelDiscoveryFetcher(format, async () => ({
+ kind: "failed" as const,
+ failure: { kind: "no-credentials" as const, detail: "no OAuth token" },
+ }));
+ registerRuntimeProvider(
+ defineProvider("roster-logged-out-test", { modelDiscovery: { path: "", format } })
+ );
+
+ expect(await discoverProviderRoster("roster-logged-out-test")).toMatchObject({
+ kind: "failed",
+ failure: { kind: "no-credentials", provider: "roster-logged-out-test" },
+ });
+ });
+
+ test("a reachable-but-empty fetcher gives empty-roster WITH the endpoint it asked", async () => {
+ const format = testFormat("roster-empty-fetcher");
+ registerModelDiscoveryFetcher(format, async () => ({
+ kind: "models" as const,
+ models: [],
+ endpoint: "http://localhost:11434/api/tags",
+ }));
+ registerRuntimeProvider(
+ defineProvider("roster-empty-fetcher-test", { modelDiscovery: { path: "", format } })
+ );
+
+ expect(await discoverProviderRoster("roster-empty-fetcher-test")).toEqual({
+ kind: "failed",
+ failure: {
+ kind: "empty-roster",
+ provider: "roster-empty-fetcher-test",
+ // Before `FetcherResult`, this half recorded empty-roster with NO
+ // endpoint, so any copy naming one rendered the literal `undefined`.
+ endpoint: "http://localhost:11434/api/tags",
+ },
+ });
+ });
+
+ test("a fetcher returning models is served", async () => {
+ const format = testFormat("roster-serving-fetcher");
+ registerModelDiscoveryFetcher(format, async () => ({
+ kind: "models" as const,
+ models: [{ id: "llama3.2", supportsTools: true }],
+ endpoint: "http://localhost:11434/api/tags",
+ }));
+ registerRuntimeProvider(
+ defineProvider("roster-serving-fetcher-test", { modelDiscovery: { path: "", format } })
+ );
+
+ expect(await discoverProviderRoster("roster-serving-fetcher-test")).toEqual({
+ kind: "served",
+ models: [{ id: "llama3.2", supportsTools: true }],
+ });
+ });
+
+ test("NEVER REJECTS: a throwing fetcher resolves to failed{unreachable}", async () => {
+ const format = testFormat("roster-throwing-fetcher");
+ registerModelDiscoveryFetcher(format, async () => {
+ throw new Error("protobuf decode blew up");
+ });
+ registerRuntimeProvider(
+ defineProvider("roster-throwing-test", { modelDiscovery: { path: "", format } })
+ );
+
+ // `.resolves` is the assertion, not a convenience: before the wrapping try,
+ // this rejection propagated out of the picker and, behind a live renderer
+ // with no stderr, would leave a progress indicator running forever.
+ await expect(discoverProviderRoster("roster-throwing-test")).resolves.toMatchObject({
+ kind: "failed",
+ failure: {
+ kind: "unreachable",
+ provider: "roster-throwing-test",
+ detail: "protobuf decode blew up",
+ },
+ });
+ });
+});
+
+describe("discoverProviderModels stays the fail-soft wrapper", () => {
+ test.each([
+ ["served", JSON.stringify({ data: [{ id: "k3" }] }), 200, ["k3"]],
+ ["failed", JSON.stringify({ error: "nope" }), 401, []],
+ ["empty-roster", JSON.stringify({ data: [] }), 200, []],
+ ] as const)("%s → the models or []", async (_label, body, status, ids) => {
+ stubResponse(body, status);
+
+ expect((await discoverProviderModels("kimi-coding")).map((m) => m.id)).toEqual([...ids]);
+ });
+
+ test("unsupported → []", async () => {
+ expect(await discoverProviderModels("openrouter")).toEqual([]);
+ });
+
+ test("both entry points share ONE cache, so asking twice costs one request", async () => {
+ let calls = 0;
+ globalThis.fetch = mock(async () => {
+ calls++;
+ return new Response(JSON.stringify({ data: [{ id: `model-${calls}` }] }), { status: 200 });
+ }) as unknown as typeof fetch;
+
+ const first = await discoverProviderRoster("kimi-coding");
+ const second = await discoverProviderModels("kimi-coding");
+
+ expect(calls).toBe(1);
+ expect(first).toMatchObject({ kind: "served" });
+ expect(second.map((m) => m.id)).toEqual(["model-1"]);
+ });
+});
diff --git a/packages/cli/src/providers/model-discovery-seam.test.ts b/packages/cli/src/providers/model-discovery-seam.test.ts
index b5cc35b9..f251bfa2 100644
--- a/packages/cli/src/providers/model-discovery-seam.test.ts
+++ b/packages/cli/src/providers/model-discovery-seam.test.ts
@@ -1,4 +1,5 @@
import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import type { ModelDiscoveryFetcher } from "./model-discovery.js";
import { getModelDiscoveryFetcher, registerModelDiscoveryFetcher } from "./model-discovery.js";
const realFetch = globalThis.fetch;
@@ -15,8 +16,11 @@ afterEach(() => {
describe("model discovery fetcher registration", () => {
test("returns the registered fetcher and lets the last writer win", () => {
- const firstFetcher = async () => [];
- const replacementFetcher = async () => [{ id: "replacement-model" }];
+ const firstFetcher: ModelDiscoveryFetcher = async () => ({ kind: "models", models: [] });
+ const replacementFetcher: ModelDiscoveryFetcher = async () => ({
+ kind: "models",
+ models: [{ id: "replacement-model" }],
+ });
registerModelDiscoveryFetcher("test-format", firstFetcher);
expect(getModelDiscoveryFetcher("test-format")).toBe(firstFetcher);
diff --git a/packages/cli/src/providers/model-discovery.ts b/packages/cli/src/providers/model-discovery.ts
index db6e5b41..b7879a0c 100644
--- a/packages/cli/src/providers/model-discovery.ts
+++ b/packages/cli/src/providers/model-discovery.ts
@@ -15,8 +15,11 @@
* and grandfathered, but the endpoint always reports what the key can do now.
*
* Design rules:
- * - **Fail-soft.** Every failure path returns an empty list. Discovery is an
- * enhancement; it must never block a launch or a picker.
+ * - **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. `discoverProviderRoster` is the same work
+ * reported as a {@link RosterOutcome}, 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 —
@@ -133,12 +136,34 @@ export interface ModelDiscoveryDescriptor {
}
/**
- * A roster fetcher for a format this module does not know how to speak.
+ * What a registered fetcher answers with.
*
- * Returning `[]` means "asked, got nothing" — the caller records an
- * `empty-roster` failure. Throwing is also fine; the caller converts it.
+ * 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-roster` 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 roster.
+ * - `models` with `[]` is a genuine empty roster — and `endpoint` is what makes
+ * it sayable: the notice can finally name the URL that answered.
+ * - `failed` carries any of the six kinds. `provider` is filled in by the
+ * caller, which is the only place that knows it.
+ *
+ * Throwing is still fine: {@link discoverProviderRoster} maps a rejection to
+ * `unreachable` and never rejects itself.
*/
-export type ModelDiscoveryFetcher = (providerName: string) => Promise<DiscoveredModel[]>;
+export type FetcherResult =
+ | { kind: "models"; models: DiscoveredModel[]; endpoint?: string }
+ | { kind: "failed"; failure: Omit<DiscoveryFailure, "provider"> };
+
+/** A roster 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>();
@@ -215,6 +240,38 @@ export interface DiscoveryFailure {
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 roster. **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 six {@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 roster fact — which is why it is here
+ * rather than folded into `empty-roster` as it used to be.
+ */
+export type RosterOutcome =
+ | { kind: "served"; models: DiscoveredModel[] }
+ | { kind: "failed"; failure: DiscoveryFailure }
+ | { kind: "unsupported"; reason: "no-descriptor" | "no-base-url" | "no-fetcher" };
+
/**
* Last failure per provider.
*
@@ -226,10 +283,17 @@ export interface DiscoveryFailure {
*/
const _failures = new Map<string, DiscoveryFailure>();
-function recordFailure(failure: DiscoveryFailure): DiscoveredModel[] {
+/**
+ * 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): RosterOutcome {
_failures.set(failure.provider, failure);
log(`[model-discovery:${failure.provider}] ${describeDiscoveryFailure(failure)}`);
- return [];
+ return { kind: "failed", failure };
}
/**
@@ -274,13 +338,21 @@ 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 ${status})${at}${because}`;
+ return `the API key was rejected${http}${at}${because}`;
case "http-error":
- return `the model list returned HTTP ${status}${at}${because}`;
+ 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":
@@ -375,52 +447,91 @@ function parseOpenAIModelsList(body: unknown): DiscoveredModel[] {
}
/**
- * List the models this provider serves for the CURRENT credentials.
+ * The non-GET half: a format this module cannot speak itself, served by a
+ * registered fetcher.
*
- * Returns [] when the provider declares no `modelDiscovery`, has no usable
- * credentials, or the endpoint is unreachable/malformed — callers fall back to
- * the cloud catalog.
+ * Devin's roster 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.
*/
-export async function discoverProviderModels(providerName: string): Promise<DiscoveredModel[]> {
- const cached = _cache.get(providerName);
- if (cached && cached.expiresAt > Date.now()) return cached.models;
-
- const def = getProviderByName(providerName);
- const descriptor = def?.modelDiscovery;
- if (!def || !descriptor) return [];
-
- // Devin's roster is not a GET — it is two protobuf rpcs (capability ∩
- // entitlement), owned by the module that speaks that wire. The import is
- // DYNAMIC to keep the codec off the cold-start path and out of a static
- // cycle. (If a third such provider ever appears, replace this branch with a
- // `registerModelDiscoveryFetcher(name, fn)` seam — not worth it for one.)
- // Formats this module cannot speak itself are served by registered fetchers.
- // It deliberately knows NONE of them by name: the builtin bundle is imported
- // on first miss, which both inverts the dependency and keeps the protobuf
- // codec and the Antigravity OAuth path off the cold-start path.
- if (descriptor.format !== "openai-models-list") {
- let fetcher = getModelDiscoveryFetcher(descriptor.format);
+async function discoverViaFetcher(providerName: string, format: string): Promise<RosterOutcome> {
+ let result: FetcherResult;
+ try {
+ let fetcher = getModelDiscoveryFetcher(format);
if (!fetcher) {
await import("./model-discovery-builtins.js");
- fetcher = getModelDiscoveryFetcher(descriptor.format);
+ fetcher = getModelDiscoveryFetcher(format);
}
if (!fetcher) {
- // A declared format nothing claims. Report it as a roster miss rather
- // than falling through to the GET path, which would hit a bogus URL.
- return recordFailure({ kind: "empty-roster", provider: providerName });
+ // 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 roster, so it is `unsupported`, not the
+ // `empty-roster` 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" };
}
- const models = await fetcher(providerName);
- if (models.length === 0) {
- return recordFailure({ kind: "empty-roster", provider: providerName });
- }
- _failures.delete(providerName);
- log(`[model-discovery:${providerName}] discovered ${models.length} models`);
- _cache.set(providerName, { models, expiresAt: Date.now() + CACHE_TTL_MS });
- return models;
+ 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-roster",
+ 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 RosterOutcome}.
+ *
+ * **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 discoverProviderRoster(providerName: string): Promise<RosterOutcome> {
+ 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) return [];
+ if (!baseUrl) return { kind: "unsupported", reason: "no-base-url" };
const endpoint = `${baseUrl}${descriptor.path}`;
// Auth via the credential authority — it owns OAuth-vs-API-key precedence
@@ -537,7 +648,25 @@ export async function discoverProviderModels(providerName: string): Promise<Disc
models.map((m) => `${m.id}(${m.contextWindow ?? "?"})`).join(", ")
);
_cache.set(providerName, { models, expiresAt: Date.now() + CACHE_TTL_MS });
- return models;
+ 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 — callers fall back to
+ * the cloud catalog.
+ *
+ * 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 discoverProviderRoster} 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 discoverProviderRoster(providerName);
+ return outcome.kind === "served" ? outcome.models : [];
}
/**
diff --git a/packages/cli/src/providers/ollama-discovery.ts b/packages/cli/src/providers/ollama-discovery.ts
index 72c9180e..1e3df84f 100644
--- a/packages/cli/src/providers/ollama-discovery.ts
+++ b/packages/cli/src/providers/ollama-discovery.ts
@@ -8,7 +8,9 @@
*
* Network-light and fail-soft: every fetch is wrapped in a short timeout and
* any error resolves to an empty list, so a missing/unreachable daemon never
- * throws — callers fall back to free-text entry.
+ * throws — callers fall back to free-text entry. The one caller that needs to
+ * TELL the user the daemon is down rather than absorb it passes
+ * `throwOnError: true`; see that option.
*/
export interface OllamaModel {
@@ -40,22 +42,36 @@ interface FetchOllamaOptions {
* still filtered out by name in that case.
*/
enrichCapabilities?: boolean;
+ /**
+ * Re-throw a daemon failure instead of absorbing it into `[]`.
+ *
+ * Default `false`, so every existing caller is byte-identical. Opt in only
+ * when you can report the difference: "the daemon is not running" and "the
+ * daemon is running and nothing is pulled" are the same `[]` otherwise, and
+ * model discovery used to record both as `empty-roster` — telling the user
+ * their local provider serves no models when in fact nothing answered.
+ */
+ throwOnError?: boolean;
}
/**
* Fetch installed Ollama models. Returns `[]` when the daemon is unreachable,
- * returns an error, or has no models — never throws. Embedding models are
- * filtered out (they can't be used for chat/completion).
+ * returns an error, or has no models — never throws unless `throwOnError` is
+ * set. Embedding models are filtered out (they can't be used for
+ * chat/completion).
*/
export async function fetchOllamaModels(options: FetchOllamaOptions = {}): Promise<OllamaModel[]> {
- const { enrichCapabilities = true } = options;
+ const { enrichCapabilities = true, throwOnError = false } = options;
const host = ollamaBaseUrl();
try {
const response = await fetch(`${host}/api/tags`, {
signal: AbortSignal.timeout(3000),
});
- if (!response.ok) return [];
+ if (!response.ok) {
+ if (throwOnError) throw new Error(`HTTP ${response.status} from ${host}/api/tags`);
+ return [];
+ }
const data = (await response.json()) as { models?: Array<Record<string, any>> };
const models = data.models || [];
@@ -104,8 +120,9 @@ export async function fetchOllamaModels(options: FetchOllamaOptions = {}): Promi
);
return enriched.filter((m) => !m.isEmbeddingModel);
- } catch {
+ } catch (err) {
// Ollama not running or not reachable.
+ if (throwOnError) throw err;
return [];
}
}