oh-my-pi/packages/coding-agent/src/config/model-registry.ts

/**
 * Model registry - manages built-in and custom models, provides API key resolution.
 */

import * as path from "node:path";

import {
	type Api,
	getGitHubCopilotBaseUrl,
	getModels,
	getProviders,
	type Model,
	normalizeDomain,
} from "@oh-my-pi/pi-ai";

import { isEnoent, logger } from "@oh-my-pi/pi-utils";
import { type Static, Type } from "@sinclair/typebox";
import AjvModule from "ajv";
import { YAML } from "bun";
import type { AuthStorage } from "../session/auth-storage";

const Ajv = (AjvModule as any).default || AjvModule;

// Schema for OpenAI compatibility settings
const OpenAICompatSchema = Type.Object({
	supportsStore: Type.Optional(Type.Boolean()),
	supportsDeveloperRole: Type.Optional(Type.Boolean()),
	supportsReasoningEffort: Type.Optional(Type.Boolean()),
	maxTokensField: Type.Optional(Type.Union([Type.Literal("max_completion_tokens"), Type.Literal("max_tokens")])),
});

// Schema for custom model definition
const ModelDefinitionSchema = Type.Object({
	id: Type.String({ minLength: 1 }),
	name: Type.String({ minLength: 1 }),
	api: Type.Optional(
		Type.Union([
			Type.Literal("openai-completions"),
			Type.Literal("openai-responses"),
			Type.Literal("openai-codex-responses"),
			Type.Literal("anthropic-messages"),
			Type.Literal("google-generative-ai"),
			Type.Literal("google-vertex"),
		]),
	),
	reasoning: Type.Boolean(),
	input: Type.Array(Type.Union([Type.Literal("text"), Type.Literal("image")])),
	cost: Type.Object({
		input: Type.Number(),
		output: Type.Number(),
		cacheRead: Type.Number(),
		cacheWrite: Type.Number(),
	}),
	contextWindow: Type.Number(),
	maxTokens: Type.Number(),
	headers: Type.Optional(Type.Record(Type.String(), Type.String())),
	compat: Type.Optional(OpenAICompatSchema),
});

const ProviderConfigSchema = Type.Object({
	baseUrl: Type.Optional(Type.String({ minLength: 1 })),
	apiKey: Type.Optional(Type.String({ minLength: 1 })),
	api: Type.Optional(
		Type.Union([
			Type.Literal("openai-completions"),
			Type.Literal("openai-responses"),
			Type.Literal("openai-codex-responses"),
			Type.Literal("anthropic-messages"),
			Type.Literal("google-generative-ai"),
			Type.Literal("google-vertex"),
		]),
	),
	headers: Type.Optional(Type.Record(Type.String(), Type.String())),
	authHeader: Type.Optional(Type.Boolean()),
	models: Type.Optional(Type.Array(ModelDefinitionSchema)),
});

const ModelsConfigSchema = Type.Object({
	providers: Type.Record(Type.String(), ProviderConfigSchema),
});

type ModelsConfig = Static<typeof ModelsConfigSchema>;

/** Provider override config (baseUrl, headers, apiKey) without custom models */
interface ProviderOverride {
	baseUrl?: string;
	headers?: Record<string, string>;
	apiKey?: string;
}

/**
 * Serialized representation of ModelRegistry for passing to subagent workers.
 */
export interface SerializedModelRegistry {
	models: Model<Api>[];
	customProviderApiKeys?: Record<string, string>;
	loadError?: string;
}

/** Result of loading custom models from models.json */
interface CustomModelsResult {
	models: Model<Api>[];
	/** Providers with custom models (full replacement) */
	replacedProviders: Set<string>;
	/** Providers with only baseUrl/headers override (no custom models) */
	overrides: Map<string, ProviderOverride>;
	error: string | undefined;
	/** Whether the file was found (true) or didn't exist (false) */
	found: boolean;
}

function emptyCustomModelsResult(error?: string): CustomModelsResult {
	return { models: [], replacedProviders: new Set(), overrides: new Map(), error, found: false };
}

/**
 * Resolve an API key config value to an actual key.
 * Checks environment variable first, then treats as literal.
 */
