feat(ai): compat entrypoint, core-only root barrel (phase 5)

The root barrel is now core-only and side-effect free: types,
createModels/createProvider, auth substrate, lazyStream/lazyApi, faux,
utils. Generated catalogs, api-registry, env-api-keys, images, global
stream functions, and per-API lazy wrappers leave the root.

New @earendil-works/pi-ai/compat preserves the old surface verbatim as
a strict superset of the root: api-dispatch stream/complete with env
key injection, the builtin registration side effect (skip-if-present so
it cannot clobber earlier overrides), deprecated getModel/getModels/
getProviders aliases of the new getBuiltin* reads in providers/all,
lazy api wrappers + setBedrockProviderModule, and image generation.
Compat dies with the coding-agent ModelManager migration.

Packaging: exports map gains ./compat, ./providers/*, ./api/*;
sideEffects array lists only the effectful modules.

Old-global imports across agent/coding-agent/examples and pi-ai tests
switch to /compat (path-only; compat is a superset). The coding-agent
extension loader resolves the pi-ai ROOT specifier to compat, so
existing user extensions using the old global API keep working at
runtime until compat is removed. vitest configs alias /compat to src;
browser smoke imports old globals from /compat.

packages/ai/src/compat.ts

@@ -1,3 +1,32 @@
+/**
+ * Temporary compatibility entrypoint preserving the old global pi-ai API
+ * surface: api-dispatch `stream()`/`complete()` with env API key injection,
+ * the api-registry, generated catalog reads (`getModel`/`getModels`/
+ * `getProviders`), per-API lazy stream wrappers, and image generation.
+ *
+ * Existing apps switch imports from "@earendil-works/pi-ai" to
+ * "@earendil-works/pi-ai/compat" unchanged; new code uses `createModels()`
+ * and the provider factories. This module is deleted with the coding-agent
+ * ModelManager migration.
+ */
+
+export * from "./api/anthropic-messages.lazy.ts";
+export * from "./api/azure-openai-responses.lazy.ts";
+export * from "./api/bedrock-converse-stream.lazy.ts";
+export * from "./api/google-generative-ai.lazy.ts";
+export * from "./api/google-vertex.lazy.ts";
+export * from "./api/mistral-conversations.lazy.ts";
+export * from "./api/openai-codex-responses.lazy.ts";
+export * from "./api/openai-completions.lazy.ts";
+export * from "./api/openai-responses.lazy.ts";
+export * from "./api-registry.ts";
+export * from "./env-api-keys.ts";
+export * from "./image-models.ts";
+export * from "./images.ts";
+export * from "./images-api-registry.ts";
+export * from "./index.ts";
+export * from "./providers/images/register-builtins.ts";
+
 import { anthropicMessagesApi } from "./api/anthropic-messages.lazy.ts";
 import { azureOpenAIResponsesApi } from "./api/azure-openai-responses.lazy.ts";
 import { bedrockConverseStreamApi } from "./api/bedrock-converse-stream.lazy.ts";
@@ -9,6 +38,7 @@ import { openAICompletionsApi } from "./api/openai-completions.lazy.ts";
 import { openAIResponsesApi } from "./api/openai-responses.lazy.ts";
 import { clearApiProviders, getApiProvider, registerApiProvider } from "./api-registry.ts";
 import { getEnvApiKey } from "./env-api-keys.ts";
