jeopi-ai 16.2.13

package/src/registry/ollama-cloud.ts

@@ -0,0 +1,36 @@
+import * as AIError from "../error";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const OLLAMA_CLOUD_KEYS_URL = "https://ollama.com/settings/keys";
+
+export async function loginOllamaCloud(options: OAuthController): Promise<string> {
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+	if (!options.onPrompt) {
+		throw new AIError.ConfigurationError("Interactive prompt is required for Ollama Cloud login");
+	}
+	options.onAuth?.({
+		url: OLLAMA_CLOUD_KEYS_URL,
+		instructions: "Create an Ollama Cloud API key, then paste it here.",
+	});
+	const apiKey = await options.onPrompt({
+		message: "Paste your Ollama Cloud API key",
+		placeholder: "ollama-cloud-api-key",
+	});
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError("Ollama Cloud API key is required");
+	}
+	return trimmed;
+}
+
+export const ollamaCloudProvider = {
+	id: "ollama-cloud",
+	name: "Ollama Cloud",
+	login: (cb: OAuthLoginCallbacks) => loginOllamaCloud(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/ollama.ts

@@ -0,0 +1,43 @@
+import * as AIError from "../error";
+import type { OAuthController } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const OLLAMA_DOCS_URL = "https://github.com/ollama/ollama/blob/main/docs/api.md";
+
+/**
+ * Login to Ollama.
+ *
+ * Returns a trimmed API key/token string. Empty string means local no-auth mode.
+ */
+export async function loginOllama(options: OAuthController): Promise<string> {
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+	if (!options.onPrompt) {
+		return "";
+	}
+
+	options.onAuth?.({
+		url: OLLAMA_DOCS_URL,
+		instructions:
+			"Optional: paste an Ollama API key/token for authenticated hosts. Leave empty for local no-auth mode.",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Ollama API key/token (optional)",
+		placeholder: "ollama-local",
+		allowEmpty: true,
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	return apiKey.trim();
+}
+
+export const ollamaProvider = {
+	id: "ollama",
+	name: "Ollama (Local OpenAI-compatible)",
+	login: loginOllama,
+} as const satisfies ProviderDefinition;

package/src/registry/openai-codex-device.ts

@@ -0,0 +1,18 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const openaiCodexDeviceProvider = {
+	id: "openai-codex-device",
+	name: "ChatGPT Plus/Pro (Codex, headless/device)",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginOpenAICodexDevice } = await import("./oauth/openai-codex");
+		return loginOpenAICodexDevice(cb);
+	},
+	refreshToken: async (credentials: OAuthCredentials) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { refreshOpenAICodexToken } = await import("./oauth/openai-codex");
+		return refreshOpenAICodexToken(credentials.refresh);
+	},
+	storeCredentialsAs: "openai-codex",
+} as const satisfies ProviderDefinition;

package/src/registry/openai-codex.ts

@@ -0,0 +1,19 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const openaiCodexProvider = {
+	id: "openai-codex",
+	name: "ChatGPT Plus/Pro (Codex Subscription)",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginOpenAICodex } = await import("./oauth/openai-codex");
+		return loginOpenAICodex(cb);
+	},
+	refreshToken: async (credentials: OAuthCredentials) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { refreshOpenAICodexToken } = await import("./oauth/openai-codex");
+		return refreshOpenAICodexToken(credentials.refresh);
+	},
+	callbackPort: 1455,
+	pasteCodeFlow: true,
+} as const satisfies ProviderDefinition;

package/src/registry/openai.ts

@@ -0,0 +1,6 @@
+import type { ProviderDefinition } from "./types";
+
+export const openaiProvider = {
+	id: "openai",
+	name: "OpenAI",
+} as const satisfies ProviderDefinition;

package/src/registry/opencode-go.ts

@@ -0,0 +1,12 @@
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const opencodeGoProvider = {
+	id: "opencode-go",
+	name: "OpenCode Go",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginOpenCode } = await import("./oauth/opencode");
+		return loginOpenCode(cb);
+	},
+} as const satisfies ProviderDefinition;

package/src/registry/opencode-zen.ts

@@ -0,0 +1,12 @@
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const opencodeZenProvider = {
+	id: "opencode-zen",
+	name: "OpenCode Zen",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginOpenCode } = await import("./oauth/opencode");
+		return loginOpenCode(cb);
+	},
+} as const satisfies ProviderDefinition;

