jeo-code 0.9.17 → 0.11.0

package/src/agent/notify/daemon-control.ts

@@ -42,13 +42,52 @@ export function parseEtimeToMs(raw: string): number | undefined {
   return ((days * 24 + h!) * 60 + m!) * 60 * 1000 + s! * 1000;
 }
 
-/** Best-effort actual OS process start time in epoch ms, via `ps -o etime=`
- *  (POSIX-portable across macOS/Linux `ps`; unsupported on Windows, where
- *  there is no equivalent zero-dependency lookup). Returns `undefined` when
- *  the lookup is unavailable or unparseable — callers MUST treat that as
- *  "cannot verify" and fall back to the existence-only check, not as "dead". */
+/**
+ * Read a process's start time from `/proc` — Linux only, no subprocess.
+ *
+ * Field 22 of `/proc/<pid>/stat` is the process start time in clock ticks since
+ * boot; `/proc/uptime` gives seconds since boot. Together they yield an epoch
+ * timestamp WITHOUT spawning anything. That matters because the `ps` path below is
+ * exactly what disappears in the environments a Telegram daemon actually runs in:
+ * distroless and scratch containers ship no `ps`, and hardened sandboxes/seccomp
+ * profiles routinely block the setuid `/bin/ps`. When the lookup dies there, the
+ * PID-reuse guard silently degrades to a bare `kill(pid, 0)` — see
+ * {@link isLockOwnerAlive} for why that is the dangerous case.
+ *
+ * The 22nd field is parsed from the LAST `)` rather than by splitting on spaces:
+ * field 2 is the executable name in parentheses and may itself contain spaces.
+ */
+function procStartTimeMs(pid: number): number | undefined {
+  if (process.platform !== "linux") return undefined;
+  try {
+    const stat = fsSync.readFileSync(`/proc/${pid}/stat`, "utf-8");
+    const afterComm = stat.slice(stat.lastIndexOf(")") + 2);
+    const fields = afterComm.split(" ");
+    // stat field 22 (1-based) == index 19 of the post-comm remainder (fields 3+).
+    const startTicks = Number(fields[19]);
+    if (!Number.isFinite(startTicks)) return undefined;
+    const uptimeSec = Number(fsSync.readFileSync("/proc/uptime", "utf-8").split(" ")[0]);
+    if (!Number.isFinite(uptimeSec)) return undefined;
+    // USER_HZ is 100 on every Linux ABI that matters; sysconf(_SC_CLK_TCK) is not
+    // reachable without a native addon, and jeo is zero-native-dependency by design.
+    const startSecSinceBoot = startTicks / 100;
+    const bootEpochMs = Date.now() - uptimeSec * 1000;
+    return bootEpochMs + startSecSinceBoot * 1000;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Best-effort actual OS process start time in epoch ms. Tries `/proc` first (Linux,
+ *  no subprocess, works in distroless/sandboxed containers), then `ps -o etime=`
+ *  (POSIX-portable across macOS/Linux; unsupported on Windows, where there is no
+ *  equivalent zero-dependency lookup). Returns `undefined` when the lookup is
+ *  unavailable or unparseable — callers MUST treat that as "cannot verify" and fall
+ *  back to the existence-only check, not as "dead". */
 export async function processStartTimeMs(pid: number): Promise<number | undefined> {
   if (process.platform === "win32") return undefined;
+  const viaProc = procStartTimeMs(pid);
+  if (viaProc !== undefined) return viaProc;
   const output = await new Promise<string | undefined>(resolve => {
     let child: ReturnType<typeof nodeSpawn>;
     try {
@@ -67,6 +106,13 @@ export async function processStartTimeMs(pid: number): Promise<number | undefine
   return ms === undefined ? undefined : Date.now() - ms;
 }
 
+/** True when this host can actually verify a process's start time. Exported so
+ *  status output (and tests) can distinguish "the guard says the owner is alive"
+ *  from "the guard could not check" instead of conflating the two. */
+export async function canVerifyProcessStartTime(): Promise<boolean> {
+  return (await processStartTimeMs(process.pid)) !== undefined;
+}
+
 /** `etime` is truncated to whole seconds and adds a little spawn/poll jitter;
  *  genuine PID reuse shows up as a gap of minutes/hours/days, never a few
  *  seconds, so a generous-but-tight tolerance loses no real detections. */
@@ -82,10 +128,23 @@ const START_TIME_TOLERANCE_MS = 10_000;
  *  unavailable (Windows, `ps` missing, permission denied) — never a
  *  regression versus the old behavior in that case. */
 export async function isLockOwnerAlive(lock: DaemonLockInfo): Promise<boolean> {
-  if (!isPidAlive(lock.pid)) return false;
+  return (await inspectLockOwner(lock)).alive;
+}
+
+/** Whether the recorded owner is alive, AND whether that answer was actually
+ *  verified against the OS start time or merely assumed from `kill(pid, 0)`. */
+export interface LockOwnerCheck {
+  alive: boolean;
+  /** False when the host could not report the process start time (no `/proc`,
+   *  no usable `ps`, Windows) — `alive` is then an existence-only guess. */
+  verified: boolean;
+}
+
+export async function inspectLockOwner(lock: DaemonLockInfo): Promise<LockOwnerCheck> {
+  if (!isPidAlive(lock.pid)) return { alive: false, verified: true };
   const real = await processStartTimeMs(lock.pid);
-  if (real === undefined) return true;
-  return Math.abs(real - lock.startedAt) <= START_TIME_TOLERANCE_MS;
+  if (real === undefined) return { alive: true, verified: false };
+  return { alive: Math.abs(real - lock.startedAt) <= START_TIME_TOLERANCE_MS, verified: true };
 }
 
 export async function readDaemonLock(): Promise<DaemonLockInfo | undefined> {
@@ -123,6 +182,10 @@ export interface DaemonStatus {
   stale: boolean;
   pid?: number;
   startedAt?: number;
+  /** False when this host cannot report a process start time (no `/proc`, no usable
+   *  `ps`, Windows), so `running` is an existence-only guess that cannot rule out PID
+   *  reuse. Present only when a lock file exists. */
+  ownerVerified?: boolean;
 }
 
 export async function isNotifyConfigured(): Promise<boolean> {
@@ -133,8 +196,10 @@ export async function isNotifyConfigured(): Promise<boolean> {
 export async function daemonStatus(): Promise<DaemonStatus> {
   const [lock, configured] = await Promise.all([readDaemonLock(), isNotifyConfigured()]);
   if (!lock) return { configured, running: false, stale: false };
-  const alive = await isLockOwnerAlive(lock);
-  return { configured, running: alive, stale: !alive, pid: lock.pid, startedAt: lock.startedAt };
+  const { alive, verified } = await inspectLockOwner(lock);
+  // Surface the degraded case instead of hiding it: on a host with no `/proc` and no
+  // usable `ps`, "running" is an existence-only guess that cannot rule out PID reuse.
+  return { configured, running: alive, stale: !alive, pid: lock.pid, startedAt: lock.startedAt, ownerVerified: verified };
 }
 
 /** Self-invocation argv for the daemon child (mirrors `memory.ts`'s
@@ -200,7 +265,8 @@ export async function startDaemon(spawnImpl: SpawnLike = defaultSpawn): Promise<
 
 export async function stopDaemon(): Promise<{ ok: boolean; message: string }> {
   const lock = await readDaemonLock();
-  if (!lock || !(await isLockOwnerAlive(lock))) {
+  const owner = lock ? await inspectLockOwner(lock) : undefined;
+  if (!lock || !owner?.alive) {
     await fs.unlink(notifyDaemonLockPath()).catch(() => {});
     return { ok: true, message: "daemon was not running" };
   }
@@ -212,7 +278,8 @@ export async function stopDaemon(): Promise<{ ok: boolean; message: string }> {
   const stopped = await waitFor(async () => !isPidAlive(lock.pid), 3_000);
   if (!stopped) return { ok: false, message: `daemon (pid ${lock.pid}) did not exit within 3s` };
   await fs.unlink(notifyDaemonLockPath()).catch(() => {});
-  return { ok: true, message: `daemon stopped (was pid ${lock.pid})` };
+  const caveat = owner.verified ? "" : " (start time unverifiable on this host — PID reuse could not be ruled out)";
+  return { ok: true, message: `daemon stopped (was pid ${lock.pid})${caveat}` };
 }
 
 export async function reloadDaemon(spawnImpl: SpawnLike = defaultSpawn): Promise<{ ok: boolean; message: string }> {

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/agent/task-tool.ts

@@ -111,6 +111,27 @@ export interface TaskToolOptions {
  *  no in-batch peer channel yet, so overlapping-scope tasks MUST be sequential. */
 export const MAX_FANOUT = 4;
 
+/** Clamp for {@link resolveFanoutLimit}. Below 1 there is no fan-out at all; above 16
+ *  the parent turn is monopolized no matter how much provider capacity exists. */
+export const MIN_FANOUT_LIMIT = 1;
+export const MAX_FANOUT_LIMIT = 16;
+
+/**
+ * Effective fan-out concurrency for this account.
+ *
+ * {@link MAX_FANOUT} is a reasonable default, not a universal one: four concurrent
+ * Anthropic streams trip a Tier-1 rate limit immediately (turning a fan-out into a
+ * backoff storm that is SLOWER than running sequentially), while an account with real
+ * headroom leaves throughput on the table at four. `config.subagentConcurrency` lets
+ * that be tuned per machine; the clamp keeps a typo (`0`, `-1`, `500`) from producing a
+ * batch that never runs or never yields.
+ */
+export function resolveFanoutLimit(config?: { subagentConcurrency?: number }): number {
+  const raw = config?.subagentConcurrency;
+  if (raw === undefined || !Number.isFinite(raw)) return MAX_FANOUT;
+  return Math.min(MAX_FANOUT_LIMIT, Math.max(MIN_FANOUT_LIMIT, Math.trunc(raw)));
+}
+
 /** Small bounded reroute budget for a SUBAGENT's own 429 (distinct from
  *  launch.ts's `ROUTE_FALLBACK_MAX_ATTEMPTS`, default 3): a subagent is already
  *  bounded by its own step/token budget and the parent turn's patience, so this
@@ -635,9 +656,12 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
           };
         }
       }
-      // Both roles fan out CONCURRENTLY, bounded at MAX_FANOUT (gjc parity — see
-      // MAX_FANOUT's docstring for the disjoint-file-scope expectation this relies on).
-      const limit = Math.min(items.length, MAX_FANOUT);
+      // Both roles fan out CONCURRENTLY, bounded at the account's effective limit
+      // (gjc parity — see MAX_FANOUT's docstring for the disjoint-file-scope expectation
+      // this relies on). `config.subagentConcurrency` tunes it per machine so a
+      // rate-limited account can drop below the default instead of backoff-storming.
+      const fanoutLimit = resolveFanoutLimit(opts.config as { subagentConcurrency?: number });
+      const limit = Math.min(items.length, fanoutLimit);
       // Load project context ONCE per batch instead of re-scanning AGENTS.md for
       // every fan-out task (redundant IO + duplicated tokens).
       const batchContext = await loadProjectContext(cwd);

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/model-retirements.ts

@@ -0,0 +1,123 @@
+/**
+ * Retired model ids and where they went.
+ *
+ * A model id that a provider has sunset does not fail *nicely*: the id is simply
+ * unknown at the API, so the call comes back as a 404 / "model not found" from deep
+ * inside the adapter. That is a bad failure for jeo specifically, because model ids get
+ * **pinned in three durable places** — `config.defaultModel`, per-role
+ * `config.subagents.<role>.model`, and `config.roles.*` — and a pinned id keeps failing
+ * every turn until the user works out which of the three is stale. The live catalog
+ * refresh does not help: discovery only reports what still EXISTS, so a retired pin has
+ * nothing to match against and silently stays broken.
+ *
+ * This table maps a retired id to its documented successor so the manager can (a) route
+ * the call to something that works and (b) tell the user exactly which pin to update.
+ * It is deliberately small and hand-curated: only ids jeo itself shipped in its catalog
+ * or aliases, so nobody's config can be silently rewritten to a model they never chose.
+ *
+ * Rules for entries:
+ *  - `replacement` MUST be a currently-catalogued id, and MUST stay on the SAME provider.
+ *    Silently moving a user to a different vendor (different pricing, different data
+ *    handling, different account) is not a substitution jeo gets to make on its own.
+ *  - `note` is shown to the user once per session, so it should name the successor and
+ *    read as an explanation, not a warning banner.
+ */
+
+export interface ModelRetirement {
+  /** The retired id, exactly as it appeared in jeo's catalog/aliases. */
+  readonly retired: string;
+  /** Current catalog id that serves the same role on the SAME provider. */
+  readonly replacement: string;
+  /** One-line reason surfaced to the user. */
+  readonly note: string;
+}
+
+export const MODEL_RETIREMENTS: readonly ModelRetirement[] = [
+  {
+    retired: "antigravity/gemini-3.1-pro-high",
+    replacement: "antigravity/gemini-pro-agent",
+    note: "Antigravity retired gemini-3.1-pro-high; gemini-pro-agent is its code-agent successor.",
+  },
+  {
+    retired: "gemini-3.1-pro-high",
+    replacement: "antigravity/gemini-pro-agent",
+    note: "Antigravity retired gemini-3.1-pro-high; gemini-pro-agent is its code-agent successor.",
+  },
+] as const;
+
+const BY_RETIRED = new Map(MODEL_RETIREMENTS.map(r => [r.retired.toLowerCase(), r]));
+
+/** The retirement record for `model`, or undefined when the id is still current. */
+export function findRetirement(model: string | undefined): ModelRetirement | undefined {
+  const key = model?.trim().toLowerCase();
+  return key ? BY_RETIRED.get(key) : undefined;
+}
+
+/** True when `model` names an id jeo knows has been sunset. */
+export function isRetiredModel(model: string | undefined): boolean {
+  return findRetirement(model) !== undefined;
+}
+
+/**
+ * Map a possibly-retired id onto a working one.
+ *
+ * Returns the input unchanged when it is current, so this is safe to call on every
+ * resolution path. Chains are followed (a successor that was itself later retired)
+ * with a hard bound, so a malformed table can never spin here.
+ */
+export function resolveRetiredModel(model: string): { model: string; retirement?: ModelRetirement } {
+  let current = model;
+  let first: ModelRetirement | undefined;
+  for (let hop = 0; hop < 4; hop++) {
+    const hit = findRetirement(current);
+    if (!hit) break;
+    first ??= hit;
+    if (hit.replacement.toLowerCase() === current.toLowerCase()) break; // self-reference guard
+    current = hit.replacement;
+  }
+  return first ? { model: current, retirement: first } : { model };
+}
+
+/**
+ * Which durable config pins still name a retired model, and what to change them to.
+ * Used by `jeo doctor` and by the launch banner so the user is told *where* the stale
+ * id lives rather than just that some call failed.
+ */
+export interface RetiredPin {
+  /** Human-readable location, e.g. `defaultModel` or `subagents.executor.model`. */
+  location: string;
+  retired: string;
+  replacement: string;
+  note: string;
+}
+
+export function findRetiredPins(config: {
+  defaultModel?: string;
+  roles?: Record<string, string | undefined>;
+  subagents?: Record<string, { model?: string } | undefined>;
+}): RetiredPin[] {
+  const pins: RetiredPin[] = [];
+  const add = (location: string, model: string | undefined) => {
+    const hit = findRetirement(model);
+    if (hit) pins.push({ location, retired: model!, replacement: hit.replacement, note: hit.note });
+  };
+  add("defaultModel", config.defaultModel);
+  for (const [role, model] of Object.entries(config.roles ?? {})) add(`roles.${role}`, model);
+  for (const [role, cfg] of Object.entries(config.subagents ?? {})) add(`subagents.${role}.model`, cfg?.model);
+  return pins;
+}
+
+/** One-time-per-session dedupe so a retired pin explains itself once, not every turn. */
+const announced = new Set<string>();
+
+export function shouldAnnounceRetirement(retired: string): boolean {
+  const key = retired.toLowerCase();
+  if (announced.has(key)) return false;
+  announced.add(key);
+  return true;
+}
+
+/** Test hook — clears the per-session announce dedupe. */
+export function resetRetirementAnnouncements(): void {
+  announced.clear();
+}

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)));
 }