jeo-code 0.9.16 → 0.10.0

package/CHANGELOG.md

@@ -9,6 +9,37 @@ The README mirrors the latest 5 entries — regenerate with `bun run changelog:s
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-25
+_jeo could only be pointed at ONE user-supplied endpoint (`config.openaiBaseUrl`), and doing so rebound the built-in `openai` provider: it stole the `openai/` routing prefix, collided with real OpenAI model ids, and could not speak the Anthropic Messages protocol at all. There was no way to run a company LiteLLM proxy and a self-hosted vLLM box at the same time, or to reach either from a script._
+
+### Added
+- **Named custom providers (`config.customProviders`)** (`src/ai/providers/custom-providers.ts`) — register any OpenAI- or Anthropic-compatible endpoint as a first-class provider with its own routing prefix, base URL, wire protocol, credential source (env var or literal key), model list and default model. Registered providers are published through the SAME `openaiCompatDef` lookup the compiled-in catalog uses, so routing, live `/models` discovery, `/model`, provider status, pickers and credential resolution pick them up with no new per-call-site branching. Validation is strict and actionable at registration time: provider ids must match `^[a-z0-9][a-z0-9._-]*$` (a `/` would collide with the `<provider>/<model>` separator), built-in ids are reserved, and base URLs must be absolute `http(s)` — so a typo fails with one clear message instead of an opaque fetch error at the first inference call. A single malformed row is skipped with its reason rather than failing the whole config.
+- **15 provider presets** (`src/ai/providers/provider-presets.ts`) — one-flag onboarding for known gateways: `litellm`, `vllm`, `sglang`, `llama-cpp`, `azure-openai`, `vercel-ai-gateway`, `cloudflare-ai-gateway`, `openai-compatible-proxy`, `anthropic-compatible-proxy`, `glm`, `alibaba-token-plan`, `cline-pass`, `commandcode-goat`, `ollama-cloud`, `github-copilot`. Parameterized presets (proxies the user runs) require `--base-url`; fixed presets pin theirs and reject one.
+- **`jeo provider` CLI** (`src/commands/provider.ts`) — `list` / `add` / `remove` / `presets` / `test`, sharing the exact planners the slash command uses so the two surfaces cannot drift. `jeo provider test <id>` probes the endpoint and reports credential source and endpoint health separately ("no key" and "wrong URL" need different fixes), exiting non-zero on failure so CI and provisioning scripts can gate on it. `add` runs the same probe automatically without refusing the write — registering an endpoint before its key exists is legitimate.
+- **`/provider list`, `/provider remove <id>`, `/provider presets`**, plus `/provider add --id/--preset/--compat/--api-key-env/--api-key/--model/--label/--force`, with autocomplete for preset ids and — on `remove` — only custom ids, since the command refuses built-ins.
+
+### Changed
+- **Provider ordering is now one shared ranking** (`src/ai/provider-ranking.ts`) used by the model picker: usable → broken-credential → curated famous list → the rest. The picker previously sorted by `PROVIDER_NAMES.indexOf`, which returns `-1` for a provider that is not compiled in — so a user's own custom provider sorted ABOVE the provider they were actually logged into. A stored-but-unusable login now also ranks above untouched providers, because it is the one that needs attention.
+- `ProviderName` accepts custom ids alongside the literal union, and `describeAllProviders()` / `allProviderNames()` include custom providers so they are never invisible in the UI meant to expose them.
+- `/provider add --base-url <url>` with no `--id` is unchanged (still rebinds the built-in `openai` endpoint), and now points at the named alternative. `/provider add clear` explicitly leaves custom providers alone.
+
+### Fixed
+- **`resolveProvider()` ignored custom routing prefixes** (`src/ai/model-manager.ts`) — it matched against the static `OPENAI_COMPAT_NAMES` snapshot, so `my-proxy/some-model` fell through every prefix check and hit the final `anthropic` fallthrough, silently routing a custom-provider request to Anthropic. Now matches against the live built-in + custom name list.
+- **Removing a custom provider whose id shadowed a built-in unregistered the BUILT-IN adapter** (`src/ai/register-providers.ts`) — a hand-edited row named e.g. `groq` would overwrite the shipped adapter on load and delete it on removal, leaving a compiled-in provider unreachable for the rest of the session. Shadowing rows are now inert at the adapter layer too, matching the lookup layer which already prefers built-ins.
+- `normalizeCustomBaseUrl("localhost:1234/v1")` reported "must use http or https (got 'localhost')" because `new URL()` happily parses that as a `localhost:` scheme; a missing authority marker is now detected first and reported as the missing-scheme error it actually is.
+
+### Verified
+- `bun run typecheck` clean; `bun test` shows no new failures against the 0.9.17 baseline.
+- 88 new tests across `test/custom-provider-registry.test.ts`, `test/provider-presets-ranking.test.ts`, `test/provider-slash-add.test.ts` and `test/autocomplete.test.ts`.
+- End-to-end against a live local OpenAI-compatible gateway: `jeo provider add --preset openai-compatible-proxy --id gw --base-url http://localhost:4599/v1` registered it and reported the missing credential (exit 1); with the key exported, `jeo provider test gw` discovered both served model ids and exited 0.
+
+## [0.9.17] - 2026-08-18
+_Live model discovery already existed (`listProviderModels`/`discoverModels`), but only `jeo auth login openai` ever called it — logging into Anthropic or Antigravity left the account pinned to the maintained static catalog snapshot until the next unrelated live-discovery call happened to run._
+
+### Added
+- **`jeo auth login anthropic` / `jeo auth login antigravity` now fetch and cache the account's live model list immediately after login**, matching the existing OpenAI/Codex behavior (`src/commands/auth.ts`) — the prior `reportOpenAiCodexModels` helper was generalized into `reportLiveModels(provider)` (driven by a `LIVE_MODEL_REPORT_PROVIDERS` set covering `openai`/`anthropic`/`antigravity`) so a freshly logged-in Anthropic or Antigravity account immediately shows its real, current model ids (e.g. newly released Claude/Gemini models not yet in the bundled static catalog) instead of waiting for the next launch's background discovery. The result is persisted via the existing `writeModelCache` so the very next `jeo` launch rehydrates it before any network call. Verified live: `listProviderModels("anthropic", …)` and `listProviderModels("antigravity", …)` both returned real, larger-than-catalog model sets (10 and 11 ids respectively) against live logged-in accounts, and the merged cache file reflected all three providers correctly.
+
+
 ## [0.9.16] - 2026-08-18
 _Routing looked broken while it was actually working: the idle status bar and `/compact`/`/handoff` never reflected which model `routePrompt` actually routed to._
 