package/src/registry/openrouter.ts

@@ -0,0 +1,28 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+/** OpenRouter login flow (API key paste, validated via /auth/key).
+ *
+ * `/api/v1/models` is public and returns 200 for any bearer (including bogus),
+ * so it cannot validate auth. `/api/v1/auth/key` is the canonical "who am I"
+ * endpoint — 200 for valid keys, 401 otherwise.
+ */
+export const loginOpenRouter = createApiKeyLogin({
+	providerLabel: "OpenRouter",
+	authUrl: "https://openrouter.ai/keys",
+	instructions: "Create or copy your OpenRouter API key",
+	promptMessage: "Paste your OpenRouter API key",
+	placeholder: "sk-or-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "OpenRouter",
+		modelsUrl: "https://openrouter.ai/api/v1/auth/key",
+	},
+});
+
+export const openrouterProvider = {
+	id: "openrouter",
+	name: "OpenRouter",
+	login: (cb: OAuthLoginCallbacks) => loginOpenRouter(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/parallel.ts

@@ -0,0 +1,45 @@
+import * as AIError from "../error";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const AUTH_URL = "https://platform.parallel.ai/settings?tab=api-keys";
+
+/**
+ * Login to Parallel.
+ *
+ * Opens browser to the API keys page, prompts the user to paste their API key,
+ * and returns the API key directly.
+ */
+export async function loginParallel(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError("Parallel");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Parallel API key from the Parallel settings page.",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Parallel API key",
+		placeholder: "sk_...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError();
+	}
+
+	return trimmed;
+}
+
+export const parallelProvider = {
+	id: "parallel",
+	name: "Parallel",
+	envKeys: "PARALLEL_API_KEY",
+	login: (cb: OAuthLoginCallbacks) => loginParallel(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/perplexity.ts

@@ -0,0 +1,13 @@
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const perplexityProvider = {
+	id: "perplexity",
+	name: "Perplexity (Pro/Max)",
+	envKeys: "PERPLEXITY_API_KEY",
+	login: async (cb: OAuthLoginCallbacks) => {
+		// Lazy import: keep heavy OAuth flow modules out of the eager registry graph.
+		const { loginPerplexity } = await import("./oauth/perplexity");
+		return loginPerplexity(cb);
+	},
+} as const satisfies ProviderDefinition;

package/src/registry/qianfan.ts

@@ -0,0 +1,27 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const AUTH_URL = "https://console.bce.baidu.com/qianfan/ais/console/apiKey";
+const API_BASE_URL = "https://qianfan.baidubce.com/v2";
+const VALIDATION_MODEL = "deepseek-v3.2";
+
+export const loginQianfan = createApiKeyLogin({
+	providerLabel: "Qianfan",
+	authUrl: AUTH_URL,
+	instructions: "Copy your Qianfan API key from the console",
+	promptMessage: "Paste your Qianfan API key",
+	placeholder: "bce-v3/ALTAK-...",
+	validation: {
+		kind: "chat-completions",
+		provider: "qianfan",
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+	},
+});
+
+export const qianfanProvider = {
+	id: "qianfan",
+	name: "Qianfan",
+	login: (cb: OAuthLoginCallbacks) => loginQianfan(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/qwen-portal.ts

@@ -0,0 +1,50 @@
+import * as AIError from "../error";
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const AUTH_URL = "https://chat.qwen.ai";
+const API_BASE_URL = "https://portal.qwen.ai/v1";
+const VALIDATION_MODEL = "coder-model";
+
+export async function loginQwenPortal(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError("Qwen Portal");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Qwen OAuth token or API key",
+	});
+
+	const token = await options.onPrompt({
+		message: "Paste your Qwen OAuth token or API key",
+		placeholder: "sk-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	const trimmed = token.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError("Qwen token/API key is required");
+	}
+
+	options.onProgress?.("Validating credentials...");
+	await validateOpenAICompatibleApiKey({
+		provider: "qwen-portal",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+
+	return trimmed;
+}
+
+export const qwenPortalProvider = {
+	id: "qwen-portal",
+	name: "Qwen Portal",
+	login: (cb: OAuthLoginCallbacks) => loginQwenPortal(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/registry.ts

@@ -0,0 +1,161 @@
+import type { KnownProvider } from "jeopi-catalog";
+import { aimlApiProvider } from "./aimlapi";
+import { alibabaCodingPlanProvider } from "./alibaba-coding-plan";
+import { amazonBedrockProvider } from "./amazon-bedrock";
+import { anthropicProvider } from "./anthropic";
+import { azureProvider } from "./azure";
+import { cerebrasProvider } from "./cerebras";
+import { cloudflareAiGatewayProvider } from "./cloudflare-ai-gateway";
+import { coreWeaveProvider } from "./coreweave";
+import { cursorProvider } from "./cursor";
+import { deepseekProvider } from "./deepseek";
+import { devinProvider } from "./devin";
+import { firepassProvider } from "./firepass";
+import { fireworksProvider } from "./fireworks";
+import { githubCopilotProvider } from "./github-copilot";
+import { gitlabDuoProvider } from "./gitlab-duo";
+import { gitLabDuoWorkflowProvider } from "./gitlab-duo-workflow";
+import { googleProvider } from "./google";
+import { googleAntigravityProvider } from "./google-antigravity";
+import { googleGeminiCliProvider } from "./google-gemini-cli";
+import { googleVertexProvider } from "./google-vertex";
+import { groqProvider } from "./groq";
+import { huggingfaceProvider } from "./huggingface";
+import { kagiProvider } from "./kagi";
+import { kiloProvider } from "./kilo";
+import { kimiCodeProvider } from "./kimi-code";
+import { litellmProvider } from "./litellm";
+import { llamaCppProvider } from "./llama-cpp";
+import { lmStudioProvider } from "./lm-studio";
+import { minimaxProvider } from "./minimax";
+import { minimaxCodeProvider } from "./minimax-code";
+import { minimaxCodeCnProvider } from "./minimax-code-cn";
+import { mistralProvider } from "./mistral";
+import { moonshotProvider } from "./moonshot";
+import { nanogptProvider } from "./nanogpt";
+import { nvidiaProvider } from "./nvidia";
+import { ollamaProvider } from "./ollama";
+import { ollamaCloudProvider } from "./ollama-cloud";
+import { openaiProvider } from "./openai";
+import { openaiCodexProvider } from "./openai-codex";
+import { openaiCodexDeviceProvider } from "./openai-codex-device";
+import { opencodeGoProvider } from "./opencode-go";
+import { opencodeZenProvider } from "./opencode-zen";
+import { openrouterProvider } from "./openrouter";
+import { parallelProvider } from "./parallel";
+import { perplexityProvider } from "./perplexity";
+import { qianfanProvider } from "./qianfan";
+import { qwenPortalProvider } from "./qwen-portal";
+import { sakanaProvider } from "./sakana";
+import { syntheticProvider } from "./synthetic";
+import { tavilyProvider } from "./tavily";
+import { togetherProvider } from "./together";
+import type { ProviderDefinition } from "./types";
+import { umansProvider } from "./umans";
+import { veniceProvider } from "./venice";
+import { vercelAiGatewayProvider } from "./vercel-ai-gateway";
+import { vllmProvider } from "./vllm";
+import { waferServerlessProvider } from "./wafer-serverless";
+import { xaiProvider } from "./xai";
+import { xaiOauthProvider } from "./xai-oauth";
+import { xiaomiProvider } from "./xiaomi";
+import { xiaomiTokenPlanAmsProvider } from "./xiaomi-token-plan-ams";
+import { xiaomiTokenPlanCnProvider } from "./xiaomi-token-plan-cn";
+import { xiaomiTokenPlanSgpProvider } from "./xiaomi-token-plan-sgp";
+import { zaiProvider } from "./zai";
+import { zenmuxProvider } from "./zenmux";
+import { zhipuCodingPlanProvider } from "./zhipu-coding-plan";
+
+/**
+ * The single per-provider list. Adding a provider = create `./providers/<id>.ts`
+ * and add its export here. Every legacy structure (`KnownProvider`/`OAuthProvider`
+ * unions, descriptors, env map, login list, refresh/login dispatch, CLI callback
+ * maps) is derived from this registry. Order matches the interactive `/login`
+ * list for the loginable providers; non-login model providers are appended.
+ */
+const ALL = [
+	azureProvider,
+	openaiCodexProvider,
+	anthropicProvider,
+	zaiProvider,
+	kimiCodeProvider,
+	openrouterProvider,
+	githubCopilotProvider,
+	cursorProvider,
+	devinProvider,
+	googleAntigravityProvider,
+	googleGeminiCliProvider,
+	openaiCodexDeviceProvider,
+	xaiOauthProvider,
+	gitlabDuoProvider,
+	gitLabDuoWorkflowProvider,
+	alibabaCodingPlanProvider,
+	aimlApiProvider,
+	zhipuCodingPlanProvider,
+	umansProvider,
+	qwenPortalProvider,
+	sakanaProvider,
+	minimaxCodeProvider,
+	minimaxCodeCnProvider,
+	xiaomiProvider,
+	xiaomiTokenPlanSgpProvider,
+	xiaomiTokenPlanAmsProvider,
+	xiaomiTokenPlanCnProvider,
+	firepassProvider,
+	deepseekProvider,
+	moonshotProvider,
+	cerebrasProvider,
+	fireworksProvider,
+	togetherProvider,
+	nvidiaProvider,
+	huggingfaceProvider,
+	perplexityProvider,
+	qianfanProvider,
+	veniceProvider,
+	syntheticProvider,
+	nanogptProvider,
+	waferServerlessProvider,
+	coreWeaveProvider,
+	vercelAiGatewayProvider,
+	cloudflareAiGatewayProvider,
+	litellmProvider,
+	kiloProvider,
+	zenmuxProvider,
+	opencodeZenProvider,
+	opencodeGoProvider,
+	tavilyProvider,
+	kagiProvider,
+	parallelProvider,
+	ollamaProvider,
+	ollamaCloudProvider,
+	lmStudioProvider,
+	llamaCppProvider,
+	vllmProvider,
+	openaiProvider,
+	googleProvider,
+	googleVertexProvider,
+	xaiProvider,
+	groqProvider,
+	mistralProvider,
+	minimaxProvider,
+	amazonBedrockProvider,
+];
+
+export type RegistryDef = (typeof ALL)[number];
+export const PROVIDER_REGISTRY: readonly ProviderDefinition[] = ALL;
+
+const BY_ID = new Map<string, ProviderDefinition>(ALL.map(p => [p.id, p] as [string, ProviderDefinition]));
+
+export function getProviderDefinition(id: string): ProviderDefinition | undefined {
+	return BY_ID.get(id);
+}
+
+/** Compile-time completeness: every catalog chat-model provider must have a registry definition. */
+type _MissingCatalogProviders = Exclude<KnownProvider, RegistryDef["id"]>;
+type _CheckRegistryComplete = _MissingCatalogProviders extends never
+	? true
+	: ["registry is missing catalog providers", _MissingCatalogProviders];
+true satisfies _CheckRegistryComplete;
+
+/** Loginable providers (those carrying a `login` flow). */
+export type OAuthProviderUnion = Extract<RegistryDef, { login: object }>["id"];

package/src/registry/sakana.ts

@@ -0,0 +1,22 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+export const loginSakana = createApiKeyLogin({
+	providerLabel: "Sakana AI",
+	authUrl: "https://console.sakana.ai/api-keys",
+	instructions: "Copy your API key from the Sakana AI console",
+	promptMessage: "Paste your Sakana AI API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "Sakana AI",
+		modelsUrl: "https://api.sakana.ai/v1/models",
+	},
+});
+
+export const sakanaProvider = {
+	id: "sakana",
+	name: "Sakana AI",
+	login: (cb: OAuthLoginCallbacks) => loginSakana(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/synthetic.ts

@@ -0,0 +1,21 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { ProviderDefinition } from "./types";
+
+export const loginSynthetic = createApiKeyLogin({
+	providerLabel: "Synthetic",
+	authUrl: "https://dev.synthetic.new/docs/api/overview",
+	instructions: "Copy your API key from the Synthetic dashboard",
+	promptMessage: "Paste your Synthetic API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "Synthetic",
+		modelsUrl: "https://api.synthetic.new/openai/v1/models",
+	},
+});
+
+export const syntheticProvider = {
+	id: "synthetic",
+	name: "Synthetic",
+	login: loginSynthetic,
+} as const satisfies ProviderDefinition;

package/src/registry/tavily.ts

@@ -0,0 +1,45 @@
+import * as AIError from "../error";
+import type { OAuthLoginCallbacks } from "./oauth/types";
+import type { ProviderDefinition } from "./types";
+
+const AUTH_URL = "https://app.tavily.com/home";
+
+/**
+ * Login to Tavily.
+ *
+ * Opens browser to API keys page and prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginTavily(options: OAuthLoginCallbacks): Promise<string> {
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError("Tavily");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Tavily API key from the API Keys page.",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Tavily API key",
+		placeholder: "tvly-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError();
+	}
+
+	return trimmed;
+}
+
+export const tavilyProvider = {
+	id: "tavily",
+	name: "Tavily",
+	envKeys: "TAVILY_API_KEY",
+	login: (cb: OAuthLoginCallbacks) => loginTavily(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/together.ts

@@ -0,0 +1,22 @@
+import { createApiKeyLogin } from "./api-key-login";
+import type { ProviderDefinition } from "./types";
+
+export const loginTogether = createApiKeyLogin({
+	providerLabel: "Together",
+	authUrl: "https://api.together.xyz/settings/api-keys",
+	instructions: "Copy your API key from the Together dashboard",
+	promptMessage: "Paste your Together API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "chat-completions",
+		provider: "together",
+		baseUrl: "https://api.together.xyz/v1",
+		model: "moonshotai/Kimi-K2.5",
+	},
+});
+
+export const togetherProvider = {
+	id: "together",
+	name: "Together",
+	login: (cb: Parameters<typeof loginTogether>[0]) => loginTogether(cb),
+} as const satisfies ProviderDefinition;

package/src/registry/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Single-source provider auth model. Every provider — model providers,
+ * gateways, search/tool credentials, and login-only flows — is described by
+ * one {@link ProviderDefinition}. The legacy scattered structures (the
+ * `OAuthProvider` union, `serviceProviderMap`, `builtInOAuthProviders`, the
+ * refresh/login switches, and the CLI callback maps) are all *derived* from
+ * the registry of these definitions. Adding a provider is one new file in
+ * `./providers/` plus one line in `./registry.ts`. Model-catalog metadata
+ * (default model, model-manager factory, catalog discovery) lives in
+ * `jeopi-catalog`'s descriptor table.
+ */
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
+
+/**
+ * API-key environment fallback: either a single env var name (e.g.
+ * `"OPENAI_API_KEY"`) or a resolver that inspects several env vars / probes
+ * the host (Vertex ADC, Bedrock credential chains, …).
+ */
+export type KeyResolver = string | (() => string | undefined);
+
+/**
+ * Declarative description of a single provider's auth/login wiring. All
+ * fields are optional except `id`/`name`; presence of a field opts the
+ * provider into a derived structure:
+ *
+ * - `envKeys` present ⇒ env-var fallback in `getEnvApiKey`, overriding the
+ *   catalog table's `envVars` for that provider.
+ * - `login` present ⇒ member of `OAuthProvider`, shown in the `/login` list
+ *   (unless `showInLoginList === false`) and dispatchable via `AuthStorage.login`.
+ * - `callbackPort` present ⇒ entry in the auth-broker `CALLBACK_PORTS` map.
+ * - `pasteCodeFlow` ⇒ member of `PASTE_CODE_LOGIN_PROVIDERS`.
+ *
+ * Heavy OAuth flow modules MUST be reached through dynamic-import thunks in
+ * `login`/`refreshToken` so they stay out of the eager startup graph.
+ */
+export interface ProviderDefinition {
+	readonly id: string;
+	readonly name: string;
+	/** Login-list availability flag. Defaults to true when shown. */
+	readonly available?: boolean;
+	/** Whether to surface in the interactive login list. Defaults to true when `login` is present. */
+	readonly showInLoginList?: boolean;
+	// --- env-var fallback (the catalog table's `envVars` supplies plain names; set this only for computed resolvers) ---
+	readonly envKeys?: KeyResolver;
+	// --- interactive login (OAuthProviderInterface-compatible) ---
+	readonly login?: (callbacks: OAuthLoginCallbacks) => Promise<OAuthCredentials | string>;
+	readonly refreshToken?: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
+	readonly getApiKey?: (credentials: OAuthCredentials) => string;
+	/** Store OAuth credentials under a different provider id (e.g. `openai-codex-device` ⇒ `openai-codex`). */
+	readonly storeCredentialsAs?: string;
+	// --- coding-agent login UX ---
+	/** Auth-broker local callback-server port. Presence ⇒ entry in `CALLBACK_PORTS`. */
+	readonly callbackPort?: number;
+	/** OAuth flow needs a pasted code/redirect URL rather than a callback server. */
+	readonly pasteCodeFlow?: boolean;
+}