@schlenkr/ragents 0.1.0

package/packages/agent/src/core/model-runtime.ts

@@ -0,0 +1,517 @@
+import { dirname, join } from "node:path";
+import {
+	type Api,
+	type ApiStreamOptions,
+	type AssistantMessage,
+	type AssistantMessageEventStream,
+	type AuthCheck,
+	type AuthInteraction,
+	type AuthResult,
+	type AuthType,
+	type Context,
+	type Credential,
+	type CredentialInfo,
+	type CredentialStore,
+	createModels,
+	lazyStream,
+	type Model,
+	type Models,
+	type ModelsApiStreamOptions,
+	ModelsError,
+	type ModelsRefreshOptions,
+	type ModelsRefreshResult,
+	type ModelsSimpleStreamOptions,
+	type ModelsStore,
+	type ModelsStreamTransforms,
+	type MutableModels,
+	type Provider,
+	type ProviderHeaders,
+	type SimpleStreamOptions,
+	type StreamOptions,
+} from "@aicontainer/ai";
+import * as builtinProviderCatalog from "@aicontainer/ai/providers/all";
+import { getAgentDir } from "../config.ts";
+import { AuthStorage as DefaultAuthStorage } from "./auth-storage.ts";
+import { ModelConfig } from "./model-config.ts";
+import {
+	type AuthStatus,
+	type CompatibilityRequestConfig,
+	composeModelProvider,
+	configuredRequestAuthStatus,
+	type ProviderConfigInput,
+	resolveCompatibilityRequestConfig,
+	resolveConfiguredModelHeaders,
+	validateExtensionProvider,
+} from "./provider-composer.ts";
+import { RuntimeCredentials } from "./runtime-credentials.ts";
+
+interface ModelRuntimeSnapshot {
+	all: readonly Model<Api>[];
+	available: readonly Model<Api>[];
+	configuredProviders: ReadonlySet<string>;
+	storedProviders: ReadonlySet<string>;
+	auth: ReadonlyMap<string, AuthCheck | undefined>;
+}
+
+export interface CreateModelRuntimeOptions {
+	/** Credential storage. Defaults to the file at authPath. */
+	credentials?: CredentialStore;
+	authPath?: string;
+	modelsPath?: string | null;
+	modelRefreshTimeoutMs?: number;
+}
+
+export interface ModelRuntimeAuthOverrides {
+	apiKey?: string;
+	env?: Record<string, string>;
+}
+
+function mergeHeaders(
+	base: ProviderHeaders | undefined,
+	override: ProviderHeaders | undefined,
+): ProviderHeaders | undefined {
+	if (!base && !override) return undefined;
+	const merged = { ...base };
+	for (const [name, value] of Object.entries(override ?? {})) {
+		const lowerName = name.toLowerCase();
+		for (const existingName of Object.keys(merged)) {
+			if (existingName.toLowerCase() === lowerName) delete merged[existingName];
+		}
+		merged[name] = value;
+	}
+	return merged;
+}
+
+/** Configured Models collection used by coding-agent and SDK consumers. */
+export class ModelRuntime implements Models {
+	private readonly models: MutableModels;
+	private readonly credentials: RuntimeCredentials;
+	private readonly defaultBuiltins: ReadonlyMap<string, Provider>;
+	private readonly builtins = new Map<string, Provider>();
+	private readonly extensionProviders = new Map<string, ProviderConfigInput>();
+	private readonly compositionErrors = new Map<string, string>();
+	private readonly modelsPath: string | undefined;
+	private config: ModelConfig;
+	private snapshot: ModelRuntimeSnapshot = {
+		all: [],
+		available: [],
+		configuredProviders: new Set(),
+		storedProviders: new Set(),
+		auth: new Map(),
+	};
+	private availabilityRefresh: Promise<void> | undefined;
+	private availabilityError: string | undefined;
+
+	private constructor(
+		credentials: RuntimeCredentials,
+		config: ModelConfig,
+		modelsPath: string | undefined,
+		providers: readonly Provider[],
+	) {
+		this.credentials = credentials;
+		this.config = config;
+		this.modelsPath = modelsPath;
+		this.defaultBuiltins = new Map(providers.map((provider) => [provider.id, provider]));
+		for (const [providerId, provider] of this.defaultBuiltins) this.builtins.set(providerId, provider);
+		this.models = createModels({ credentials });
+		this.rebuildProviders();
+	}
+
+	static async create(options: CreateModelRuntimeOptions = {}): Promise<ModelRuntime> {
+		const credentials = new RuntimeCredentials(options.credentials ?? DefaultAuthStorage.create(options.authPath));
+		const modelsPath =
+			options.modelsPath === null ? undefined : (options.modelsPath ?? join(getAgentDir(), "models.json"));
+		const config = await ModelConfig.load(modelsPath);
+		const runtime = new ModelRuntime(credentials, config, modelsPath, builtinProviderCatalog.builtinProviders());
+		runtime.resetBuiltins();
+		runtime.rebuildProviders();
+		await runtime.refresh();
+		return runtime;
+	}
+
+	private resetBuiltins(): void {
+		this.builtins.clear();
+		for (const [providerId, provider] of this.defaultBuiltins) this.builtins.set(providerId, provider);
+	}
+
+	private providerIds(): Set<string> {
+		return new Set([...this.builtins.keys(), ...this.config.getProviderIds(), ...this.extensionProviders.keys()]);
+	}
+
+	private recomposeProvider(providerId: string): void {
+		const base = this.builtins.get(providerId);
+		const extension = this.extensionProviders.get(providerId);
+		if (!base && !this.config.getProvider(providerId) && !extension) {
+			this.models.deleteProvider(providerId);
+			this.compositionErrors.delete(providerId);
+			return;
+		}
+		if (base && !this.config.getProvider(providerId) && !extension) {
+			// No overlays: use the builtin untouched so its auth/login/stream behavior is exact.
+			this.models.setProvider(base);
+			this.compositionErrors.delete(providerId);
+			return;
+		}
+		try {
+			this.models.setProvider(composeModelProvider(providerId, base, this.config, extension));
+			this.compositionErrors.delete(providerId);
+		} catch (error) {
+			this.compositionErrors.set(providerId, error instanceof Error ? error.message : String(error));
+			if (base) this.models.setProvider(base);
+			else this.models.deleteProvider(providerId);
+		}
+	}
+
+	private rebuildProviders(): void {
+		this.models.clearProviders();
+		this.compositionErrors.clear();
+		for (const providerId of this.providerIds()) this.recomposeProvider(providerId);
+		this.updateModelSnapshot();
+	}
+
+	private updateModelSnapshot(): void {
+		const all = [...this.models.getModels()];
+		this.snapshot = {
+			...this.snapshot,
+			all,
+			available: all.filter((model) => this.snapshot.configuredProviders.has(model.provider)),
+		};
+	}
+
+	private async runAvailabilityRefresh(): Promise<void> {
+		const providers = this.models.getProviders();
+		const [available, checks, credentials] = await Promise.all([
+			this.models.getAvailable(),
+			Promise.all(
+				providers.map(
+					async (provider): Promise<[string, AuthCheck | undefined]> => [
+						provider.id,
+						await this.models.checkAuth(provider.id),
+					],
+				),
+			),
+			this.credentials.list(),
+		]);
+		const auth = new Map(checks);
+		const configuredProviders = new Set(
+			checks
+				.filter((entry): entry is [string, AuthCheck] => entry[1] !== undefined)
+				.map(([providerId]) => providerId),
+		);
+		this.snapshot = {
+			all: [...this.models.getModels()],
+			available: [...available],
+			configuredProviders,
+			storedProviders: new Set(credentials.map((entry) => entry.providerId)),
+			auth,
+		};
+		this.availabilityError = undefined;
+	}
+
+	private queueAvailabilityRefresh(after: Promise<void> | undefined): Promise<void> {
+		const refresh = (after ?? Promise.resolve()).catch(() => {}).then(() => this.runAvailabilityRefresh());
+		const recorded = refresh.catch((error) => {
+			this.availabilityError = error instanceof Error ? error.message : String(error);
+			throw error;
+		});
+		const tracked = recorded.finally(() => {
+			if (this.availabilityRefresh === tracked) this.availabilityRefresh = undefined;
+		});
+		this.availabilityRefresh = tracked;
+		return tracked;
+	}
+
+	/** Coalesce concurrent readers onto the pending refresh. */
+	private refreshAvailability(): Promise<void> {
+		return this.availabilityRefresh ?? this.queueAvailabilityRefresh(undefined);
+	}
+
+	/** Mutations must not observe an in-flight refresh started before them. */
+	private forceRefreshAvailability(): Promise<void> {
+		return this.queueAvailabilityRefresh(this.availabilityRefresh);
+	}
+
+	getProviders(): readonly Provider[] {
+		return this.models.getProviders();
+	}
+
+	getProvider(providerId: string): Provider | undefined {
+		return this.models.getProvider(providerId);
+	}
+
+	getModels(providerId?: string): readonly Model<Api>[] {
+		return this.models.getModels(providerId);
+	}
+
+	getModel(providerId: string, modelId: string): Model<Api> | undefined {
+		return this.models.getModel(providerId, modelId);
+	}
+
+	async checkAuth(providerId: string): Promise<AuthCheck | undefined> {
+		return this.models.checkAuth(providerId);
+	}
+
+	async getAvailable(providerId?: string): Promise<readonly Model<Api>[]> {
+		if (providerId) {
+			if (this.availabilityRefresh) {
+				await this.availabilityRefresh;
+				return this.snapshot.available.filter((model) => model.provider === providerId);
+			}
+			try {
+				return await this.models.getAvailable(providerId);
+			} catch (error) {
+				this.availabilityError = error instanceof Error ? error.message : String(error);
+				throw error;
+			}
+		}
+		await this.refreshAvailability();
+		return this.snapshot.available;
+	}
+
+	getAvailableSnapshot(): readonly Model<Api>[] {
+		return this.snapshot.available;
+	}
+
+	getError(): string | undefined {
+		const errors: string[] = [];
+		const configError = this.config.getError();
+		if (configError) errors.push(configError);
+		for (const [providerId, error] of this.compositionErrors) {
+			errors.push(`Provider "${providerId}": ${error}`);
+		}
+		if (this.availabilityError) errors.push(`Availability refresh: ${this.availabilityError}`);
+		return errors.length > 0 ? errors.join("\n\n") : undefined;
+	}
+
+	getRegisteredProviderConfig(providerId: string): ProviderConfigInput | undefined {
+		return this.extensionProviders.get(providerId);
+	}
+
+	getRegisteredProviderIds(): readonly string[] {
+		return [...this.extensionProviders.keys()];
+	}
+
+	/** @internal Compatibility fallback for ModelRegistry when provider auth is unconfigured. */
+	getCompatibilityRequestConfig(model: Model<Api>): CompatibilityRequestConfig {
+		return resolveCompatibilityRequestConfig(
+			model,
+			this.config.getProvider(model.provider),
+			this.extensionProviders.get(model.provider),
+		);
+	}
+
+	isUsingOAuth(providerId: string): boolean {
+		return this.snapshot.auth.get(providerId)?.type === "oauth";
+	}
+
+	hasConfiguredAuth(providerId: string): boolean {
+		return this.snapshot.configuredProviders.has(providerId);
+	}
+
+	getAuth(providerId: string, overrides?: ModelRuntimeAuthOverrides): Promise<AuthResult | undefined>;
+	getAuth(model: Model<Api>, overrides?: ModelRuntimeAuthOverrides): Promise<AuthResult | undefined>;
+	async getAuth(
+		providerOrModel: string | Model<Api>,
+		overrides: ModelRuntimeAuthOverrides = {},
+	): Promise<AuthResult | undefined> {
+		if (typeof providerOrModel === "string") return this.models.getAuth(providerOrModel, overrides);
+		const resolution = await this.models.getAuth(providerOrModel, overrides);
+		if (!resolution) return undefined;
+		const configuredHeaders = resolveConfiguredModelHeaders(
+			providerOrModel,
+			this.config.getProvider(providerOrModel.provider),
+			this.extensionProviders.get(providerOrModel.provider),
+			{ ...(resolution.env ?? {}), ...(overrides.env ?? {}) },
+		);
+		return {
+			...resolution,
+			auth: {
+				...resolution.auth,
+				headers: mergeHeaders(resolution.auth.headers, configuredHeaders),
+			},
+		};
+	}
+
+	async setRuntimeApiKey(providerId: string, apiKey: string): Promise<void> {
+		this.credentials.setRuntimeApiKey(providerId, apiKey);
+		const auth = new Map(this.snapshot.auth).set(providerId, { type: "api_key", source: "runtime API key" });
+		const configuredProviders = new Set(this.snapshot.configuredProviders).add(providerId);
+		const storedProviders = new Set(this.snapshot.storedProviders).add(providerId);
+		this.snapshot = {
+			...this.snapshot,
+			auth,
+			configuredProviders,
+			storedProviders,
+			available: this.snapshot.all.filter((model) => configuredProviders.has(model.provider)),
+		};
+		await this.refresh();
+	}
+
+	async removeRuntimeApiKey(providerId: string): Promise<void> {
+		this.credentials.removeRuntimeApiKey(providerId);
+		await this.refresh();
+	}
+
+	listCredentials(): Promise<readonly CredentialInfo[]> {
+		return this.credentials.list();
+	}
+
+	getProviderAuthStatus(providerId: string): AuthStatus {
+		if (this.credentials.hasRuntimeApiKey(providerId)) return { configured: true, source: "runtime" };
+		if (this.snapshot.storedProviders.has(providerId)) return { configured: true, source: "stored" };
+		const configured = configuredRequestAuthStatus(
+			this.config.getProvider(providerId),
+			this.extensionProviders.get(providerId),
+		);
+		if (configured) return configured;
+		const check = this.snapshot.auth.get(providerId);
+		return check ? { configured: true, source: "environment", label: check.source } : { configured: false };
+	}
+
+	private async prepareRequest(
+		model: Model<Api>,
+		options: (StreamOptions & ModelsStreamTransforms) | undefined,
+	): Promise<{ provider: Provider; model: Model<Api>; options: StreamOptions }> {
+		const provider = this.models.getProvider(model.provider);
+		if (!provider) throw new ModelsError("provider", `Unknown provider: ${model.provider}`);
+		const resolution = await this.getAuth(model, { apiKey: options?.apiKey, env: options?.env });
+		if (!resolution) throw new ModelsError("auth", `Provider is not configured: ${model.provider}`);
+
+		const { transformHeaders, ...providerOptions } = options ?? {};
+		let headers = mergeHeaders(resolution.auth.headers, providerOptions.headers);
+		if (transformHeaders) headers = await transformHeaders(headers ?? {});
+		const env =
+			resolution.env || providerOptions.env
+				? { ...(resolution.env ?? {}), ...(providerOptions.env ?? {}) }
+				: undefined;
+		return {
+			provider,
+			model: resolution.auth.baseUrl ? { ...model, baseUrl: resolution.auth.baseUrl } : model,
+			options: {
+				...providerOptions,
+				apiKey: providerOptions.apiKey ?? resolution.auth.apiKey,
+				headers,
+				env,
+			},
+		};
+	}
+
+	stream<TApi extends Api>(
+		model: Model<TApi>,
+		context: Context,
+		options?: ModelsApiStreamOptions<TApi>,
+	): AssistantMessageEventStream {
+		return lazyStream(model, async () => {
+			const prepared = await this.prepareRequest(
+				model,
+				options as (StreamOptions & ModelsStreamTransforms) | undefined,
+			);
+			return prepared.provider.stream(
+				prepared.model as Model<TApi>,
+				context,
+				prepared.options as ApiStreamOptions<TApi>,
+			);
+		});
+	}
+
+	complete<TApi extends Api>(
+		model: Model<TApi>,
+		context: Context,
+		options?: ModelsApiStreamOptions<TApi>,
+	): Promise<AssistantMessage> {
+		return this.stream(model, context, options).result();
+	}
+
+	streamSimple(model: Model<Api>, context: Context, options?: ModelsSimpleStreamOptions): AssistantMessageEventStream {
+		return lazyStream(model, async () => {
+			const prepared = await this.prepareRequest(model, options);
+			return prepared.provider.streamSimple(prepared.model, context, prepared.options as SimpleStreamOptions);
+		});
+	}
+
+	completeSimple(model: Model<Api>, context: Context, options?: ModelsSimpleStreamOptions): Promise<AssistantMessage> {
+		return this.streamSimple(model, context, options).result();
+	}
+
+	async login(providerId: string, type: AuthType, interaction: AuthInteraction): Promise<Credential> {
+		const credential = await this.models.login(providerId, type, interaction);
+		await this.refresh();
+		return credential;
+	}
+
+	async logout(providerId: string): Promise<void> {
+		await this.models.logout(providerId);
+		// Reset credential-dependent compatibility projections before the unconfigured provider is skipped by refresh.
+		this.recomposeProvider(providerId);
+		await this.refresh();
+	}
+
+	async reloadConfig(): Promise<void> {
+		this.config = await ModelConfig.load(this.modelsPath);
+		this.resetBuiltins();
+		this.rebuildProviders();
+		await this.refresh();
+	}
+
+	async refresh(options: ModelsRefreshOptions = {}): Promise<ModelsRefreshResult> {
+		const refreshOptions = {
+			...options,
+			allowNetwork: options.allowNetwork ?? false,
+		};
+		const result = ((await this.models.refresh(refreshOptions)) as ModelsRefreshResult | undefined) ?? {
+			aborted: refreshOptions.signal?.aborted ?? false,
+			errors: new Map(),
+		};
+		this.updateModelSnapshot();
+		try {
+			await this.forceRefreshAvailability();
+		} catch {
+			// Availability errors are recorded by forceRefreshAvailability; refreshed models remain usable.
+		}
+		return result;
+	}
+
+	registerProvider(providerId: string, config: ProviderConfigInput): void {
+		// Validate the incoming registration on its own, like the legacy registry:
+		// a broken re-registration must throw without touching the stored config.
+		validateExtensionProvider(providerId, this.builtins.get(providerId), this.config.getProvider(providerId), config);
+		// Re-registration merges defined values over the previous registration and
+		// preserves undefined ones, matching the legacy ModelRegistry contract.
+		const previous = this.extensionProviders.get(providerId);
+		const effective: ProviderConfigInput = { ...previous };
+		for (const [key, value] of Object.entries(config)) {
+			if (value !== undefined) (effective as Record<string, unknown>)[key] = value;
+		}
+		this.extensionProviders.set(providerId, effective);
+		this.recomposeProvider(providerId);
+		this.updateModelSnapshot();
+		if (
+			this.snapshot.storedProviders.has(providerId) ||
+			configuredRequestAuthStatus(this.config.getProvider(providerId), effective)?.configured
+		) {
+			const configuredProviders = new Set(this.snapshot.configuredProviders).add(providerId);
+			const auth = new Map(this.snapshot.auth);
+			// Provisional entry until the async refresh lands; never clobber a real check result.
+			if (!auth.get(providerId)) {
+				auth.set(providerId, {
+					type: effective.oauth && !effective.apiKey ? "oauth" : "api_key",
+					source: "configured provider",
+				});
+			}
+			this.snapshot = {
+				...this.snapshot,
+				auth,
+				configuredProviders,
+				available: this.snapshot.all.filter((model) => configuredProviders.has(model.provider)),
+			};
+		}
+		void this.refresh();
+	}
+
+	unregisterProvider(providerId: string): void {
+		this.extensionProviders.delete(providerId);
+		this.recomposeProvider(providerId);
+		this.updateModelSnapshot();
+		void this.refresh();
+	}
+}