package/README.ja.md

@@ -287,10 +287,10 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.10.0]** (2026-08-25) — jeo could only be pointed at ONE user-supplied endpoint (`config.openaiBaseUrl`), and doing so rebound the built-in `openai` provider: it stole the `openai/` routing prefix, collided with real OpenAI model ids, and could not speak the Anthropic Messages protocol at all. There was no way to run a company LiteLLM proxy and a self-hosted vLLM box at the same time, or to reach either from a script.
+- **[0.9.17]** (2026-08-18) — Live model discovery already existed (`listProviderModels`/`discoverModels`), but only `jeo auth login openai` ever called it — logging into Anthropic or Antigravity left the account pinned to the maintained static catalog snapshot until the next unrelated live-discovery call happened to run.
 - **[0.9.16]** (2026-08-18) — Routing looked broken while it was actually working: the idle status bar and `/compact`/`/handoff` never reflected which model `routePrompt` actually routed to.
 - **[0.9.15]** (2026-08-18) — The 0.9.14 fix wired `promptInput` into the `$a $b …` one-shot skill-chain's `io.input`, but that chain runs before the interactive REPL's own `readline.Interface` exists — so a bundled workflow skill (`$deep-interview`, with or without `--tmux`) invoked directly from the command line still froze forever on its first question.
