@oh-my-pi/pi-catalog 15.10.11

package/src/models.json.d.ts

@@ -0,0 +1,9 @@
+import type { Api } from "./types";
+
+/** Typed declaration for the generated models.json — only the `api` field matters for type inference. */
+declare const models: {
+	[provider: string]: {
+		[modelId: string]: { readonly api: Api; [key: string]: unknown };
+	};
+};
+export default models;

package/src/models.ts

@@ -0,0 +1,64 @@
+import { buildModel } from "./build";
+import MODELS from "./models.json" with { type: "json" };
+import type { Api, KnownProvider, Model, ModelSpec, Usage } from "./types";
+
+/**
+ * Static bundled model registry loaded from `models.json`.
+ *
+ * This module intentionally exposes compile-time defaults only.
+ * It does not include runtime discovery, models.dev overlays, or on-disk cache state.
+ *
+ * For runtime-aware resolution, use `createModelManager()` / `resolveProviderModels()`.
+ */
+let modelRegistry: Map<string, Map<string, Model<Api>>> | undefined;
+
+/** Build (once) and return the enriched bundled-model registry. Lazy: enrichment of ~12K models is deferred off module load. */
+function getModelRegistry(): Map<string, Map<string, Model<Api>>> {
+	if (modelRegistry === undefined) {
+		modelRegistry = new Map();
+		for (const [provider, models] of Object.entries(MODELS)) {
+			const providerModels = new Map<string, Model<Api>>();
+			for (const [id, model] of Object.entries(models)) {
+				providerModels.set(id, buildModel(model as ModelSpec<Api>));
+			}
+			modelRegistry.set(provider, providerModels);
+		}
+	}
+	return modelRegistry;
+}
+
+export type GeneratedProvider = keyof typeof MODELS;
+
+export function getBundledModel<TApi extends Api = Api>(provider: GeneratedProvider, modelId: string): Model<TApi> {
+	const providerModels = getModelRegistry().get(provider);
+	return providerModels?.get(modelId) as Model<TApi>;
+}
+
+export function getBundledProviders(): KnownProvider[] {
+	return Object.keys(MODELS) as KnownProvider[];
+}
+
+export function getBundledModels(provider: GeneratedProvider): Model<Api>[] {
+	const models = getModelRegistry().get(provider);
+	return models ? (Array.from(models.values()) as Model<Api>[]) : [];
+}
+
+export function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"] {
+	usage.cost.input = (model.cost.input / 1000000) * usage.input;
+	usage.cost.output = (model.cost.output / 1000000) * usage.output;
+	usage.cost.cacheRead = (model.cost.cacheRead / 1000000) * usage.cacheRead;
+	usage.cost.cacheWrite = (model.cost.cacheWrite / 1000000) * usage.cacheWrite;
+	usage.cost.total = usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+	return usage.cost;
+}
+/**
+ * Check if two models are equal by comparing both their id and provider.
+ * Returns false if either model is null or undefined.
+ */
+export function modelsAreEqual<TApi extends Api>(
+	a: Model<TApi> | null | undefined,
+	b: Model<TApi> | null | undefined,
+): boolean {
+	if (!a || !b) return false;
+	return a.id === b.id && a.provider === b.provider;
+}

package/src/provider-models/bundled-references.ts