package/packages/agent/src/core/output-guard.ts

@@ -0,0 +1,108 @@
+interface StdoutTakeoverState {
+	rawStdoutWrite: (chunk: string, callback?: (error?: Error | null) => void) => boolean;
+	rawStderrWrite: (chunk: string, callback?: (error?: Error | null) => void) => boolean;
+	originalStdoutWrite: typeof process.stdout.write;
+}
+
+let stdoutTakeoverState: StdoutTakeoverState | undefined;
+
+const RAW_STDOUT_RETRY_DELAY_MS = 10;
+
+let rawStdoutWriteTail: Promise<void> = Promise.resolve();
+
+function getRawStdoutWrite(): StdoutTakeoverState["rawStdoutWrite"] {
+	if (stdoutTakeoverState) {
+		return stdoutTakeoverState.rawStdoutWrite;
+	}
+	return process.stdout.write.bind(process.stdout) as StdoutTakeoverState["rawStdoutWrite"];
+}
+
+async function writeRawStdoutChunk(text: string): Promise<void> {
+	while (true) {
+		try {
+			await new Promise<void>((resolve, reject) => {
+				try {
+					getRawStdoutWrite()(text, (error) => {
+						if (error) reject(error);
+						else resolve();
+					});
+				} catch (error) {
+					reject(error instanceof Error ? error : new Error(String(error)));
+				}
+			});
+			return;
+		} catch (error) {
+			const writeError = error instanceof Error ? error : new Error(String(error));
+			const code = (writeError as Error & { code?: unknown }).code;
+			if (code !== "ENOBUFS" && code !== "EAGAIN" && code !== "EWOULDBLOCK") {
+				throw writeError;
+			}
+			await new Promise<void>((resolve) => setTimeout(resolve, RAW_STDOUT_RETRY_DELAY_MS));
+		}
+	}
+}
+
+export function takeOverStdout(): void {
+	if (stdoutTakeoverState) {
+		return;
+	}
+
+	const rawStdoutWrite = process.stdout.write.bind(process.stdout) as StdoutTakeoverState["rawStdoutWrite"];
+	const rawStderrWrite = process.stderr.write.bind(process.stderr) as StdoutTakeoverState["rawStderrWrite"];
+	const originalStdoutWrite = process.stdout.write;
+
+	process.stdout.write = ((
+		chunk: string | Uint8Array,
+		encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+		callback?: (error?: Error | null) => void,
+	): boolean => {
+		if (typeof encodingOrCallback === "function") {
+			return rawStderrWrite(String(chunk), encodingOrCallback);
+		}
+		return rawStderrWrite(String(chunk), callback);
+	}) as typeof process.stdout.write;
+
+	stdoutTakeoverState = {
+		rawStdoutWrite,
+		rawStderrWrite,
+		originalStdoutWrite,
+	};
+}
+
+export function restoreStdout(): void {
+	if (!stdoutTakeoverState) {
+		return;
+	}
+
+	process.stdout.write = stdoutTakeoverState.originalStdoutWrite;
+	stdoutTakeoverState = undefined;
+}
+
+export function isStdoutTakenOver(): boolean {
+	return stdoutTakeoverState !== undefined;
+}
+
+export function writeRawStdout(text: string): void {
+	if (text.length === 0) {
+		return;
+	}
+	rawStdoutWriteTail = rawStdoutWriteTail.then(() => writeRawStdoutChunk(text));
+	void rawStdoutWriteTail.catch(() => {
+		process.exit(1);
+	});
+}
+
+export async function waitForRawStdoutBackpressure(): Promise<void> {
+	while (true) {
+		const tail = rawStdoutWriteTail;
+		await tail;
+		if (tail === rawStdoutWriteTail) {
+			return;
+		}
+	}
+}
+
+export async function flushRawStdout(): Promise<void> {
+	await waitForRawStdoutBackpressure();
+	await writeRawStdoutChunk("");
+}