-- **[0.9.14]** (2026-08-04) — A `$a $b … [intent]` skill-chain invocation of a bundled workflow skill (deep-interview/ralplan/team/ultragoal) hung forever with no error and no prompt.
-- **[0.9.13]** (2026-08-03) — The provider-login browser tab now actually goes away — by itself on macOS, by a working button everywhere else.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -288,10 +288,10 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.10.0]** (2026-08-25) — jeo could only be pointed at ONE user-supplied endpoint (`config.openaiBaseUrl`), and doing so rebound the built-in `openai` provider: it stole the `openai/` routing prefix, collided with real OpenAI model ids, and could not speak the Anthropic Messages protocol at all. There was no way to run a company LiteLLM proxy and a self-hosted vLLM box at the same time, or to reach either from a script.
+- **[0.9.17]** (2026-08-18) — Live model discovery already existed (`listProviderModels`/`discoverModels`), but only `jeo auth login openai` ever called it — logging into Anthropic or Antigravity left the account pinned to the maintained static catalog snapshot until the next unrelated live-discovery call happened to run.
 - **[0.9.16]** (2026-08-18) — Routing looked broken while it was actually working: the idle status bar and `/compact`/`/handoff` never reflected which model `routePrompt` actually routed to.
 - **[0.9.15]** (2026-08-18) — The 0.9.14 fix wired `promptInput` into the `$a $b …` one-shot skill-chain's `io.input`, but that chain runs before the interactive REPL's own `readline.Interface` exists — so a bundled workflow skill (`$deep-interview`, with or without `--tmux`) invoked directly from the command line still froze forever on its first question.
-- **[0.9.14]** (2026-08-04) — A `$a $b … [intent]` skill-chain invocation of a bundled workflow skill (deep-interview/ralplan/team/ultragoal) hung forever with no error and no prompt.
-- **[0.9.13]** (2026-08-03) — The provider-login browser tab now actually goes away — by itself on macOS, by a working button everywhere else.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -295,10 +295,10 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.10.0]** (2026-08-25) — jeo could only be pointed at ONE user-supplied endpoint (`config.openaiBaseUrl`), and doing so rebound the built-in `openai` provider: it stole the `openai/` routing prefix, collided with real OpenAI model ids, and could not speak the Anthropic Messages protocol at all. There was no way to run a company LiteLLM proxy and a self-hosted vLLM box at the same time, or to reach either from a script.
+- **[0.9.17]** (2026-08-18) — Live model discovery already existed (`listProviderModels`/`discoverModels`), but only `jeo auth login openai` ever called it — logging into Anthropic or Antigravity left the account pinned to the maintained static catalog snapshot until the next unrelated live-discovery call happened to run.
 - **[0.9.16]** (2026-08-18) — Routing looked broken while it was actually working: the idle status bar and `/compact`/`/handoff` never reflected which model `routePrompt` actually routed to.
 - **[0.9.15]** (2026-08-18) — The 0.9.14 fix wired `promptInput` into the `$a $b …` one-shot skill-chain's `io.input`, but that chain runs before the interactive REPL's own `readline.Interface` exists — so a bundled workflow skill (`$deep-interview`, with or without `--tmux`) invoked directly from the command line still froze forever on its first question.
-- **[0.9.14]** (2026-08-04) — A `$a $b … [intent]` skill-chain invocation of a bundled workflow skill (deep-interview/ralplan/team/ultragoal) hung forever with no error and no prompt.
-- **[0.9.13]** (2026-08-03) — The provider-login browser tab now actually goes away — by itself on macOS, by a working button everywhere else.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -287,10 +287,10 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.10.0]** (2026-08-25) — jeo could only be pointed at ONE user-supplied endpoint (`config.openaiBaseUrl`), and doing so rebound the built-in `openai` provider: it stole the `openai/` routing prefix, collided with real OpenAI model ids, and could not speak the Anthropic Messages protocol at all. There was no way to run a company LiteLLM proxy and a self-hosted vLLM box at the same time, or to reach either from a script.
+- **[0.9.17]** (2026-08-18) — Live model discovery already existed (`listProviderModels`/`discoverModels`), but only `jeo auth login openai` ever called it — logging into Anthropic or Antigravity left the account pinned to the maintained static catalog snapshot until the next unrelated live-discovery call happened to run.
 - **[0.9.16]** (2026-08-18) — Routing looked broken while it was actually working: the idle status bar and `/compact`/`/handoff` never reflected which model `routePrompt` actually routed to.
 - **[0.9.15]** (2026-08-18) — The 0.9.14 fix wired `promptInput` into the `$a $b …` one-shot skill-chain's `io.input`, but that chain runs before the interactive REPL's own `readline.Interface` exists — so a bundled workflow skill (`$deep-interview`, with or without `--tmux`) invoked directly from the command line still froze forever on its first question.