+import { getBuiltinModel, getBuiltinModels, getBuiltinProviders } from "./providers/all.ts";
 import type {
 	Api,
 	AssistantMessage,
@@ -21,7 +51,14 @@ import type {
 	StreamOptions,
 } from "./types.ts";
 
-export { getEnvApiKey } from "./env-api-keys.ts";
+/** @deprecated Static catalog read. Use `getBuiltinModel` from "@earendil-works/pi-ai/providers/all" or `Models.getModel()`. */
+export const getModel = getBuiltinModel;
+
+/** @deprecated Static catalog read. Use `getBuiltinModels` from "@earendil-works/pi-ai/providers/all" or `Models.getModels()`. */
+export const getModels = getBuiltinModels;
+
+/** @deprecated Static catalog read. Use `getBuiltinProviders` from "@earendil-works/pi-ai/providers/all" or `Models.getProviders()`. */
+export const getProviders = getBuiltinProviders;
 
 const BUILTIN_APIS: [Api, ProviderStreams][] = [
 	["anthropic-messages", anthropicMessagesApi()],
@@ -35,8 +72,14 @@ const BUILTIN_APIS: [Api, ProviderStreams][] = [
 	["bedrock-converse-stream", bedrockConverseStreamApi()],
 ];
 
+/**
+ * Registers the builtin API implementations into the api-registry without
+ * clobbering existing entries: compat may load after a test or extension has
+ * already registered an override for a builtin api id.
+ */
 export function registerBuiltInApiProviders(): void {
 	for (const [api, streams] of BUILTIN_APIS) {
+		if (getApiProvider(api)) continue;
 		registerApiProvider({ api, stream: streams.stream, streamSimple: streams.streamSimple });
 	}
 }

packages/ai/src/index.ts

@@ -1,40 +1,29 @@
 export type { Static, TSchema } from "typebox";
 export { Type } from "typebox";
 
-export * from "./api/anthropic-messages.lazy.ts";
+// Core only, side-effect free: no generated catalogs, no provider factories,
+// no api-registry, no OAuth implementations, no compat. Provider factories
+// live under "@earendil-works/pi-ai/providers/*", API implementations under
+// "@earendil-works/pi-ai/api/*", the old global API under
+// "@earendil-works/pi-ai/compat".
 export type { AnthropicEffort, AnthropicOptions, AnthropicThinkingDisplay } from "./api/anthropic-messages.ts";
-export * from "./api/azure-openai-responses.lazy.ts";
 export type { AzureOpenAIResponsesOptions } from "./api/azure-openai-responses.ts";
-export * from "./api/bedrock-converse-stream.lazy.ts";
 export type { BedrockOptions, BedrockThinkingDisplay } from "./api/bedrock-converse-stream.ts";
-export * from "./api/google-generative-ai.lazy.ts";
 export type { GoogleOptions } from "./api/google-generative-ai.ts";
 export type { GoogleThinkingLevel } from "./api/google-shared.ts";
-export * from "./api/google-vertex.lazy.ts";
 export type { GoogleVertexOptions } from "./api/google-vertex.ts";
 export * from "./api/lazy.ts";
-export * from "./api/mistral-conversations.lazy.ts";
 export type { MistralOptions } from "./api/mistral-conversations.ts";
-export * from "./api/openai-codex-responses.lazy.ts";
 export type { OpenAICodexResponsesOptions, OpenAICodexWebSocketDebugStats } from "./api/openai-codex-responses.ts";
-export * from "./api/openai-completions.lazy.ts";
 export type { OpenAICompletionsOptions } from "./api/openai-completions.ts";
-export * from "./api/openai-responses.lazy.ts";
 export type { OpenAIResponsesOptions } from "./api/openai-responses.ts";
-export * from "./api-registry.ts";
 export * from "./auth/context.ts";
 export * from "./auth/credential-store.ts";
 export * from "./auth/helpers.ts";
 export * from "./auth/types.ts";
-export * from "./env-api-keys.ts";
-export * from "./image-models.ts";
-export * from "./images.ts";
-export * from "./images-api-registry.ts";
 export * from "./models.ts";
 export * from "./providers/faux.ts";
-export * from "./providers/images/register-builtins.ts";
 export * from "./session-resources.ts";
-export * from "./stream.ts";
 export * from "./types.ts";
 export * from "./utils/diagnostics.ts";
 export * from "./utils/event-stream.ts";

packages/ai/src/models.ts

@@ -12,14 +12,12 @@ import type {
 	OAuthCredential,
 	ProviderAuth,
 } from "./auth/types.ts";
-import { MODELS } from "./models.generated.ts";
 import type {
 	Api,
 	ApiStreamOptions,
 	AssistantMessage,
 	AssistantMessageEventStream,
 	Context,
-	KnownProvider,
 	Model,
 	ModelThinkingLevel,
 	ProviderStreams,
@@ -421,41 +419,6 @@ export function hasApi<TApi extends Api>(model: Model<Api>, api: TApi): model is
 	return model.api === api;
 }
 
-const modelRegistry: Map<string, Map<string, Model<Api>>> = new Map();
-
-// Initialize registry from MODELS on module load
-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, model as Model<Api>);
-	}
-	modelRegistry.set(provider, providerModels);
-}
-
-type ModelApi<
-	TProvider extends KnownProvider,
-	TModelId extends keyof (typeof MODELS)[TProvider],
-> = (typeof MODELS)[TProvider][TModelId] extends { api: infer TApi } ? (TApi extends Api ? TApi : never) : never;
-
-export function getModel<TProvider extends KnownProvider, TModelId extends keyof (typeof MODELS)[TProvider]>(
-	provider: TProvider,
-	modelId: TModelId,
-): Model<ModelApi<TProvider, TModelId>> {
-	const providerModels = modelRegistry.get(provider);
-	return providerModels?.get(modelId as string) as Model<ModelApi<TProvider, TModelId>>;
-}
-
-export function getProviders(): KnownProvider[] {
-	return Array.from(modelRegistry.keys()) as KnownProvider[];
-}
-
-export function getModels<TProvider extends KnownProvider>(
-	provider: TProvider,
-): Model<ModelApi<TProvider, keyof (typeof MODELS)[TProvider]>>[] {
-	const models = modelRegistry.get(provider);
-	return models ? (Array.from(models.values()) as Model<ModelApi<TProvider, keyof (typeof MODELS)[TProvider]>>[]) : [];
-}
-
 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;