@@ -0,0 +1,54 @@
+import { getBundledModels, getBundledProviders } from "../models";
+import type { Api, Model, ModelSpec } from "../types";
+
+/**
+ * Project a built `Model` back to spec stage: `compat` becomes the verbatim
+ * sparse override record (`compatConfig`), never the resolved view. Discovery
+ * mappers spread these references into the specs they hand to the model
+ * manager, which rebuilds via `buildModel`.
+ */
+export function toModelSpec<TApi extends Api>(model: Model<TApi>): ModelSpec<TApi> {
+	const { compat: _compat, compatConfig, ...rest } = model;
+	return { ...rest, compat: compatConfig } as ModelSpec<TApi>;
+}
+
+export function createBundledReferenceMap<TApi extends Api>(
+	provider: Parameters<typeof getBundledModels>[0],
+): Map<string, ModelSpec<TApi>> {
+	const references = new Map<string, ModelSpec<TApi>>();
+	for (const model of getBundledModels(provider)) {
+		references.set(model.id, toModelSpec(model as Model<TApi>));
+	}
+	return references;
+}
+
+export function createReferenceResolver<TApi extends Api>(
+	providerRefs: Map<string, ModelSpec<TApi>>,
+): (modelId: string) => ModelSpec<TApi> | undefined {
+	const globalRefs = new Map<string, Model<Api>>();
+	for (const provider of getBundledProviders()) {
+		for (const model of getBundledModels(provider as Parameters<typeof getBundledModels>[0])) {
+			const candidate = model as Model<Api>;
+			const existing = globalRefs.get(candidate.id);
+			if (!existing) {
+				globalRefs.set(candidate.id, candidate);
+			} else if (candidate.contextWindow !== existing.contextWindow) {
+				if (candidate.contextWindow > existing.contextWindow) {
+					globalRefs.set(candidate.id, candidate);
+				}
+			} else if (candidate.maxTokens !== existing.maxTokens) {
+				if (candidate.maxTokens > existing.maxTokens) {
+					globalRefs.set(candidate.id, candidate);
+				}
+			} else if (existing.provider !== "openai" && candidate.provider === "openai") {
+				globalRefs.set(candidate.id, candidate);
+			}
+		}
+	}
+	return (modelId: string) => {
+		const providerRef = providerRefs.get(modelId);
+		if (providerRef) return providerRef;
+		const globalRef = globalRefs.get(modelId);
+		return globalRef ? toModelSpec(globalRef as Model<TApi>) : undefined;
+	};
+}

package/src/provider-models/descriptor-types.ts

@@ -0,0 +1,79 @@
+import type { ModelManagerOptions } from "../model-manager";
+import type { Api, FetchImpl } from "../types";
+
+/** Config passed to a provider's runtime model-manager factory. */
+export type ModelManagerConfig = { apiKey?: string; baseUrl?: string; fetch?: FetchImpl };
+
+/** Catalog discovery configuration for providers that support endpoint-based model listing. */
+export interface CatalogDiscoveryConfig {
+	/** Human-readable name for log messages. */
+	label: string;
+	/**
+	 * Environment variables to check for API keys during catalog generation.
+	 * Defaults to the entry-level `envVars` when omitted.
+	 */
+	envVars?: readonly string[];
+	/** OAuth provider for credential refresh during catalog generation. */
+	oauthProvider?: string;
+	/** When true, catalog discovery proceeds even without credentials. */
+	allowUnauthenticated?: boolean;
+}
+
+/** Unified provider descriptor used by both runtime discovery and catalog generation. */
+export interface ProviderDescriptor {
+	providerId: string;
+	createModelManagerOptions(config: ModelManagerConfig): ModelManagerOptions<Api>;
+	/** Preferred model ID when no explicit selection is made. */
+	defaultModel: string;
+	/** When true, the runtime creates a model manager even without a valid API key (e.g. ollama). */
+	allowUnauthenticated?: boolean;
+	/** When true, successful runtime discovery replaces bundled provider models instead of merging fallback-only IDs. */
+	dynamicModelsAuthoritative?: boolean;
+	/** Catalog discovery configuration. Only providers with this field participate in generate-models.ts. */
+	catalogDiscovery?: CatalogDiscoveryConfig;
+}
+
+/** A provider descriptor that has catalog discovery configured. */
+export type CatalogProviderDescriptor = ProviderDescriptor & { catalogDiscovery: CatalogDiscoveryConfig };
+
+/** Type guard for descriptors with catalog discovery. */
+export function isCatalogDescriptor(d: ProviderDescriptor): d is CatalogProviderDescriptor {
+	return d.catalogDiscovery != null;
+}
+
+/** Whether catalog discovery may run without provider credentials. */
+export function allowsUnauthenticatedCatalogDiscovery(descriptor: CatalogProviderDescriptor): boolean {
+	return descriptor.catalogDiscovery.allowUnauthenticated ?? descriptor.allowUnauthenticated ?? false;
+}
+
+/**
+ * One model provider's catalog-side description. The auth half of a provider
+ * (env keys, OAuth login/refresh flows) lives in `@oh-my-pi/pi-ai`'s registry;
+ * the catalog table below is the single source of truth for ids, default
+ * models, and discovery wiring.
+ *
+ * - Every entry is a member of `KnownProvider`.
+ * - `createModelManagerOptions` present (and not `specialModelManager`) ⇒
+ *   appears in `PROVIDER_DESCRIPTORS` for runtime model discovery.
+ * - `catalogDiscovery` present ⇒ participates in `generate-models.ts`.
+ */
+export interface ProviderCatalogEntry {
+	readonly id: string;
+	/** Preferred model ID when no explicit selection is made. */
+	readonly defaultModel: string;
+	/** Environment variables consulted (in order) for the provider's runtime API-key env fallback. */
+	readonly envVars?: readonly string[];
+	/** Runtime model-manager factory. Omitted for catalog-only providers. */
+	readonly createModelManagerOptions?: (config: ModelManagerConfig) => ModelManagerOptions<Api>;
+	/** When true, the runtime creates a model manager even without a valid API key. */
+	readonly allowUnauthenticated?: boolean;
+	/** When true, successful runtime discovery replaces bundled provider models. */
+	readonly dynamicModelsAuthoritative?: boolean;
+	/** Catalog discovery configuration for generate-models.ts. */
+	readonly catalogDiscovery?: CatalogDiscoveryConfig;
+	/**
+	 * Built bespoke by the coding-agent runtime (OAuth-token-driven managers);
+	 * excluded from `PROVIDER_DESCRIPTORS` even though models are discoverable.
+	 */
+	readonly specialModelManager?: boolean;
+}