function resolveApiKeyConfig(keyConfig: string): string | undefined {
	const envValue = process.env[keyConfig];
	if (envValue) return envValue;
	return keyConfig;
}

/**
 * Model registry - loads and manages models, resolves API keys via AuthStorage.
 */
export class ModelRegistry {
	private models: Model<Api>[] = [];
	private customProviderApiKeys: Map<string, string> = new Map();
	private loadError: string | undefined = undefined;

	/**
	 * @param authStorage - Auth storage for API key resolution
	 * @param modelsJsonPath - Primary path for models.json
	 * @param fallbackPaths - Additional paths to check (legacy support)
	 */
	constructor(
		readonly authStorage: AuthStorage,
		private modelsJsonPath: string | undefined = undefined,
		private fallbackPaths: string[] = [],
	) {
		// Set up fallback resolver for custom provider API keys
		this.authStorage.setFallbackResolver((provider) => {
			const keyConfig = this.customProviderApiKeys.get(provider);
			if (keyConfig) {
				return resolveApiKeyConfig(keyConfig);
			}
			return undefined;
		});
	}

	/**
	 * Create an in-memory ModelRegistry instance from serialized data.
	 * Used by subagent workers to bypass discovery and use parent's models.
	 */
	static fromSerialized(data: SerializedModelRegistry, authStorage: AuthStorage): ModelRegistry {
		const instance = Object.create(ModelRegistry.prototype) as ModelRegistry;
		(instance as any).authStorage = authStorage;
		instance.models = data.models;
		instance.customProviderApiKeys = new Map(Object.entries(data.customProviderApiKeys ?? {}));
		instance.loadError = data.loadError;

		authStorage.setFallbackResolver((provider) => {
			const keyConfig = instance.customProviderApiKeys.get(provider);
			if (keyConfig) {
				return resolveApiKeyConfig(keyConfig);
			}
			return undefined;
		});

		return instance;
	}

	/**
	 * Serialize ModelRegistry for passing to subagent workers.
	 */
	serialize(): SerializedModelRegistry {
		const customProviderApiKeys: Record<string, string> = {};
		for (const [k, v] of this.customProviderApiKeys.entries()) {
			customProviderApiKeys[k] = v;
		}
		return {
			models: this.models,
			customProviderApiKeys: Object.keys(customProviderApiKeys).length > 0 ? customProviderApiKeys : undefined,
			loadError: this.loadError,
		};
	}

	/**
	 * Reload models from disk (built-in + custom from models.json).
	 */
	async refresh(): Promise<void> {
		this.customProviderApiKeys.clear();
		this.loadError = undefined;
		await this.loadModels();
	}

	/**
	 * Get any error from loading models.json (undefined if no error).
	 */
	getError(): string | undefined {
		return this.loadError;
	}

	private async loadModels(): Promise<void> {
		// Load custom models from models.json first (to know which providers to skip/override)
		let customModels: Model<Api>[] = [];
		let replacedProviders: Set<string> = new Set();
		let overrides: Map<string, ProviderOverride> = new Map();
		const pathsToCheck = this.modelsJsonPath ? [this.modelsJsonPath, ...this.fallbackPaths] : this.fallbackPaths;

		if (pathsToCheck.length > 0) {
			logger.debug("ModelRegistry.loadModels checking paths", { paths: pathsToCheck });
		}

		for (const modelsPath of pathsToCheck) {
			const result = await this.loadCustomModels(modelsPath);
			if (!result.found) {
				continue; // File doesn't exist, try next path
			}
			logger.debug("ModelRegistry.loadModels loading", { path: modelsPath });
			if (result.error) {
				this.loadError = result.error;
				// Keep built-in models even if custom models failed to load
			} else {
				customModels = result.models;
				replacedProviders = result.replacedProviders;
				overrides = result.overrides;
			}
			break; // Use first existing file
		}

		const builtInModels = this.loadBuiltInModels(replacedProviders, overrides);
		const combined = [...builtInModels, ...customModels];

		// Update github-copilot base URL based on OAuth credentials
		const copilotCred = this.authStorage.getOAuthCredential("github-copilot");
		if (copilotCred) {
			const domain = copilotCred.enterpriseUrl
				? (normalizeDomain(copilotCred.enterpriseUrl) ?? undefined)
				: undefined;
			const baseUrl = getGitHubCopilotBaseUrl(copilotCred.access, domain);
			this.models = combined.map((m) => (m.provider === "github-copilot" ? { ...m, baseUrl } : m));
		} else {
			this.models = combined;
		}
	}