packages/ai/src/providers/all.ts

@@ -1,4 +1,6 @@
+import { MODELS } from "../models.generated.ts";
 import { type CreateModelsOptions, createModels, type MutableModels, type Provider } from "../models.ts";
+import type { Api, KnownProvider, Model } from "../types.ts";
 import { amazonBedrockProvider } from "./amazon-bedrock.ts";
 import { antLingProvider } from "./ant-ling.ts";
 import { anthropicProvider } from "./anthropic.ts";
@@ -35,11 +37,32 @@ import { xiaomiTokenPlanSgpProvider } from "./xiaomi-token-plan-sgp.ts";
 import { zaiProvider } from "./zai.ts";
 import { zaiCodingCnProvider } from "./zai-coding-cn.ts";
 
-export {
-	getModel as getBuiltinModel,
-	getModels as getBuiltinModels,
-	getProviders as getBuiltinProviders,
-} from "../models.ts";
+type BuiltinModelApi<
+	TProvider extends KnownProvider,
+	TModelId extends keyof (typeof MODELS)[TProvider],
+> = (typeof MODELS)[TProvider][TModelId] extends { api: infer TApi } ? (TApi extends Api ? TApi : never) : never;
+
+/** Typed read of the generated built-in catalog. */
+export function getBuiltinModel<TProvider extends KnownProvider, TModelId extends keyof (typeof MODELS)[TProvider]>(
+	provider: TProvider,
+	modelId: TModelId,
+): Model<BuiltinModelApi<TProvider, TModelId>> {
+	const models = MODELS[provider] as Record<string, Model<Api>> | undefined;
+	return models?.[modelId as string] as Model<BuiltinModelApi<TProvider, TModelId>>;
+}
+
+export function getBuiltinProviders(): KnownProvider[] {
+	return Object.keys(MODELS) as KnownProvider[];
+}
+
+export function getBuiltinModels<TProvider extends KnownProvider>(
+	provider: TProvider,
+): Model<BuiltinModelApi<TProvider, keyof (typeof MODELS)[TProvider]>>[] {
+	const models = MODELS[provider] as Record<string, Model<Api>> | undefined;
+	return models
+		? (Object.values(models) as Model<BuiltinModelApi<TProvider, keyof (typeof MODELS)[TProvider]>>[])
+		: [];
+}
 
 /** All built-in providers, freshly constructed. */
 export function builtinProviders(): Provider[] {

packages/ai/src/utils/oauth/github-copilot.ts

@@ -3,7 +3,7 @@
  */
 
 import type { OAuthAuth, OAuthCredential } from "../../auth/types.ts";
-import { getModels } from "../../models.ts";
+import { GITHUB_COPILOT_MODELS } from "../../providers/github-copilot.models.ts";
 import type { Api, Model } from "../../types.ts";
 import { pollOAuthDeviceCodeFlow } from "./device-code.ts";
 import type { OAuthCredentials, OAuthDeviceCodeInfo, OAuthLoginCallbacks, OAuthProviderInterface } from "./types.ts";
@@ -274,7 +274,7 @@ async function enableAllGitHubCopilotModels(
 	enterpriseDomain?: string,
 	onProgress?: (model: string, success: boolean) => void,
 ): Promise<void> {
-	const models = getModels("github-copilot");
+	const models = Object.values(GITHUB_COPILOT_MODELS);
 	await Promise.all(
 		models.map(async (model) => {
 			const success = await enableGitHubCopilotModel(token, model.id, enterpriseDomain);