package/src/provider-models/descriptors.ts

@@ -0,0 +1,456 @@
+/**
+ * The provider catalog table: one entry per chat-model provider, carrying the
+ * catalog half of what used to live in `@oh-my-pi/pi-ai`'s registry definitions
+ * (default model, runtime model-manager factory, discovery wiring). The auth
+ * half (env keys, OAuth login/refresh) stays in the pi-ai registry, which
+ * type-checks itself against `KnownProvider` from this table.
+ */
+import type { ModelManagerConfig, ProviderCatalogEntry, ProviderDescriptor } from "./descriptor-types";
+import { googleModelManagerOptions, googleVertexModelManagerOptions } from "./google";
+import { ollamaCloudModelManagerOptions } from "./ollama";
+import {
+	aimlApiModelManagerOptions,
+	alibabaCodingPlanModelManagerOptions,
+	anthropicModelManagerOptions,
+	cerebrasModelManagerOptions,
+	cloudflareAiGatewayModelManagerOptions,
+	deepseekModelManagerOptions,
+	firepassModelManagerOptions,
+	fireworksModelManagerOptions,
+	githubCopilotModelManagerOptions,
+	groqModelManagerOptions,
+	huggingfaceModelManagerOptions,
+	kiloModelManagerOptions,
+	kimiCodeModelManagerOptions,
+	litellmModelManagerOptions,
+	lmStudioModelManagerOptions,
+	mistralModelManagerOptions,
+	moonshotModelManagerOptions,
+	nanoGptModelManagerOptions,
+	nvidiaModelManagerOptions,
+	ollamaModelManagerOptions,
+	openaiModelManagerOptions,
+	opencodeGoModelManagerOptions,
+	opencodeZenModelManagerOptions,
+	openrouterModelManagerOptions,
+	qianfanModelManagerOptions,
+	qwenPortalModelManagerOptions,
+	syntheticModelManagerOptions,
+	togetherModelManagerOptions,
+	veniceModelManagerOptions,
+	vercelAiGatewayModelManagerOptions,
+	vllmModelManagerOptions,
+	waferPassModelManagerOptions,
+	waferServerlessModelManagerOptions,
+	xaiModelManagerOptions,
+	xaiOAuthModelManagerOptions,
+	xiaomiModelManagerOptions,
+	zenmuxModelManagerOptions,
+	zhipuCodingPlanModelManagerOptions,
+} from "./openai-compat";
+import { cursorModelManagerOptions, zaiModelManagerOptions } from "./special";
+
+export const CATALOG_PROVIDERS = [
+	{
+		id: "aimlapi",
+		defaultModel: "gpt-4o",
+		envVars: ["AIMLAPI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => aimlApiModelManagerOptions(config),
+		dynamicModelsAuthoritative: true,
+		catalogDiscovery: { label: "AIML API" },
+	},
+	{
+		id: "alibaba-coding-plan",
+		defaultModel: "qwen3.5-plus",
+		envVars: ["ALIBABA_CODING_PLAN_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => alibabaCodingPlanModelManagerOptions(config),
+		catalogDiscovery: { label: "Alibaba Coding Plan" },
+	},
+	{
+		id: "amazon-bedrock",
+		defaultModel: "us.anthropic.claude-opus-4-6-v1",
+	},
+	{
+		id: "anthropic",
+		defaultModel: "claude-opus-4-6",
+		createModelManagerOptions: (config: ModelManagerConfig) => anthropicModelManagerOptions(config),
+	},
+	{
+		id: "cerebras",
+		defaultModel: "zai-glm-4.6",
+		envVars: ["CEREBRAS_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => cerebrasModelManagerOptions(config),
+		catalogDiscovery: { label: "Cerebras" },
+	},
+	{
+		id: "cloudflare-ai-gateway",
+		defaultModel: "claude-sonnet-4-5",
+		envVars: ["CLOUDFLARE_AI_GATEWAY_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => cloudflareAiGatewayModelManagerOptions(config),
+		catalogDiscovery: { label: "Cloudflare AI Gateway" },
+	},
+	{
+		id: "cursor",
+		defaultModel: "claude-sonnet-4-6",
+		envVars: ["CURSOR_ACCESS_TOKEN"],
+		createModelManagerOptions: (config: ModelManagerConfig) => cursorModelManagerOptions(config),
+		catalogDiscovery: { label: "Cursor", envVars: ["CURSOR_API_KEY"], oauthProvider: "cursor" },
+	},
+	{
+		id: "deepseek",
+		defaultModel: "deepseek-v4-pro",
+		envVars: ["DEEPSEEK_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => deepseekModelManagerOptions(config),
+		catalogDiscovery: { label: "DeepSeek" },
+	},
+	{
+		id: "firepass",
+		defaultModel: "kimi-k2.6-turbo",
+		envVars: ["FIREPASS_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => firepassModelManagerOptions(config),
+	},
+	{
+		id: "fireworks",
+		defaultModel: "kimi-k2.6",
+		envVars: ["FIREWORKS_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => fireworksModelManagerOptions(config),
+		catalogDiscovery: { label: "Fireworks" },
+	},
+	{
+		id: "github-copilot",
+		defaultModel: "gpt-4o",
+		envVars: ["COPILOT_GITHUB_TOKEN"],
+		createModelManagerOptions: (config: ModelManagerConfig) => githubCopilotModelManagerOptions(config),
+	},
+	{
+		id: "gitlab-duo",
+		defaultModel: "duo-chat-sonnet-4-5",
+		envVars: ["GITLAB_TOKEN"],
+	},
+	{
+		id: "google",
+		defaultModel: "gemini-2.5-pro",
+		envVars: ["GEMINI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => googleModelManagerOptions(config),
+	},
+	{
+		id: "google-antigravity",
+		defaultModel: "gemini-3-pro-high",
+		specialModelManager: true,
+	},
+	{
+		id: "google-gemini-cli",
+		defaultModel: "gemini-2.5-pro",
+		specialModelManager: true,
+	},
+	{
+		id: "google-vertex",
+		defaultModel: "gemini-3-pro-preview",
+		createModelManagerOptions: (config: ModelManagerConfig) => googleVertexModelManagerOptions(config),
+		allowUnauthenticated: true,
+	},
+	{
+		id: "groq",
+		defaultModel: "openai/gpt-oss-120b",
+		envVars: ["GROQ_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => groqModelManagerOptions(config),
+	},
+	{
+		id: "huggingface",
+		defaultModel: "deepseek-ai/DeepSeek-R1",
+		envVars: ["HUGGINGFACE_HUB_TOKEN", "HF_TOKEN"],
+		createModelManagerOptions: (config: ModelManagerConfig) => huggingfaceModelManagerOptions(config),
+		catalogDiscovery: { label: "Hugging Face" },
+	},
+	{
+		id: "kilo",
+		defaultModel: "anthropic/claude-sonnet-4.5",
+		envVars: ["KILO_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => kiloModelManagerOptions(config),
+		catalogDiscovery: { label: "Kilo Gateway", allowUnauthenticated: true },
+	},
+	{
+		id: "kimi-code",
+		defaultModel: "kimi-k2.5",
+		createModelManagerOptions: (config: ModelManagerConfig) => kimiCodeModelManagerOptions(config),
+		catalogDiscovery: { label: "Kimi Code", envVars: ["KIMI_API_KEY"] },
+	},
+	{
+		id: "litellm",
+		defaultModel: "claude-opus-4-6",
+		envVars: ["LITELLM_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => litellmModelManagerOptions(config),
+		catalogDiscovery: { label: "LiteLLM", allowUnauthenticated: true },
+	},
+	{
+		id: "lm-studio",
+		defaultModel: "llama-3-8b",
+		envVars: ["LM_STUDIO_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => lmStudioModelManagerOptions(config),
+		allowUnauthenticated: true,
+	},
+	{
+		id: "minimax",
+		defaultModel: "MiniMax-M2.5",
+		envVars: ["MINIMAX_API_KEY"],
+	},
+	{
+		id: "minimax-code",
+		defaultModel: "MiniMax-M2.5",
+		envVars: ["MINIMAX_CODE_API_KEY"],
+	},
+	{
+		id: "minimax-code-cn",
+		defaultModel: "MiniMax-M2.5",
+		envVars: ["MINIMAX_CODE_CN_API_KEY"],
+	},
+	{
+		id: "mistral",
+		defaultModel: "devstral-medium-latest",
+		envVars: ["MISTRAL_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => mistralModelManagerOptions(config),
+	},
+	{
+		id: "moonshot",
+		defaultModel: "kimi-k2.5",
+		envVars: ["MOONSHOT_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => moonshotModelManagerOptions(config),
+		catalogDiscovery: { label: "Moonshot" },
+	},
+	{
+		id: "nanogpt",
+		defaultModel: "openai/gpt-5.4",
+		envVars: ["NANO_GPT_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => nanoGptModelManagerOptions(config),
+		catalogDiscovery: { label: "NanoGPT" },
+	},
+	{
+		id: "nvidia",
+		defaultModel: "nvidia/llama-3.1-nemotron-70b-instruct",
+		envVars: ["NVIDIA_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => nvidiaModelManagerOptions(config),
+		catalogDiscovery: { label: "NVIDIA" },
+	},
+	{
+		id: "ollama",
+		defaultModel: "gpt-oss:20b",
+		envVars: ["OLLAMA_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => ollamaModelManagerOptions(config),
+		allowUnauthenticated: true,
+	},
+	{
+		id: "ollama-cloud",
+		defaultModel: "gpt-oss:120b",
+		envVars: ["OLLAMA_CLOUD_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => ollamaCloudModelManagerOptions(config),
+		catalogDiscovery: { label: "Ollama Cloud", oauthProvider: "ollama-cloud" },
+	},
+	{
+		id: "openai",
+		defaultModel: "gpt-5.4",
+		envVars: ["OPENAI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => openaiModelManagerOptions(config),
+	},
+	{
+		id: "openai-codex",
+		defaultModel: "gpt-5.4",
+		envVars: ["OPENAI_CODEX_OAUTH_TOKEN"],
+		specialModelManager: true,
+	},
+	{
+		id: "opencode-go",
+		defaultModel: "kimi-k2.5",
+		envVars: ["OPENCODE_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => opencodeGoModelManagerOptions(config),
+	},
+	{
+		id: "opencode-zen",
+		defaultModel: "claude-sonnet-4-6",
+		envVars: ["OPENCODE_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => opencodeZenModelManagerOptions(config),
+	},
+	{
+		id: "openrouter",
+		defaultModel: "openai/gpt-5.4",
+		envVars: ["OPENROUTER_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => openrouterModelManagerOptions(config),
+		catalogDiscovery: { label: "OpenRouter", allowUnauthenticated: true },
+	},
+	{
+		id: "qianfan",
+		defaultModel: "deepseek-v3.2",
+		envVars: ["QIANFAN_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => qianfanModelManagerOptions(config),
+		catalogDiscovery: { label: "Qianfan" },
+	},
+	{
+		id: "qwen-portal",
+		defaultModel: "coder-model",
+		envVars: ["QWEN_OAUTH_TOKEN", "QWEN_PORTAL_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => qwenPortalModelManagerOptions(config),
+		catalogDiscovery: {
+			label: "Qwen Portal",
+			oauthProvider: "qwen-portal",
+		},
+	},
+	{
+		id: "synthetic",
+		defaultModel: "hf:zai-org/GLM-5.1",
+		envVars: ["SYNTHETIC_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => syntheticModelManagerOptions(config),
+		dynamicModelsAuthoritative: true,
+		catalogDiscovery: { label: "Synthetic" },
+	},
+	{
+		id: "together",
+		defaultModel: "moonshotai/Kimi-K2.5",
+		envVars: ["TOGETHER_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => togetherModelManagerOptions(config),
+		catalogDiscovery: { label: "Together" },
+	},
+	{
+		id: "venice",
+		defaultModel: "llama-3.3-70b",
+		envVars: ["VENICE_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => veniceModelManagerOptions(config),
+		catalogDiscovery: { label: "Venice", allowUnauthenticated: true },
+	},
+	{
+		id: "vercel-ai-gateway",
+		defaultModel: "anthropic/claude-sonnet-4-6",
+		envVars: ["AI_GATEWAY_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => vercelAiGatewayModelManagerOptions(config),
+		catalogDiscovery: {
+			label: "Vercel AI Gateway",
+			envVars: ["VERCEL_AI_GATEWAY_API_KEY"],
+			allowUnauthenticated: true,
+		},
+	},
+	{
+		id: "vllm",
+		defaultModel: "gpt-oss-20b",
+		envVars: ["VLLM_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => vllmModelManagerOptions(config),
+		catalogDiscovery: { label: "vLLM", allowUnauthenticated: true },
+	},
+	{
+		id: "wafer-pass",
+		defaultModel: "GLM-5.1",
+		envVars: ["WAFER_PASS_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => waferPassModelManagerOptions(config),
+		catalogDiscovery: { label: "Wafer Pass", oauthProvider: "wafer-pass" },
+	},
+	{
+		id: "wafer-serverless",
+		defaultModel: "GLM-5.1",
+		envVars: ["WAFER_SERVERLESS_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => waferServerlessModelManagerOptions(config),
+		catalogDiscovery: {
+			label: "Wafer Serverless",
+			oauthProvider: "wafer-serverless",
+		},
+	},
+	{
+		id: "xai",
+		defaultModel: "grok-4-fast-non-reasoning",
+		envVars: ["XAI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => xaiModelManagerOptions(config),
+	},
+	{
+		id: "xai-oauth",
+		defaultModel: "grok-4.3",
+		envVars: ["XAI_OAUTH_TOKEN", "XAI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => xaiOAuthModelManagerOptions(config),
+		catalogDiscovery: {
+			label: "xAI Grok OAuth (SuperGrok)",
+			oauthProvider: "xai-oauth",
+		},
+	},
+	{
+		id: "xiaomi",
+		defaultModel: "mimo-v2-flash",
+		envVars: ["XIAOMI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => xiaomiModelManagerOptions(config),
+		catalogDiscovery: { label: "Xiaomi" },
+	},
+	{
+		id: "xiaomi-token-plan-ams",
+		defaultModel: "mimo-v2.5",
+		envVars: ["XIAOMI_TOKEN_PLAN_AMS_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) =>
+			xiaomiModelManagerOptions({ ...config, providerId: "xiaomi-token-plan-ams", tokenPlanRegion: "ams" }),
+	},
+	{
+		id: "xiaomi-token-plan-cn",
+		defaultModel: "mimo-v2.5",
+		envVars: ["XIAOMI_TOKEN_PLAN_CN_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) =>
+			xiaomiModelManagerOptions({ ...config, providerId: "xiaomi-token-plan-cn", tokenPlanRegion: "cn" }),
+	},
+	{
+		id: "xiaomi-token-plan-sgp",
+		defaultModel: "mimo-v2.5",
+		envVars: ["XIAOMI_TOKEN_PLAN_SGP_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) =>
+			xiaomiModelManagerOptions({ ...config, providerId: "xiaomi-token-plan-sgp", tokenPlanRegion: "sgp" }),
+	},
+	{
+		id: "zai",
+		defaultModel: "glm-5.1",
+		envVars: ["ZAI_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => zaiModelManagerOptions(config),
+		catalogDiscovery: { label: "zAI" },
+	},
+	{
+		id: "zenmux",
+		defaultModel: "anthropic/claude-opus-4.6",
+		envVars: ["ZENMUX_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => zenmuxModelManagerOptions(config),
+		catalogDiscovery: { label: "ZenMux" },
+	},
+	{
+		id: "zhipu-coding-plan",
+		defaultModel: "glm-5.1",
+		envVars: ["ZHIPU_API_KEY"],
+		createModelManagerOptions: (config: ModelManagerConfig) => zhipuCodingPlanModelManagerOptions(config),
+		catalogDiscovery: { label: "Zhipu Coding Plan" },
+	},
+] as const satisfies readonly ProviderCatalogEntry[];
+
+/** Chat-model providers — every entry in the catalog table. */
+export type KnownProvider = (typeof CATALOG_PROVIDERS)[number]["id"];
+
+/**
+ * Runtime model-discovery descriptors: every catalog provider that exposes a
+ * standard model-manager factory. Special-managed providers
+ * (`google-antigravity`/`google-gemini-cli`/`openai-codex`) are built bespoke in
+ * the coding-agent runtime and are excluded here.
+ */
+const CATALOG_ENTRY_LIST: readonly ProviderCatalogEntry[] = CATALOG_PROVIDERS;
+
+export const PROVIDER_DESCRIPTORS: readonly ProviderDescriptor[] = CATALOG_ENTRY_LIST.flatMap(provider => {
+	if (!provider.createModelManagerOptions || provider.specialModelManager) {
+		return [];
+	}
+	return [
+		{
+			providerId: provider.id,
+			defaultModel: provider.defaultModel,
+			createModelManagerOptions: provider.createModelManagerOptions,
+			allowUnauthenticated: provider.allowUnauthenticated,
+			dynamicModelsAuthoritative: provider.dynamicModelsAuthoritative,
+			catalogDiscovery: provider.catalogDiscovery
+				? { ...provider.catalogDiscovery, envVars: provider.catalogDiscovery.envVars ?? provider.envVars ?? [] }
+				: undefined,
+		},
+	];
+});
+
+/** Default model IDs for all known providers, derived from the catalog table. */
+export const DEFAULT_MODEL_PER_PROVIDER: Record<KnownProvider, string> = Object.fromEntries(
+	CATALOG_PROVIDERS.map(provider => [provider.id, provider.defaultModel] as [string, string]),
+) as Record<KnownProvider, string>;
+
+export function getCatalogProviderEntry(id: string): ProviderCatalogEntry | undefined {
+	return CATALOG_PROVIDERS.find(provider => provider.id === id);
+}

package/src/provider-models/discovery-constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Fallback context-window / max-output-token values for models discovered
+ * without limit metadata.
+ *
+ * Kept in a dependency-free leaf module (rather than `openai-compat.ts`) so the
+ * model-discovery helpers in `utils/discovery/*` can import them without pulling
+ * the package root barrel (`@oh-my-pi/pi-ai`) into the model-manager init graph,
+ * which would otherwise form an import cycle through the provider registry.
+ */
+export const UNK_CONTEXT_WINDOW = 222_222;
+export const UNK_MAX_TOKENS = 8_888;