-- **[0.9.14]** (2026-08-04) — A `$a $b … [intent]` skill-chain invocation of a bundled workflow skill (deep-interview/ralplan/team/ultragoal) hung forever with no error and no prompt.
-- **[0.9.13]** (2026-08-03) — The provider-login browser tab now actually goes away — by itself on macOS, by a working button everywhere else.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.9.16",
+  "version": "0.10.0",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/config-schema.ts

@@ -24,6 +24,22 @@ const OAuthEntry = z.union([z.string(), StoredOAuthSchema]);
 // are validated/kept rather than stripped. Adding a provider = one catalog row.
 const compatKeySchema = Object.fromEntries(OPENAI_COMPAT_PROVIDERS.map(p => [p.name, z.string().optional()]));
 const compatOAuthSchema = Object.fromEntries(OPENAI_COMPAT_PROVIDERS.map(p => [p.name, OAuthEntry.optional()]));
+/** One user-registered provider (`/provider add`). Mirrors `CustomProviderConfig`.
+ *  Kept permissive on `baseUrl` (a plain string) because the real validation lives in
+ *  `toCustomProviderDef` — a bad URL must surface as ONE actionable provider error,
+ *  not a whole-config schema rejection that would strand every other setting. */
+const CustomProviderSchema = z.object({
+  label: z.string().optional(),
+  baseUrl: z.string().min(1),
+  protocol: z.enum(["openai", "anthropic"]).optional(),
+  apiKeyEnv: z.string().optional(),
+  apiKey: z.string().optional(),
+  models: z.array(z.string()).optional(),
+  defaultModel: z.string().optional(),
+  thinkingFormat: z.enum(["openai", "openrouter", "qwen", "zai"]).optional(),
+  preset: z.string().optional(),
+});
+
 const HookConfigSchema = z.object({
   enabled: z.boolean().optional(),
   hooks: z
@@ -67,6 +83,10 @@ export const ConfigSchema = z
         ...compatOAuthSchema,
       })
       .optional(),
+    /** User-registered OpenAI/Anthropic-compatible providers, keyed by routing id.
+     *  Unlike `openaiBaseUrl` (which rebinds the single built-in `openai` provider),
+     *  each entry here is its own provider with its own prefix, models and credential. */
+    customProviders: z.record(z.string(), CustomProviderSchema).optional(),
     ollamaBaseUrl: z.string().optional(),
     ollamaNumCtx: z.number().int().positive().optional(),
     openaiBaseUrl: z.string().optional(),

package/src/agent/state.ts

@@ -4,6 +4,7 @@ import * as os from "node:os";
 import { parseConfig } from "./config-schema";
 import type { AuthProvider } from "../auth/storage";
 import { OPENAI_COMPAT_PROVIDERS } from "../ai/providers/openai-compatible-catalog";
+import { resolveCustomApiKey, setCustomProviders, type CustomProviderConfig } from "../ai/providers/custom-providers";
 import { jeoEnv } from "../util/env";
 
 /** Persisted OAuth credential set (access + refresh + expiry) for a provider. */