	/** Load built-in models, skipping replaced providers and applying overrides */
	private loadBuiltInModels(replacedProviders: Set<string>, overrides: Map<string, ProviderOverride>): Model<Api>[] {
		return getProviders()
			.filter((provider) => !replacedProviders.has(provider))
			.flatMap((provider) => {
				const models = getModels(provider as any) as Model<Api>[];
				const override = overrides.get(provider);
				if (!override) return models;

				// Apply baseUrl/headers override to all models of this provider
				return models.map((m) => ({
					...m,
					baseUrl: override.baseUrl ?? m.baseUrl,
					headers: override.headers ? { ...m.headers, ...override.headers } : m.headers,
				}));
			});
	}

	private async loadCustomModels(modelsPath: string): Promise<CustomModelsResult> {
		let content: string;
		try {
			content = await Bun.file(modelsPath).text();
		} catch (error) {
			if (isEnoent(error)) {
				return emptyCustomModelsResult();
			}
			return {
				...emptyCustomModelsResult(
					`Failed to load models config: ${error instanceof Error ? error.message : error}\n\nFile: ${modelsPath}`,
				),
				found: true,
			};
		}

		try {
			const ext = path.extname(modelsPath).toLowerCase();
			let config: ModelsConfig;

			if (ext === ".yaml" || ext === ".yml") {
				config = YAML.parse(content) as ModelsConfig;
			} else {
				config = JSON.parse(content) as ModelsConfig;
			}

			// Validate schema
			const ajv = new Ajv();
			const validate = ajv.compile(ModelsConfigSchema);
			if (!validate(config)) {
				const errors =
					validate.errors?.map((e: any) => `  - ${e.instancePath || "root"}: ${e.message}`).join("\n") ||
					"Unknown schema error";
				return emptyCustomModelsResult(`Invalid models config schema:\n${errors}\n\nFile: ${modelsPath}`);
			}

			// Additional validation
			this.validateConfig(config);

			// Separate providers into "full replacement" (has models) vs "override-only" (no models)
			const replacedProviders = new Set<string>();
			const overrides = new Map<string, ProviderOverride>();

			for (const [providerName, providerConfig] of Object.entries(config.providers)) {
				if (providerConfig.models && providerConfig.models.length > 0) {
					// Has custom models -> full replacement
					replacedProviders.add(providerName);
				} else {
					// No models -> just override baseUrl/headers on built-in
					overrides.set(providerName, {
						baseUrl: providerConfig.baseUrl,
						headers: providerConfig.headers,
						apiKey: providerConfig.apiKey,
					});
					// Store API key for fallback resolver
					if (providerConfig.apiKey) {
						this.customProviderApiKeys.set(providerName, providerConfig.apiKey);
					}
				}
			}

			return { models: this.parseModels(config), replacedProviders, overrides, error: undefined, found: true };
		} catch (error) {
			if (error instanceof SyntaxError) {
				return {
					...emptyCustomModelsResult(`Failed to parse models config: ${error.message}\n\nFile: ${modelsPath}`),
					found: true,
				};
			}
			return {
				...emptyCustomModelsResult(
					`Failed to load models config: ${error instanceof Error ? error.message : error}\n\nFile: ${modelsPath}`,
				),
				found: true,
			};
		}
	}

