jeo-code 0.9.16 → 0.10.0

package/src/ai/providers/custom-providers.ts

@@ -0,0 +1,321 @@
+/**
+ * User-defined ("custom") provider registry — gjc/gajae-code parity.
+ *
+ * jeo ships a fixed, data-driven catalog of OpenAI/Anthropic-compatible clouds
+ * (`OPENAI_COMPAT_PROVIDERS`). That table is compiled in: a user could not point jeo
+ * at their own gateway (LiteLLM behind a company proxy, a self-hosted vLLM, an
+ * OpenRouter-style aggregator, a corporate Anthropic proxy) without patching source.
+ * The single escape hatch was `config.openaiBaseUrl`, which rebinds the ONE built-in
+ * `openai` provider — so only one custom endpoint could exist at a time, it stole the
+ * `openai/` routing prefix, and its models collided with real OpenAI ids.
+ *
+ * This module adds NAMED custom providers: each gets its own routing prefix, base URL,
+ * wire protocol, credential source, and model list, persisted under
+ * `config.customProviders`. They are surfaced through the SAME lookup the built-in
+ * catalog uses (`openaiCompatDef`), so discovery, routing, `/model`, `/provider`,
+ * status, and the adapter factories all pick them up with no per-call-site branching.
+ *
+ * Design constraints (kept deliberately narrow so the generic paths stay simple):
+ *  - `id` is the routing prefix (`<id>/…`) AND the config/auth key — same rule as the
+ *    built-in catalog, so `resolveProvider()` needs no special case.
+ *  - Only the two wire protocols jeo already speaks are allowed ("openai" | "anthropic").
+ *  - The credential is either a literal key stored in config, or the name of an env var.
+ *    Env is the default and the recommended path (nothing secret lands on disk).
+ */
+import type { ProviderName } from "../types";
+import type { OpenAICompatProviderDef } from "./openai-compatible-catalog";
+
+/** Wire protocols a custom provider may speak — the two jeo already implements. */
+export type ProviderCompatibility = "openai" | "anthropic";
+
+/** Where a custom provider's API key comes from. */
+export type CredentialSource = "env" | "literal" | "none";
+
+/** One user-defined provider, as persisted under `config.customProviders[id]`. */
+export interface CustomProviderConfig {
+  /** Display label (defaults to the id when absent). */
+  label?: string;
+  /** API base URL. OpenAI protocol → `${base}/chat/completions` + `${base}/models`;
+   *  Anthropic protocol → `${base}/v1/messages` + `${base}/v1/models`. */
+  baseUrl: string;
+  /** Wire protocol. Defaults to "openai". */
+  protocol?: ProviderCompatibility;
+  /** Env var holding the API key. Defaults to `<ID>_API_KEY` (id upper-cased, `-`/`.` → `_`). */
+  apiKeyEnv?: string;
+  /** Literal API key. Only set when the user explicitly chose the "literal" source;
+   *  redacted everywhere it is displayed. `apiKeyEnv` wins when both resolve. */
+  apiKey?: string;
+  /** Known model ids (BARE, not prefixed) for the offline pick-list. Live `/models`
+   *  discovery supersedes this once the endpoint answers. */
+  models?: string[];
+  /** Default model id (BARE or prefixed) used by `--provider <id>`. */
+  defaultModel?: string;
+  /** Native-reasoning enablement, same semantics as the built-in catalog. */
+  thinkingFormat?: "openai" | "openrouter" | "qwen" | "zai";
+  /** The preset this entry was created from, when applicable (informational). */
+  preset?: string;
+}
+
+export type CustomProviderMap = Record<string, CustomProviderConfig>;
+
+/** A validated custom provider, normalized into the catalog's own shape. */
+export interface CustomProviderDef extends OpenAICompatProviderDef {
+  /** True — distinguishes a user entry from a compiled-in catalog row. */
+  readonly custom: true;
+  /** Literal key when the user chose the "literal" credential source. */
+  readonly literalApiKey?: string;
+  /** Preset id this entry came from, when applicable. */
+  readonly preset?: string;
+}
+
+/** Provider ids the user may NOT claim: every compiled-in provider plus reserved words. */
+export const RESERVED_PROVIDER_IDS: readonly string[] = [
+  "anthropic",
+  "openai",
+  "gemini",
+  "antigravity",
+  "ollama",
+  "lmstudio",
+  "xai",
+  "kimi",
+  // Reserved so a future built-in cannot be shadowed by a stale user entry.
+  "google",
+  "vertex",
+  "bedrock",
+  "azure",
+  "copilot",
+  "cursor",
+  "codex",
+  "auto",
+  "default",
+  "none",
+  "all",
+  "help",
+  "clear",
+  "list",
+  "add",
+  "remove",
+  "rm",
+];
+
+/** Same grammar gajae-code enforces: lowercase, starts alphanumeric, `.`/`_`/`-` inside. */
+export const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+
+const MAX_PROVIDER_ID_LENGTH = 48;
+const REDACT_PREFIX = 4;
+const REDACT_SUFFIX = 4;
+
+/** Lowercase + trim. Ids are case-insensitive so `/model MyProxy/x` still routes. */
+export function normalizeProviderId(id: string): string {
+  return id.trim().toLowerCase();
+}
+
+/** Derived env var for a provider id: `my-proxy` → `MY_PROXY_API_KEY`. */
+export function defaultApiKeyEnv(id: string): string {
+  return `${normalizeProviderId(id).replace(/[.\-]/g, "_").toUpperCase()}_API_KEY`;
+}
+
+/**
+ * Validate a candidate custom-provider id. Throws with an actionable message rather
+ * than returning a boolean, because every call site (CLI, slash command, config load)
+ * wants the reason to show the user.
+ */
+export function assertValidProviderId(rawId: string, reserved: readonly string[] = RESERVED_PROVIDER_IDS): string {
+  const id = normalizeProviderId(rawId);
+  if (!id) throw new Error("Provider id is required (e.g. --id my-proxy).");
+  if (id.length > MAX_PROVIDER_ID_LENGTH) {
+    throw new Error(`Provider id '${id}' is too long (max ${MAX_PROVIDER_ID_LENGTH} characters).`);
+  }
+  if (!PROVIDER_ID_PATTERN.test(id)) {
+    throw new Error(
+      `Invalid provider id '${id}'. Use lowercase letters, digits, '.', '_' or '-', starting with a letter or digit.`,
+    );
+  }
+  if ((reserved as readonly string[]).includes(id)) {
+    throw new Error(`Provider id '${id}' is reserved by a built-in provider — pick another id.`);
+  }
+  return id;
+}
+
+/** Parse a compatibility flag the way gajae-code does (accepts the common aliases). */
+export function parseProviderCompatibility(value: string): ProviderCompatibility {
+  const v = value.trim().toLowerCase();
+  if (v === "openai" || v === "openai-compatible" || v === "oai" || v === "chat" || v === "completions") return "openai";
+  if (v === "anthropic" || v === "anthropic-compatible" || v === "claude" || v === "messages") return "anthropic";
+  throw new Error(`Provider compatibility must be 'openai' or 'anthropic' (got '${value}').`);
+}
+
+/**
+ * Normalize + validate a base URL. Rejects anything that is not an absolute http(s)
+ * URL so a typo ("localhost:1234") fails at registration time with a clear message
+ * instead of at the first inference call with an opaque fetch error.
+ */
+export function normalizeCustomBaseUrl(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) throw new Error("Base URL is required (e.g. --base-url https://api.example.com/v1).");
+  // `new URL("localhost:1234/v1")` PARSES — as scheme "localhost:" — so a missing scheme
+  // would otherwise surface as a confusing "must use http or https (got 'localhost')".
+  // Check for the authority marker first and give the actionable hint instead.
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    throw new Error(`Invalid base URL '${raw}' — include the scheme, e.g. https://api.example.com/v1`);
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`Invalid base URL '${raw}' — include the scheme, e.g. https://api.example.com/v1`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Base URL must use http or https (got '${parsed.protocol.replace(":", "")}').`);
+  }
+  if (!parsed.hostname) throw new Error(`Invalid base URL '${raw}' — no host.`);
+  // Keep the path (gateways live under /v1, /api/v1, /openai/v1 …); drop a trailing
+  // slash so `${base}/chat/completions` never produces a double slash.
+  const path = parsed.pathname.replace(/\/+$/, "");
+  return `${parsed.origin}${path}${parsed.search}`;
+}
+
+/** `sk-abcd…wxyz` — never print a raw key back to the user or a log. */
+export function redactSecret(secret: string): string {
+  const trimmed = secret.trim();
+  if (!trimmed) return "";
+  if (trimmed.length <= REDACT_PREFIX + REDACT_SUFFIX) return "***";
+  return `${trimmed.slice(0, REDACT_PREFIX)}…${trimmed.slice(-REDACT_SUFFIX)}`;
+}
+
+/** Split/flatten `--model a,b --model c` into a deduped, ordered id list. */
+export function parseModelList(values: readonly string[]): string[] {
+  const out = values
+    .flatMap(v => v.split(","))
+    .map(v => v.trim())
+    .filter(v => v.length > 0);
+  return [...new Set(out)];
+}
+
+/** Strip a `<id>/` routing prefix from a model id, if present. */
+export function stripProviderPrefix(id: string, modelId: string): string {
+  const prefix = `${id}/`;
+  return modelId.startsWith(prefix) ? modelId.slice(prefix.length) : modelId;
+}
+
+/**
+ * Normalize one persisted entry into the catalog shape every generic path consumes.
+ * Throws when the entry is unusable (bad id / base URL) so a corrupt config surfaces
+ * as one clear error rather than a provider that 404s on every call.
+ */
+export function toCustomProviderDef(rawId: string, cfg: CustomProviderConfig): CustomProviderDef {
+  const id = assertValidProviderId(rawId);
+  const baseUrl = normalizeCustomBaseUrl(cfg.baseUrl);
+  const protocol: ProviderCompatibility = cfg.protocol === "anthropic" ? "anthropic" : "openai";
+  const apiKeyEnv = cfg.apiKeyEnv?.trim() || defaultApiKeyEnv(id);
+  const models = (cfg.models ?? []).map(m => stripProviderPrefix(id, m.trim())).filter(Boolean);
+  const bareDefault = cfg.defaultModel ? stripProviderPrefix(id, cfg.defaultModel.trim()) : models[0];
+  return {
+    custom: true,
+    name: id as ProviderName,
+    label: cfg.label?.trim() || id,
+    baseUrl,
+    apiKeyEnv,
+    // `defaultModel` is provider-qualified in the catalog contract; fall back to a
+    // placeholder that makes the missing-model state obvious instead of routing to "".
+    defaultModel: bareDefault ? `${id}/${bareDefault}` : `${id}/`,
+    knownModels: models.length ? models : undefined,
+    protocol,
+    thinkingFormat: cfg.thinkingFormat,
+    literalApiKey: cfg.apiKey?.trim() || undefined,
+    preset: cfg.preset,
+  };
+}
+
+/** Which credential source a def will actually use at call time. */
+export function credentialSourceOf(def: CustomProviderDef, env: NodeJS.ProcessEnv = process.env): CredentialSource {
+  if (env[def.apiKeyEnv]) return "env";
+  if (def.literalApiKey) return "literal";
+  return "none";
+}
+
+/**
+ * Resolve the API key for a custom provider. Env wins over the stored literal so a
+ * rotated key in the shell takes effect without editing config.json.
+ */
+export function resolveCustomApiKey(def: CustomProviderDef, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return env[def.apiKeyEnv] || def.literalApiKey || undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime registry
+// ---------------------------------------------------------------------------
+
+let CUSTOM_DEFS: readonly CustomProviderDef[] = [];
+let CUSTOM_BY_ID = new Map<string, CustomProviderDef>();
+
+/** Listeners fired whenever the custom set changes (registry rebuild, status refresh). */
+const listeners = new Set<(defs: readonly CustomProviderDef[]) => void>();
+
+export function onCustomProvidersChanged(fn: (defs: readonly CustomProviderDef[]) => void): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/**
+ * Replace the active custom provider set. Invalid entries are SKIPPED (with their
+ * reason returned) rather than throwing: one bad hand-edited row must never stop jeo
+ * from starting with the rest of the user's providers intact.
+ */
+export function setCustomProviders(map: CustomProviderMap | undefined): { defs: readonly CustomProviderDef[]; errors: string[] } {
+  const defs: CustomProviderDef[] = [];
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  for (const [rawId, cfg] of Object.entries(map ?? {})) {
+    if (!cfg || typeof cfg !== "object") {
+      errors.push(`customProviders.${rawId}: not an object — skipped.`);
+      continue;
+    }
+    try {
+      const def = toCustomProviderDef(rawId, cfg);
+      if (seen.has(def.name)) {
+        errors.push(`customProviders.${rawId}: duplicate id '${def.name}' — skipped.`);
+        continue;
+      }
+      seen.add(def.name);
+      defs.push(def);
+    } catch (err) {
+      errors.push(`customProviders.${rawId}: ${(err as Error).message}`);
+    }
+  }
+  CUSTOM_DEFS = defs;
+  CUSTOM_BY_ID = new Map(defs.map(d => [d.name, d]));
+  for (const fn of listeners) {
+    try {
+      fn(CUSTOM_DEFS);
+    } catch {
+      // A misbehaving listener must not break provider registration.
+    }
+  }
+  return { defs: CUSTOM_DEFS, errors };
+}
+
+/** Every registered custom provider, in config order. */
+export function customProviderDefs(): readonly CustomProviderDef[] {
+  return CUSTOM_DEFS;
+}
+
+/** Lookup by id (already normalized or not). */
+export function customProviderDef(name: string): CustomProviderDef | undefined {
+  return CUSTOM_BY_ID.get(normalizeProviderId(name));
+}
+
+/** True when `name` is a user-registered custom provider. */
+export function isCustomProvider(name: string): boolean {
+  return CUSTOM_BY_ID.has(normalizeProviderId(name));
+}
+
+/** All custom provider ids. */
+export function customProviderNames(): readonly ProviderName[] {
+  return CUSTOM_DEFS.map(d => d.name);
+}
+
+/** Drop every registered custom provider (test isolation / `/provider add clear`). */
+export function clearCustomProviders(): void {
+  setCustomProviders({});
+}

package/src/ai/providers/openai-compatible-catalog.ts

@@ -1,4 +1,5 @@
 import type { ProviderName } from "../types";
+import { customProviderDef, customProviderDefs, customProviderNames } from "./custom-providers";
 
 /**
  * gjc-style data-driven provider catalog. Every entry here is an OpenAI-compatible
@@ -81,19 +82,44 @@ export const OPENAI_COMPAT_PROVIDERS: readonly OpenAICompatProviderDef[] = [
 
 const BY_NAME = new Map<string, OpenAICompatProviderDef>(OPENAI_COMPAT_PROVIDERS.map(p => [p.name, p]));
 
-/** All catalog provider names (for PROVIDER_NAMES / AuthProvider unions). */
+/** All BUILT-IN catalog provider names (for PROVIDER_NAMES / AuthProvider unions). */
 export const OPENAI_COMPAT_NAMES: readonly ProviderName[] = OPENAI_COMPAT_PROVIDERS.map(p => p.name);
 
+/** True when `name` is one of the compiled-in catalog rows (excludes custom providers). */
+export function isBuiltinCompatProvider(name: string): boolean {
+  return BY_NAME.has(name);
+}
+
+/** Built-in catalog rows PLUS the user's registered custom providers, in that order.
+ *  Every generic path (discovery, routing, status, pickers) reads this so a custom
+ *  provider behaves exactly like a compiled-in one. */
+export function allCompatProviders(): readonly OpenAICompatProviderDef[] {
+  const custom = customProviderDefs();
+  return custom.length ? [...OPENAI_COMPAT_PROVIDERS, ...custom] : OPENAI_COMPAT_PROVIDERS;
+}
+
+/** Built-in + custom compat provider names. */
+export function allCompatNames(): readonly ProviderName[] {
+  const custom = customProviderNames();
+  return custom.length ? [...OPENAI_COMPAT_NAMES, ...custom] : OPENAI_COMPAT_NAMES;
+}
+
 /** Subscription/plan-tier provider names (coding-plan, portal, token-plan, code) — surfaced
  *  under the `/provider` "OAuth / subscription" onboarding path rather than the generic API-key list. */
 export const SUBSCRIPTION_PROVIDER_NAMES: readonly ProviderName[] = OPENAI_COMPAT_PROVIDERS.filter(p => p.subscription).map(p => p.name);
 
-/** Catalog entry for a provider name, or undefined when it is not catalog-driven. */
+/**
+ * Catalog entry for a provider name, or undefined when it is not catalog-driven.
+ *
+ * Built-ins win over custom entries with the same id — `assertValidProviderId` already
+ * rejects reserved ids at registration, so this is defence-in-depth for a hand-edited
+ * config that predates the check: a stale user row can never shadow a shipped provider.
+ */
 export function openaiCompatDef(name: string): OpenAICompatProviderDef | undefined {
-  return BY_NAME.get(name);
+  return BY_NAME.get(name) ?? customProviderDef(name);
 }
 
-/** True when `name` is a catalog-driven OpenAI-compatible provider. */
+/** True when `name` is a catalog-driven OpenAI-compatible provider (built-in or custom). */
 export function isOpenAICompatProvider(name: string): boolean {
-  return BY_NAME.has(name);
+  return BY_NAME.has(name) || customProviderDef(name) !== undefined;
 }

package/src/ai/providers/provider-presets.ts

@@ -0,0 +1,292 @@
+/**
+ * Provider presets — one-flag onboarding for well-known OpenAI/Anthropic-compatible
+ * gateways (gjc/gajae-code parity).
+ *
+ * A preset is a pre-filled {@link CustomProviderConfig}: base URL, wire protocol,
+ * credential env var, and (when the endpoint has a fixed catalog) the model ids. It
+ * exists so the common case is `jeo provider add --preset litellm --base-url <url>`
+ * instead of remembering four flags and an exact URL.
+ *
+ * Two kinds:
+ *  - FIXED presets pin a base URL (the vendor runs the endpoint).
+ *  - PARAMETERIZED presets (`parameterized: true`) are proxies/gateways the USER runs,
+ *    so `--base-url` is required and the preset only supplies protocol + env var +
+ *    discovery expectations.
+ *
+ * Presets never contain secrets. `apiKeyEnv` names the environment variable to read.
+ */
+import type { CustomProviderConfig, ProviderCompatibility } from "./custom-providers";
+
+export interface ProviderPreset {
+  /** Canonical preset id (what the user types after `--preset`). */
+  readonly id: string;
+  /** Extra accepted spellings. */
+  readonly aliases: readonly string[];
+  /** Display name. */
+  readonly label: string;
+  /** One-line description shown by `/provider presets`. */
+  readonly description: string;
+  /** Wire protocol. */
+  readonly protocol: ProviderCompatibility;
+  /** Default provider id created when the user does not pass `--id`. */
+  readonly providerId: string;
+  /** Fixed base URL. Absent for parameterized presets. */
+  readonly baseUrl?: string;
+  /** Env var that supplies the API key. */
+  readonly apiKeyEnv: string;
+  /** Known model ids (BARE). Absent when the endpoint supports live `/models`. */
+  readonly models?: readonly string[];
+  /** Preferred default model (BARE). */
+  readonly defaultModel?: string;
+  /** Native-reasoning enablement for this backend. */
+  readonly thinkingFormat?: CustomProviderConfig["thinkingFormat"];
+  /** True when the user must supply `--base-url` (self-hosted / account-scoped gateway). */
+  readonly parameterized?: boolean;
+}
+
+export const PROVIDER_PRESETS: readonly ProviderPreset[] = [
+  // --- Self-hosted / user-run gateways (base URL required) --------------------
+  {
+    id: "openai-compatible-proxy",
+    aliases: ["openai-proxy", "compatible-proxy", "custom-proxy", "proxy"],
+    label: "OpenAI-Compatible Proxy",
+    description: "Generic OpenAI-compatible gateway with live /models discovery (requires --base-url)",
+    protocol: "openai",
+    providerId: "openai-compatible-proxy",
+    apiKeyEnv: "OPENAI_COMPATIBLE_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "anthropic-compatible-proxy",
+    aliases: ["anthropic-proxy", "claude-proxy", "messages-proxy"],
+    label: "Anthropic-Compatible Proxy",
+    description: "Generic Anthropic Messages gateway, /v1/messages wire format (requires --base-url)",
+    protocol: "anthropic",
+    providerId: "anthropic-compatible-proxy",
+    apiKeyEnv: "ANTHROPIC_COMPATIBLE_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "litellm",
+    aliases: ["litellm-proxy"],
+    label: "LiteLLM Proxy",
+    description: "Self-hosted LiteLLM proxy; its catalog is whatever your config.yaml routes (requires --base-url)",
+    protocol: "openai",
+    providerId: "litellm-proxy",
+    apiKeyEnv: "LITELLM_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "vllm",
+    aliases: ["vllm-server"],
+    label: "vLLM",
+    description: "Self-hosted vLLM OpenAI-compatible server (requires --base-url, usually http://host:8000/v1)",
+    protocol: "openai",
+    providerId: "vllm",
+    apiKeyEnv: "VLLM_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "sglang",
+    aliases: ["sgl"],
+    label: "SGLang",
+    description: "Self-hosted SGLang OpenAI-compatible server (requires --base-url, usually http://host:30000/v1)",
+    protocol: "openai",
+    providerId: "sglang",
+    apiKeyEnv: "SGLANG_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "llama-cpp",
+    aliases: ["llamacpp", "llama.cpp", "llama-server"],
+    label: "llama.cpp server",
+    description: "Self-hosted llama.cpp server (requires --base-url, usually http://localhost:8080/v1)",
+    protocol: "openai",
+    providerId: "llama-cpp",
+    apiKeyEnv: "LLAMA_CPP_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "azure-openai",
+    aliases: ["azure", "aoai"],
+    label: "Azure OpenAI",
+    description: "Azure OpenAI deployment served over the OpenAI wire format (requires --base-url with api-version)",
+    protocol: "openai",
+    providerId: "azure-openai",
+    apiKeyEnv: "AZURE_OPENAI_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "vercel-ai-gateway",
+    aliases: ["vercel", "ai-gateway"],
+    label: "Vercel AI Gateway",
+    description: "Vercel AI Gateway OpenAI-compatible endpoint (requires --base-url for your gateway)",
+    protocol: "openai",
+    providerId: "vercel-ai-gateway",
+    apiKeyEnv: "AI_GATEWAY_API_KEY",
+    parameterized: true,
+  },
+  {
+    id: "cloudflare-ai-gateway",
+    aliases: ["cloudflare", "cf-gateway"],
+    label: "Cloudflare AI Gateway",
+    description: "Cloudflare AI Gateway OpenAI-compatible endpoint (requires --base-url for your account/gateway)",
+    protocol: "openai",
+    providerId: "cloudflare-ai-gateway",
+    apiKeyEnv: "CLOUDFLARE_AI_GATEWAY_API_KEY",
+    parameterized: true,
+  },
+
+  // --- Vendor-hosted endpoints (fixed base URL) -------------------------------
+  {
+    id: "glm",
+    aliases: ["zai-openai", "z-ai-openai", "bigmodel"],
+    label: "GLM / z.ai (OpenAI wire)",
+    description: "z.ai / BigModel GLM served over the OpenAI wire format",
+    protocol: "openai",
+    providerId: "glm-proxy",
+    baseUrl: "https://api.z.ai/api/paas/v4",
+    apiKeyEnv: "ZAI_API_KEY",
+    models: ["glm-5.2", "glm-5.1", "glm-5", "glm-4.6"],
+    defaultModel: "glm-5.2",
+    thinkingFormat: "zai",
+  },
+  {
+    id: "alibaba-token-plan",
+    aliases: ["alibaba", "token-plan", "dashscope-token-plan"],
+    label: "Alibaba Token Plan",
+    description: "Alibaba Token Plan OpenAI-compatible endpoint (Qwen / GLM / DeepSeek)",
+    protocol: "openai",
+    providerId: "alibaba-token-plan",
+    baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
+    apiKeyEnv: "ALIBABA_TOKEN_PLAN_API_KEY",
+    models: ["qwen3.8-max-preview", "qwen3.8-max", "glm-5.2", "deepseek-v4-pro"],
+    defaultModel: "qwen3.8-max",
+    thinkingFormat: "qwen",
+  },
+  {
+    id: "cline-pass",
+    aliases: ["clinepass", "cline"],
+    label: "ClinePass",
+    description: "ClinePass subscription endpoint with live /models discovery",
+    protocol: "openai",
+    providerId: "cline-pass",
+    baseUrl: "https://api.cline.bot/api/v1",
+    apiKeyEnv: "CLINE_API_KEY",
+  },
+  {
+    id: "commandcode-goat",
+    aliases: ["commandcode", "command-code", "goat"],
+    label: "Command Code GOAT",
+    description: "Command Code GOAT coding-plan endpoint with live /models discovery",
+    protocol: "openai",
+    providerId: "commandcode-goat",
+    baseUrl: "https://api.commandcode.ai/provider/v1",
+    apiKeyEnv: "CMD_API_KEY",
+  },
+  {
+    id: "ollama-cloud",
+    aliases: ["ollama-turbo"],
+    label: "Ollama Cloud",
+    description: "Ollama's hosted OpenAI-compatible endpoint (separate from a local ollama server)",
+    protocol: "openai",
+    providerId: "ollama-cloud",
+    baseUrl: "https://ollama.com/v1",
+    apiKeyEnv: "OLLAMA_API_KEY",
+  },
+  {
+    id: "github-copilot",
+    aliases: ["copilot", "gh-copilot"],
+    label: "GitHub Copilot",
+    description: "GitHub Copilot OpenAI-compatible endpoint (needs a Copilot token in the env var)",
+    protocol: "openai",
+    providerId: "github-copilot",
+    baseUrl: "https://api.githubcopilot.com",
+    apiKeyEnv: "GITHUB_COPILOT_TOKEN",
+  },
+] as const;
+
+const BY_KEY = new Map<string, ProviderPreset>();
+for (const preset of PROVIDER_PRESETS) {
+  BY_KEY.set(preset.id, preset);
+  for (const alias of preset.aliases) BY_KEY.set(alias, preset);
+}
+
+/** Resolve a preset by id or alias (case-insensitive). */
+export function findProviderPreset(value: string | undefined): ProviderPreset | undefined {
+  const key = value?.trim().toLowerCase();
+  return key ? BY_KEY.get(key) : undefined;
+}
+
+/** Every preset id (canonical only) — used by autocomplete and error messages. */
+export const PROVIDER_PRESET_IDS: readonly string[] = PROVIDER_PRESETS.map(p => p.id);
+
+/** Rendered preset list for `/provider presets` and unknown-preset errors. */
+export function formatProviderPresetList(): string[] {
+  return PROVIDER_PRESETS.map(p => {
+    const aliases = p.aliases.length ? ` (aliases: ${p.aliases.join(", ")})` : "";
+    const param = p.parameterized ? " [needs --base-url]" : "";
+    return `  ${p.id}${aliases}${param} — ${p.description}`;
+  });
+}
+
+export interface PresetExpandInput {
+  /** Preset id or alias. */
+  preset: string;
+  /** Override the provider id (defaults to the preset's `providerId`). */
+  id?: string;
+  /** Required for parameterized presets; rejected for fixed ones. */
+  baseUrl?: string;
+  /** Override the credential env var. */
+  apiKeyEnv?: string;
+  /** Literal key (stored in config, redacted on display). */
+  apiKey?: string;
+  /** Extra/override model ids. */
+  models?: readonly string[];
+}
+
+export interface PresetExpansion {
+  id: string;
+  config: CustomProviderConfig;
+  preset: ProviderPreset;
+}
+
+/**
+ * Expand a preset into a concrete provider id + config, validating the flag
+ * combination the way gajae-code's onboarding does (fixed presets reject
+ * `--base-url`; parameterized presets require it).
+ */
+export function expandProviderPreset(input: PresetExpandInput): PresetExpansion {
+  const preset = findProviderPreset(input.preset);
+  if (!preset) {
+    throw new Error(
+      `Unknown provider preset '${input.preset}'. Available presets:\n${formatProviderPresetList().join("\n")}`,
+    );
+  }
+  if (preset.parameterized && !input.baseUrl?.trim()) {
+    throw new Error(`Preset '${preset.id}' needs your endpoint: pass --base-url <url>.`);
+  }
+  if (!preset.parameterized && input.baseUrl?.trim() && input.baseUrl.trim() !== preset.baseUrl) {
+    throw new Error(
+      `Preset '${preset.id}' pins ${preset.baseUrl}; drop --base-url, or register a fully custom provider with --compat ${preset.protocol}.`,
+    );
+  }
+  const baseUrl = input.baseUrl?.trim() || preset.baseUrl;
+  if (!baseUrl) throw new Error(`Preset '${preset.id}' has no base URL — pass --base-url <url>.`);
+  const models = input.models && input.models.length > 0 ? [...input.models] : preset.models ? [...preset.models] : undefined;
+  return {
+    id: (input.id?.trim() || preset.providerId).toLowerCase(),
+    preset,
+    config: {
+      label: preset.label,
+      baseUrl,
+      protocol: preset.protocol,
+      apiKeyEnv: input.apiKeyEnv?.trim() || preset.apiKeyEnv,
+      apiKey: input.apiKey?.trim() || undefined,
+      models,
+      defaultModel: preset.defaultModel ?? models?.[0],
+      thinkingFormat: preset.thinkingFormat,
+      preset: preset.id,
+    },
+  };
+}