@@ -28,8 +29,13 @@ export interface HookConfig {
 }
 
 export interface Config {
-  /** Per-provider API keys, keyed by AuthProvider (cloud keys + catalog OpenAI-compatible). */
+  /** Per-provider API keys, keyed by AuthProvider (cloud keys + catalog OpenAI-compatible).
+   *  User-registered custom provider ids are published into this same map by
+   *  `withEnvOverlay` so credential resolution needs no second lookup path. */
   providers: Partial<Record<AuthProvider, string>>;
+  /** User-registered OpenAI/Anthropic-compatible providers (`/provider add`), keyed by
+   *  routing id. Each is a full provider: own prefix, base URL, models and credential. */
+  customProviders?: Record<string, CustomProviderConfig>;
   /**
    * OAuth credentials. `resolveCredential()` returns these before API keys so refresh
    * metadata is not lost, but provider execution/status applies the GJC parity rule:
@@ -292,6 +298,18 @@ function withEnvOverlay(cfg: Config): Config {
     const key = def.name as AuthProvider; // every catalog name is an AuthProvider
     if (!providers[key] && process.env[def.apiKeyEnv]) providers[key] = process.env[def.apiKeyEnv];
   }
+  // User-registered custom providers. Publishing them here is what makes every generic
+  // path (routing, discovery, /model, status, credential resolution) treat a custom
+  // endpoint exactly like a compiled-in catalog row: `setCustomProviders` refreshes the
+  // lookup `openaiCompatDef` reads, and the key lands in the SAME `providers` map
+  // `resolveCredential` already consults. Env wins over a literal key stored on disk so
+  // a rotated shell secret takes effect without editing config.json.
+  const { defs: customDefs } = setCustomProviders(cfg.customProviders);
+  const providerKeys = providers as Record<string, string | undefined>;
+  for (const def of customDefs) {
+    const resolved = resolveCustomApiKey(def);
+    if (!providerKeys[def.name] && resolved) providerKeys[def.name] = resolved;
+  }
   return {
     ...cfg,
     providers,

package/src/ai/model-discovery.ts

@@ -95,7 +95,11 @@ function authProviderFor(provider: ProviderName): AuthProvider | undefined {
   // Local providers (ollama/lmstudio) are keyless and do not resolve through the
   // auth core. API-key providers (incl. xai/kimi) DO — so discovery sends their key.
   if (provider === "ollama" || provider === "lmstudio") return undefined;
-  return provider;
+  // A user-registered custom provider id is not in the `AuthProvider` literal union,
+  // but `withEnvOverlay` publishes its key into the SAME `config.providers` map that
+  // `resolveCredential` reads — so the lookup is keyed identically. Same cast the
+  // model-manager's generic credential path already makes.
+  return provider as AuthProvider;
 }
 
 /** Build the discovery request (url + headers) for a provider/credential. */
@@ -468,7 +472,10 @@ export async function listProviderModels(
  *  service answers in single-digit ms, so this stays cheap on the turn hot path
  *  and still fails fast on a genuinely unreachable host. */
 export async function isLocalProviderReachable(
-  provider: "ollama" | "lmstudio",
+  // Accepts any ProviderName: `ProviderName` now includes user-registered custom ids,
+  // so a `provider === "ollama" || provider === "lmstudio"` guard no longer narrows to
+  // the two literals at call sites. The probe itself is protocol-generic.
+  provider: ProviderName,
   baseUrl: string | undefined,
   opts: Pick<DiscoveryOptions, "timeoutMs" | "fetchImpl"> = {},
 ): Promise<boolean> {

package/src/ai/model-manager.ts

@@ -8,7 +8,7 @@ import { expandAlias, resolveModelId, effectiveAliasesFor, BUILTIN_ALIASES } fro
 import { findCatalogEntry, type ModelCatalogEntry } from "./model-catalog-compat";
 import { toProviderModel, CODEX_MODELS, KIMI_CODE_MODELS, findCatalogModel, isCodexModel, findLiveCatalogModel } from "./model-catalog";
 import { xaiCredential } from "./providers/xai";
-import { OPENAI_COMPAT_NAMES, isOpenAICompatProvider } from "./providers/openai-compatible-catalog";
+import { allCompatNames, isOpenAICompatProvider } from "./providers/openai-compatible-catalog";
 import { withRetry, defaultRetryable, withConnectionContext, isConnectionError, ConnectionContextError, type RetryOptions } from "../util/retry";
 import { jeoEnv } from "../util/env";
 import type { Config } from "../agent/state";
@@ -39,7 +39,10 @@ export function resolveProvider(model: string): ProviderName {
   if (m.startsWith("antigravity/")) return "antigravity";
   if (m.startsWith("xai/")) return "xai";
   if (m.startsWith("kimi/")) return "kimi";
-  for (const p of OPENAI_COMPAT_NAMES) if (m.startsWith(`${p}/`)) return p;
+  // Built-ins FIRST, then user-registered custom providers: a custom id can never be a
+  // built-in name (`assertValidProviderId` reserves them), but ordering keeps routing
+  // deterministic even for a hand-edited config that predates that check.
+  for (const p of allCompatNames()) if (m.startsWith(`${p}/`)) return p;
   if (m.startsWith("openai/")) return "openai";
   if (m.startsWith("google/")) return "gemini";
   // Loose substring heuristics for BARE (unprefixed) ids only.

package/src/ai/provider-ranking.ts

@@ -0,0 +1,153 @@
+/**
+ * Shared provider ordering — the single source of truth behind every provider-facing
+ * surface (`/provider`, `/model`, the model/provider pickers, `jeo doctor`).
+ *
+ * Before this module each surface kept its own ad-hoc sort: `model-picker` sorted by
+ * `PROVIDER_NAMES` index, `/provider` printed catalog order, and custom providers
+ * (which have no compiled-in index at all) landed wherever `indexOf` returned -1 —
+ * i.e. FIRST, above the user's actual logged-in provider. The ranking below is
+ * deliberately state-first so the list a user sees always leads with providers they
+ * can actually call right now.
+ *
+ * Order: providers you have → providers you have but that are broken → a curated
+ * "famous" list → everything else alphabetically. Ties break on label, then id, so
+ * the order is total and stable (no reflow when async credential checks resolve).
+ */
+
+/**
+ * Auth/config state of a provider as seen by the calling surface.
+ *
+ * - `valid`       — credential present and believed usable right now.
+ * - `checking`    — credential present, async validation still in flight. Ranked WITH
+ *                   `valid` so rows do not jump when the check resolves.
+ * - `configured`  — no OAuth record, but the provider is usable (custom provider with
+ *                   a key, keyless local server).
+ * - `invalid`     — credential present but known-bad (expired OAuth with no refresh).
+ * - `none`        — nothing stored, nothing configured.
+ */
+export type ProviderAuthState = "valid" | "checking" | "configured" | "invalid" | "none";
+
+export const PROVIDER_RANK_TIER = {
+  existing: 0,
+  problematic: 1,
+  famous: 2,
+  other: 3,
+} as const;
+
+export type ProviderRankTier = (typeof PROVIDER_RANK_TIER)[keyof typeof PROVIDER_RANK_TIER];
+
+/**
+ * Curated order for the "famous" tier — providers a user is most likely to want when
+ * they have nothing configured yet. Regional/plan variants sit immediately behind
+ * their primary so related rows stay grouped.
+ */
+export const FAMOUS_PROVIDER_ORDER: readonly string[] = [
+  "anthropic",
+  "openai",
+  "gemini",
+  "antigravity",
+  "xai",
+  "kimi",
+  "zai",
+  "minimax",
+  "minimax-code",
+  "minimax-code-cn",
+  "groq",
+  "deepseek",
+  "openrouter",
+  "mistral",
+  "together",
+  "cerebras",
+  "fireworks",
+  "deepinfra",
+  "nvidia",
+  "alibaba-coding-plan",
+  "qwen-portal",
+  "xiaomi",
+  "xiaomi-token-plan-sgp",
+  "xiaomi-token-plan-ams",
+  "xiaomi-token-plan-cn",
+  "tencent",
+  "qianfan",
+  "huggingface",
+  "nanogpt",
+  "synthetic",
+  "venice",
+  "zenmux",
+  "litellm",
+  "ollama",
+  "lmstudio",
+];
+
+const FAMOUS_PROVIDER_INDEX = new Map(FAMOUS_PROVIDER_ORDER.map((id, i) => [id, i]));
+
+/** A provider as ranked by a surface. `label` is what the user sees. */
+export interface RankableProvider {
+  id: string;
+  label: string;
+  authState: ProviderAuthState;
+  /** User-registered custom providers sort ahead of unconfigured built-ins in the
+   *  `other` tier — the user explicitly added them, so they are not "everything else". */
+  custom?: boolean;
+}
+
+/** A provider's position: its tier plus its rank inside that tier. */
+export interface ProviderRank {
+  tier: ProviderRankTier;
+  intraTierRank: number;
+}
+
+export function providerRankTier(authState: ProviderAuthState, id: string, custom?: boolean): ProviderRankTier {
+  if (authState === "valid" || authState === "checking" || authState === "configured") {
+    return PROVIDER_RANK_TIER.existing;
+  }
+  if (authState === "invalid") return PROVIDER_RANK_TIER.problematic;
+  if (FAMOUS_PROVIDER_INDEX.has(id)) return PROVIDER_RANK_TIER.famous;
+  // An unconfigured custom provider still beat "some cloud you never mentioned" —
+  // the user typed its id into their own config.
+  return custom ? PROVIDER_RANK_TIER.famous : PROVIDER_RANK_TIER.other;
+}
+
+/** Position within the famous list, or `undefined` for providers not on it. */
+export function famousProviderIndex(id: string): number | undefined {
+  return FAMOUS_PROVIDER_INDEX.get(id);
+}
+
+export function rankProvider(provider: RankableProvider): ProviderRank {
+  return {
+    tier: providerRankTier(provider.authState, provider.id, provider.custom),
+    intraTierRank: FAMOUS_PROVIDER_INDEX.get(provider.id) ?? Number.MAX_SAFE_INTEGER,
+  };
+}
+
+/**
+ * Total order over providers: tier, then famous-list position, then display label,
+ * then id. The trailing id comparison guarantees no ties (stable across renders).
+ */
+export function compareRankedProviders(left: RankableProvider, right: RankableProvider): number {
+  const l = rankProvider(left);
+  const r = rankProvider(right);
+  if (l.tier !== r.tier) return l.tier - r.tier;
+  if (l.intraTierRank !== r.intraTierRank) return l.intraTierRank - r.intraTierRank;
+  const byLabel = left.label.localeCompare(right.label);
+  if (byLabel !== 0) return byLabel;
+  return left.id.localeCompare(right.id);
+}
+
+/** Convenience wrapper returning a NEW array in ranked order (never mutates input). */
+export function sortRankedProviders<T extends RankableProvider>(providers: readonly T[]): T[] {
+  return [...providers].sort(compareRankedProviders);
+}
+
+/** Map a jeo `ProviderStatus`-shaped record onto the ranking's auth-state vocabulary. */
+export function authStateFor(status: {
+  ready: boolean;
+  kind: "api_key" | "oauth" | "keyless" | "none";
+  loggedIn?: boolean;
+}): ProviderAuthState {
+  if (status.ready) return status.kind === "oauth" ? "valid" : "configured";
+  // A stored login that cannot serve a call is the "problematic" tier: it needs the
+  // user's attention (re-login / add a key) more urgently than an untouched provider.
+  if (status.loggedIn) return "invalid";
+  return "none";
+}

package/src/ai/provider-registry.ts

@@ -15,6 +15,16 @@ class ProviderRegistry {
     return this.adapters.get(name);
   }
 
+  /** Drop an adapter. Used when a user removes a custom provider mid-session so the
+   *  next `/model` or routing pass cannot resolve a provider that no longer exists. */
+  unregister(name: ProviderName): boolean {
+    return this.adapters.delete(name);
+  }
+
+  has(name: ProviderName): boolean {
+    return this.adapters.has(name);
+  }
+
   listProviders(): ProviderName[] {
     return Array.from(this.adapters.keys());
   }

package/src/ai/provider-status.ts

@@ -10,9 +10,20 @@ import { OAUTH_FLOW_REGISTRY } from "../auth/flows";
 import type { ProviderName } from "./types";
 
 import { OPENAI_COMPAT_NAMES, openaiCompatDef } from "./providers/openai-compatible-catalog";
+import { customProviderDef, customProviderNames, credentialSourceOf, resolveCustomApiKey } from "./providers/custom-providers";
 
+/** Compiled-in providers, in declaration order. Custom providers are NOT here — they
+ *  are discovered at runtime, so use {@link allProviderNames} for anything the user sees. */
 export const PROVIDER_NAMES: readonly ProviderName[] = ["anthropic", "openai", "gemini", "antigravity", "ollama", "lmstudio", "xai", "kimi", ...OPENAI_COMPAT_NAMES];
 
+/** Built-in providers PLUS the user's registered custom providers. Every user-facing
+ *  surface (pickers, `/provider`, autocomplete, doctor) should list from here so a
+ *  custom endpoint is never invisible in the UI that is supposed to expose it. */
+export function allProviderNames(): readonly ProviderName[] {
+  const custom = customProviderNames();
+  return custom.length ? [...PROVIDER_NAMES, ...custom] : PROVIDER_NAMES;
+}
+
 /** Cloud providers that authenticate via API key / OAuth. Ollama is keyless. */
 export const CLOUD_PROVIDERS: readonly AuthProvider[] = ["anthropic", "openai", "gemini", "antigravity"];
 
@@ -35,6 +46,8 @@ export interface ProviderStatus {
   oauthEmail?: string;
   /** Epoch ms expiry of the stored OAuth access token, when known. */
   oauthExpires?: number;
+  /** True for user-registered custom providers (`config.customProviders`). */
+  custom?: boolean;
 }
 
 /** The env var that supplies a provider's API key. Catalog providers carry their
@@ -46,6 +59,13 @@ export function providerEnvVar(name: ProviderName): string | undefined {
   return `${name.toUpperCase()}_API_KEY`;
 }
 
+/** The API key a custom provider will actually use, or undefined. Exported so setup /
+ *  doctor can probe a custom endpoint without re-deriving the env-vs-literal rule. */
+export function customProviderApiKey(name: ProviderName): string | undefined {
+  const def = customProviderDef(name);
+  return def ? resolveCustomApiKey(def) : undefined;
+}
+
 /** Human label for a credential kind. */
 export function credentialLabel(kind: CredentialKind): string {
   switch (kind) {
@@ -113,6 +133,25 @@ function effectiveCredential(provider: AuthProvider, cred: Credential, cfg: Conf
 /** Resolve the status of a single provider. */
 export async function describeProvider(name: ProviderName, config?: Config): Promise<ProviderStatus> {
   const cfg = config ?? (await readGlobalConfig());
+  // Custom providers resolve their credential from their OWN env var / stored literal,
+  // not from the fixed `providers` union — report that source verbatim so a user who
+  // set the wrong env var sees WHICH variable jeo is looking at.
+  const custom = customProviderDef(name);
+  if (custom) {
+    const source = credentialSourceOf(custom);
+    const ready = source !== "none";
+    return {
+      name,
+      kind: ready ? "api_key" : "none",
+      label: ready
+        ? `API key (${source === "env" ? custom.apiKeyEnv : "stored in config"}) · custom${custom.preset ? ` · preset ${custom.preset}` : ""}`
+        : `none (set ${custom.apiKeyEnv}, or 'jeo provider key ${name} <key>')`,
+      baseUrl: custom.baseUrl,
+      envVar: custom.apiKeyEnv,
+      ready,
+      custom: true,
+    };
+  }
   if (name === "ollama" || name === "lmstudio") {
     const baseUrl = name === "ollama"
       ? (cfg.ollamaBaseUrl ?? "http://localhost:11434")
@@ -183,8 +222,8 @@ export async function describeProvider(name: ProviderName, config?: Config): Pro
   };
 }
 
-/** Resolve the status of every provider (single config read). */
+/** Resolve the status of every provider (single config read), custom providers included. */
 export async function describeAllProviders(config?: Config): Promise<ProviderStatus[]> {
   const cfg = config ?? (await readGlobalConfig());
-  return Promise.all(PROVIDER_NAMES.map(name => describeProvider(name, cfg)));
+  return Promise.all(allProviderNames().map(name => describeProvider(name, cfg)));
 }