	private validateConfig(config: ModelsConfig): void {
		for (const [providerName, providerConfig] of Object.entries(config.providers)) {
			const hasProviderApi = !!providerConfig.api;
			const models = providerConfig.models ?? [];

			if (models.length === 0) {
				// Override-only config: just needs baseUrl (to override built-in)
				if (!providerConfig.baseUrl) {
					throw new Error(
						`Provider ${providerName}: must specify either "baseUrl" (for override) or "models" (for replacement).`,
					);
				}
			} else {
				// Full replacement: needs baseUrl and apiKey
				if (!providerConfig.baseUrl) {
					throw new Error(`Provider ${providerName}: "baseUrl" is required when defining custom models.`);
				}
				if (!providerConfig.apiKey) {
					throw new Error(`Provider ${providerName}: "apiKey" is required when defining custom models.`);
				}
			}

			for (const modelDef of models) {
				const hasModelApi = !!modelDef.api;

				if (!hasProviderApi && !hasModelApi) {
					throw new Error(
						`Provider ${providerName}, model ${modelDef.id}: no "api" specified. Set at provider or model level.`,
					);
				}

				if (!modelDef.id) throw new Error(`Provider ${providerName}: model missing "id"`);
				if (!modelDef.name) throw new Error(`Provider ${providerName}: model missing "name"`);
				if (modelDef.contextWindow <= 0)
					throw new Error(`Provider ${providerName}, model ${modelDef.id}: invalid contextWindow`);
				if (modelDef.maxTokens <= 0)
					throw new Error(`Provider ${providerName}, model ${modelDef.id}: invalid maxTokens`);
			}
		}
	}

	private parseModels(config: ModelsConfig): Model<Api>[] {
		const models: Model<Api>[] = [];

		for (const [providerName, providerConfig] of Object.entries(config.providers)) {
			const modelDefs = providerConfig.models ?? [];
			if (modelDefs.length === 0) continue; // Override-only, no custom models

			// Store API key config for fallback resolver
			if (providerConfig.apiKey) {
				this.customProviderApiKeys.set(providerName, providerConfig.apiKey);
			}

			for (const modelDef of modelDefs) {
				const api = modelDef.api || providerConfig.api;
				if (!api) continue;

				// Merge headers: provider headers are base, model headers override
				let headers =
					providerConfig.headers || modelDef.headers
						? { ...providerConfig.headers, ...modelDef.headers }
						: undefined;

				// If authHeader is true, add Authorization header with resolved API key
				if (providerConfig.authHeader && providerConfig.apiKey) {
					const resolvedKey = resolveApiKeyConfig(providerConfig.apiKey);
					if (resolvedKey) {
						headers = { ...headers, Authorization: `Bearer ${resolvedKey}` };
					}
				}

				// baseUrl is validated to exist for providers with models
				models.push({
					id: modelDef.id,
					name: modelDef.name,
					api: api as Api,
					provider: providerName,
					baseUrl: providerConfig.baseUrl!,
					reasoning: modelDef.reasoning,
					input: modelDef.input as ("text" | "image")[],
					cost: modelDef.cost,
					contextWindow: modelDef.contextWindow,
					maxTokens: modelDef.maxTokens,
					headers,
					compat: modelDef.compat,
				} as Model<Api>);
			}
		}

		return models;
	}

	/**
	 * Get all models (built-in + custom).
	 * If models.json had errors, returns only built-in models.
	 */
	getAll(): Model<Api>[] {
		return this.models;
	}

	/**
	 * Get only models that have auth configured.
	 * This is a fast check that doesn't refresh OAuth tokens.
	 */
	getAvailable(): Model<Api>[] {
		return this.models.filter((m) => this.authStorage.hasAuth(m.provider));
	}

	/**
	 * Find a model by provider and ID.
	 */
	find(provider: string, modelId: string): Model<Api> | undefined {
		return this.models.find((m) => m.provider === provider && m.id === modelId);
	}

	/**
	 * Get the base URL associated with a provider, if any model defines one.
	 */
	getProviderBaseUrl(provider: string): string | undefined {
		return this.models.find((m) => m.provider === provider && m.baseUrl)?.baseUrl;
	}

	/**
	 * Get API key for a model.
	 */
	async getApiKey(model: Model<Api>, sessionId?: string): Promise<string | undefined> {
		return this.authStorage.getApiKey(model.provider, sessionId, { baseUrl: model.baseUrl });
	}

	/**
	 * Get API key for a provider (e.g., "openai").
	 */
	async getApiKeyForProvider(provider: string, sessionId?: string, baseUrl?: string): Promise<string | undefined> {
		return this.authStorage.getApiKey(provider, sessionId, { baseUrl });
	}

	/**
	 * Check if a model is using OAuth credentials (subscription).
	 */
	isUsingOAuth(model: Model<Api>): boolean {
		return this.authStorage.hasOAuth(model.provider);
	}
}