@schlenkr/ragents 0.1.0

package/packages/ai/src/api/transform-messages.ts

@@ -0,0 +1,185 @@
+import type {
+	Api,
+	AssistantMessage,
+	Message,
+	Model,
+	ToolCall,
+	ToolResultMessage,
+} from "../types.ts";
+
+function validateInputModalities<TApi extends Api>(messages: Message[], model: Model<TApi>): void {
+	for (const message of messages) {
+		if ((message.role !== "user" && message.role !== "toolResult") || !Array.isArray(message.content)) continue;
+		for (const block of message.content) {
+			if (block.type !== "text" && !model.input.includes(block.type)) {
+				throw new Error(`Model ${model.id} does not support ${block.type} input. Supported inputs: ${model.input.join(", ")}.`);
+			}
+		}
+	}
+}
+
+/**
+ * Normalize tool call ID for cross-provider compatibility.
+ * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.
+ * Anthropic APIs require IDs matching ^[a-zA-Z0-9_-]+$ (max 64 chars).
+ */
+export function transformMessages<TApi extends Api>(
+	messages: Message[],
+	model: Model<TApi>,
+	normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string,
+): Message[] {
+	// Build a map of original tool call IDs to normalized IDs
+	const toolCallIdMap = new Map<string, string>();
+	// Normalize null/undefined content from untyped callers (custom tools, hand-built
+	// histories, old session files) so downstream code can rely on the type contract.
+	const normalizedMessages = messages.map((msg) => (msg.content == null ? { ...msg, content: [] } : msg));
+	validateInputModalities(normalizedMessages, model);
+
+	// First pass: transform thinking blocks and tool call IDs.
+	const transformed = normalizedMessages.map((msg) => {
+		// User messages pass through unchanged
+		if (msg.role === "user") {
+			return msg;
+		}
+
+		// Handle toolResult messages - normalize toolCallId if we have a mapping
+		if (msg.role === "toolResult") {
+			const normalizedId = toolCallIdMap.get(msg.toolCallId);
+			if (normalizedId && normalizedId !== msg.toolCallId) {
+				return { ...msg, toolCallId: normalizedId };
+			}
+			return msg;
+		}
+
+		// Assistant messages need transformation check
+		if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			const isSameModel =
+				assistantMsg.provider === model.provider &&
+				assistantMsg.api === model.api &&
+				assistantMsg.model === model.id;
+
+			const transformedContent = assistantMsg.content.flatMap((block) => {
+				if (block.type === "thinking") {
+					// Redacted thinking is opaque encrypted content, only valid for the same model.
+					// Drop it for cross-model to avoid API errors.
+					if (block.redacted) {
+						return isSameModel ? block : [];
+					}
+					// For same model: keep thinking blocks with signatures (needed for replay)
+					// even if the thinking text is empty (OpenAI encrypted reasoning)
+					if (isSameModel && block.thinkingSignature) return block;
+					// Skip empty thinking blocks, convert others to plain text
+					if (!block.thinking || block.thinking.trim() === "") return [];
+					if (isSameModel) return block;
+					return {
+						type: "text" as const,
+						text: block.thinking,
+					};
+				}
+
+				if (block.type === "text") {
+					if (isSameModel) return block;
+					return {
+						type: "text" as const,
+						text: block.text,
+					};
+				}
+
+				if (block.type === "toolCall") {
+					const toolCall = block as ToolCall;
+					let normalizedToolCall: ToolCall = toolCall;
+
+					if (!isSameModel && toolCall.thoughtSignature) {
+						normalizedToolCall = { ...toolCall };
+						delete (normalizedToolCall as { thoughtSignature?: string }).thoughtSignature;
+					}
+
+					if (!isSameModel && normalizeToolCallId) {
+						const normalizedId = normalizeToolCallId(toolCall.id, model, assistantMsg);
+						if (normalizedId !== toolCall.id) {
+							toolCallIdMap.set(toolCall.id, normalizedId);
+							normalizedToolCall = { ...normalizedToolCall, id: normalizedId };
+						}
+					}
+
+					return normalizedToolCall;
+				}
+
+				return block;
+			});
+
+			return {
+				...assistantMsg,
+				content: transformedContent,
+			};
+		}
+		return msg;
+	});
+
+	// Second pass: insert synthetic empty tool results for orphaned tool calls
+	// This preserves thinking signatures and satisfies API requirements
+	const result: Message[] = [];
+	let pendingToolCalls: ToolCall[] = [];
+	let existingToolResultIds = new Set<string>();
+	const insertSyntheticToolResults = () => {
+		if (pendingToolCalls.length > 0) {
+			for (const tc of pendingToolCalls) {
+				if (!existingToolResultIds.has(tc.id)) {
+					result.push({
+						role: "toolResult",
+						toolCallId: tc.id,
+						toolName: tc.name,
+						content: [{ type: "text", text: "No result provided" }],
+						isError: true,
+						timestamp: Date.now(),
+					} as ToolResultMessage);
+				}
+			}
+			pendingToolCalls = [];
+			existingToolResultIds = new Set();
+		}
+	};
+
+	for (let i = 0; i < transformed.length; i++) {
+		const msg = transformed[i];
+
+		if (msg.role === "assistant") {
+			// If we have pending orphaned tool calls from a previous assistant, insert synthetic results now
+			insertSyntheticToolResults();
+
+			// Skip errored/aborted assistant messages entirely.
+			// These are incomplete turns that shouldn't be replayed:
+			// - May have partial content (reasoning without message, incomplete tool calls)
+			// - Replaying them can cause API errors (e.g., OpenAI "reasoning without following item")
+			// - The model should retry from the last valid state
+			const assistantMsg = msg as AssistantMessage;
+			if (assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") {
+				continue;
+			}
+
+			// Track tool calls from this assistant message
+			const toolCalls = assistantMsg.content.filter((b) => b.type === "toolCall") as ToolCall[];
+			if (toolCalls.length > 0) {
+				pendingToolCalls = toolCalls;
+				existingToolResultIds = new Set();
+			}
+
+			result.push(msg);
+		} else if (msg.role === "toolResult") {
+			existingToolResultIds.add(msg.toolCallId);
+			result.push(msg);
+		} else if (msg.role === "user") {
+			// User message interrupts tool flow - insert synthetic results for orphaned calls
+			insertSyntheticToolResults();
+			result.push(msg);
+		} else {
+			result.push(msg);
+		}
+	}
+
+	// If the conversation ends with unresolved tool calls, synthesize results now.
+	insertSyntheticToolResults();
+
+	return result;
+}

package/packages/ai/src/api-registry.ts

@@ -0,0 +1,226 @@
+import { aiSdkApi } from "./api/ai-sdk.lazy.ts";
+import { getEnvApiKey } from "./env-api-keys.ts";
+import type { ModelsApiStreamOptions } from "./models.ts";
+import { builtinModels } from "./providers/all.ts";
+import { createFauxCore, type FauxProviderRegistration, type RegisterFauxProviderOptions } from "./providers/faux.ts";
+import type {
+	Api,
+	ApiStreamOptions,
+	AssistantMessage,
+	AssistantMessageEventStream,
+	Context,
+	Model,
+	ProviderStreamOptions,
+	ProviderStreams,
+	SimpleStreamOptions,
+	StreamFunction,
+	StreamOptions,
+} from "./types.ts";
+
+export type ApiStreamFunction = (
+	model: Model<Api>,
+	context: Context,
+	options?: StreamOptions,
+) => AssistantMessageEventStream;
+
+export type ApiStreamSimpleFunction = (
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+) => AssistantMessageEventStream;
+
+export interface ApiProvider<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> {
+	api: TApi;
+	stream: StreamFunction<TApi, TOptions>;
+	streamSimple: StreamFunction<TApi, SimpleStreamOptions>;
+}
+
+interface ApiProviderInternal {
+	api: Api;
+	stream: ApiStreamFunction;
+	streamSimple: ApiStreamSimpleFunction;
+}
+
+type RegisteredApiProvider = {
+	provider: ApiProviderInternal;
+	sourceId?: string;
+};
+
+const apiProviderRegistry = new Map<string, RegisteredApiProvider>();
+
+function wrapStream<TApi extends Api, TOptions extends StreamOptions>(
+	api: TApi,
+	stream: StreamFunction<TApi, TOptions>,
+): ApiStreamFunction {
+	return (model, context, options) => {
+		if (model.api !== api) {
+			throw new Error(`Mismatched api: ${model.api} expected ${api}`);
+		}
+		return stream(model as Model<TApi>, context, options as TOptions);
+	};
+}
+
+function wrapStreamSimple<TApi extends Api>(
+	api: TApi,
+	streamSimple: StreamFunction<TApi, SimpleStreamOptions>,
+): ApiStreamSimpleFunction {
+	return (model, context, options) => {
+		if (model.api !== api) {
+			throw new Error(`Mismatched api: ${model.api} expected ${api}`);
+		}
+		return streamSimple(model as Model<TApi>, context, options);
+	};
+}
+
+export function registerApiProvider<TApi extends Api, TOptions extends StreamOptions>(
+	provider: ApiProvider<TApi, TOptions>,
+	sourceId?: string,
+): void {
+	apiProviderRegistry.set(provider.api, {
+		provider: {
+			api: provider.api,
+			stream: wrapStream(provider.api, provider.stream),
+			streamSimple: wrapStreamSimple(provider.api, provider.streamSimple),
+		},
+		sourceId,
+	});
+}
+
+export function getApiProvider(api: Api): ApiProviderInternal | undefined {
+	return apiProviderRegistry.get(api)?.provider;
+}
+
+export function getApiProviders(): ApiProviderInternal[] {
+	return Array.from(apiProviderRegistry.values(), (entry) => entry.provider);
+}
+
+export function unregisterApiProviders(sourceId: string): void {
+	for (const [api, entry] of apiProviderRegistry.entries()) {
+		if (entry.sourceId === sourceId) {
+			apiProviderRegistry.delete(api);
+		}
+	}
+}
+
+export function registerFauxProvider(options: RegisterFauxProviderOptions = {}): FauxProviderRegistration {
+	const core = createFauxCore(options);
+	const sourceId = `faux-provider-${Math.random().toString(36).slice(2, 10)}`;
+	registerApiProvider({ api: core.api, stream: core.stream, streamSimple: core.streamSimple }, sourceId);
+	return {
+		api: core.api,
+		models: core.models,
+		getModel: core.getModel,
+		state: core.state,
+		setResponses: core.setResponses,
+		appendResponses: core.appendResponses,
+		getPendingResponseCount: core.getPendingResponseCount,
+		unregister() {
+			unregisterApiProviders(sourceId);
+		},
+	};
+}
+
+const BUILTIN_APIS: [Api, ProviderStreams][] = [["openai-completions", aiSdkApi()]];
+
+const builtinApiProviderInstances = new Map<Api, ReturnType<typeof getApiProvider>>();
+
+// Registriert die eingebauten APIs, ohne bereits registrierte Overrides zu überschreiben.
+export function registerBuiltInApiProviders(): void {
+	for (const [api, streams] of BUILTIN_APIS) {
+		if (!getApiProvider(api)) {
+			registerApiProvider({ api, stream: streams.stream, streamSimple: streams.streamSimple });
+		}
+		builtinApiProviderInstances.set(api, getApiProvider(api));
+	}
+}
+
+export function resetApiProviders(): void {
+	apiProviderRegistry.clear();
+	builtinApiProviderInstances.clear();
+	registerBuiltInApiProviders();
+}
+
+registerBuiltInApiProviders();
+
+const registryModels = builtinModels();
+const AMBIENT_AUTH_MARKER = "<authenticated>";
+
+function hasExplicitApiKey(apiKey: string | undefined): apiKey is string {
+	return typeof apiKey === "string" && apiKey.trim().length > 0;
+}
+
+function withEnvApiKey<TOptions extends StreamOptions>(
+	model: Model<Api>,
+	options: TOptions | undefined,
+): TOptions | undefined {
+	if (hasExplicitApiKey(options?.apiKey)) return options;
+	const apiKey = getEnvApiKey(model.provider, options?.env);
+	if (!apiKey || apiKey === AMBIENT_AUTH_MARKER) return options;
+	return { ...options, apiKey } as TOptions;
+}
+
+function hasResolvedCloudflareAuth(options: StreamOptions | undefined): boolean {
+	return hasExplicitApiKey(options?.apiKey) || typeof options?.headers?.["cf-aig-authorization"] === "string";
+}
+
+function getBuiltinProviderForModel(model: Model<Api>) {
+	if (getApiProvider(model.api) !== builtinApiProviderInstances.get(model.api)) return undefined;
+	const provider = registryModels.getProvider(model.provider);
+	return provider?.getModels().some((candidate) => candidate.api === model.api) ? provider : undefined;
+}
+
+function resolveApiProvider(api: Api) {
+	const provider = getApiProvider(api);
+	if (!provider) {
+		throw new Error(`No API provider registered for api: ${api}`);
+	}
+	return provider;
+}
+
+export function stream<TApi extends Api>(
+	model: Model<TApi>,
+	context: Context,
+	options?: ProviderStreamOptions,
+): AssistantMessageEventStream {
+	const builtinProvider = getBuiltinProviderForModel(model);
+	if (builtinProvider) {
+		if (model.provider.startsWith("cloudflare-") && !hasResolvedCloudflareAuth(options)) {
+			return registryModels.stream(model, context, options as ModelsApiStreamOptions<TApi> | undefined);
+		}
+		return builtinProvider.stream(model, context, withEnvApiKey(model, options) as ApiStreamOptions<TApi>);
+	}
+	const provider = resolveApiProvider(model.api);
+	return provider.stream(model, context, withEnvApiKey(model, options) as StreamOptions);
+}
+
+export async function complete<TApi extends Api>(
+	model: Model<TApi>,
+	context: Context,
+	options?: ProviderStreamOptions,
+): Promise<AssistantMessage> {
+	return stream(model, context, options).result();
+}
+
+export function streamSimple<TApi extends Api>(
+	model: Model<TApi>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const builtinProvider = getBuiltinProviderForModel(model);
+	if (builtinProvider) {
+		if (model.provider.startsWith("cloudflare-") && !hasResolvedCloudflareAuth(options)) {
+			return registryModels.streamSimple(model, context, options);
+		}
+		return builtinProvider.streamSimple(model, context, withEnvApiKey(model, options));
+	}
+	const provider = resolveApiProvider(model.api);
+	return provider.streamSimple(model, context, withEnvApiKey(model, options));
+}
+
+export async function completeSimple<TApi extends Api>(
+	model: Model<TApi>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): Promise<AssistantMessage> {
+	return streamSimple(model, context, options).result();
+}

package/packages/ai/src/auth/context.ts

@@ -0,0 +1,45 @@
+import type { AuthContext } from "./types.ts";
+
+interface NodeFsModule {
+	access(path: string): Promise<void>;
+}
+
+interface NodeOsModule {
+	homedir(): string;
+}
+
+// Variable specifier so browser bundlers do not try to resolve node builtins.
+const importNodeModule = (specifier: string): Promise<unknown> => import(specifier);
+
+function getProcessEnv(): Record<string, string | undefined> | undefined {
+	const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+	return proc?.env;
+}
+
+/**
+ * Default auth context: env vars from `process.env` (undefined in browsers),
+ * file existence via node:fs (always false in browsers).
+ */
+export function defaultProviderAuthContext(): AuthContext {
+	return {
+		async env(name: string): Promise<string | undefined> {
+			const value = getProcessEnv()?.[name];
+			return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+		},
+
+		async fileExists(path: string): Promise<boolean> {
+			try {
+				const fs = (await importNodeModule("node:fs/promises")) as NodeFsModule;
+				let resolved = path;
+				if (resolved.startsWith("~")) {
+					const os = (await importNodeModule("node:os")) as NodeOsModule;
+					resolved = os.homedir() + resolved.slice(1);
+				}
+				await fs.access(resolved);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+	};
+}

package/packages/ai/src/auth/credential-store.ts

@@ -0,0 +1,51 @@
+import type { Credential, CredentialInfo, CredentialStore } from "./types.ts";
+
+/**
+ * Default in-memory credential store. Apps inject persistent stores.
+ * Keyed by `Provider.id`, one credential per provider; see `CredentialStore`.
+ * Writes are serialized per provider through a promise chain.
+ */
+export class InMemoryCredentialStore implements CredentialStore {
+	private credentials = new Map<string, Credential>();
+	private chains = new Map<string, Promise<unknown>>();
+
+	/** Serialize tasks per provider id. */
+	private enqueue<T>(providerId: string, task: () => Promise<T>): Promise<T> {
+		const previous = this.chains.get(providerId) ?? Promise.resolve();
+		const next = (async () => {
+			await previous.catch(() => {});
+			return task();
+		})();
+		this.chains.set(
+			providerId,
+			next.catch(() => {}),
+		);
+		return next;
+	}
+
+	async read(providerId: string): Promise<Credential | undefined> {
+		return this.credentials.get(providerId);
+	}
+
+	async list(): Promise<readonly CredentialInfo[]> {
+		return [...this.credentials].map(([providerId, credential]) => ({ providerId, type: credential.type }));
+	}
+
+	modify(
+		providerId: string,
+		fn: (current: Credential | undefined) => Promise<Credential | undefined>,
+	): Promise<Credential | undefined> {
+		return this.enqueue(providerId, async () => {
+			const current = this.credentials.get(providerId);
+			const next = await fn(current);
+			if (next !== undefined) this.credentials.set(providerId, next);
+			return next ?? current;
+		});
+	}
+
+	delete(providerId: string): Promise<void> {
+		return this.enqueue(providerId, async () => {
+			this.credentials.delete(providerId);
+		});
+	}
+}

package/packages/ai/src/auth/helpers.ts

@@ -0,0 +1,47 @@
+import type { ApiKeyAuth, OAuthAuth } from "./types.ts";
+
+/**
+ * Standard api-key auth: a stored credential key wins, otherwise the first
+ * set env var resolves. Includes a `login` that prompts for the key.
+ * Providers with non-standard resolution (provider env, ambient files, IAM)
+ * write their own `ApiKeyAuth`.
+ */
+export function envApiKeyAuth(name: string, envVars: readonly string[]): ApiKeyAuth {
+	return {
+		name,
+		login: async (interaction) => {
+			const key = await interaction.prompt({ type: "secret", message: `Enter ${name}` });
+			return { type: "api_key", key };
+		},
+		resolve: async ({ ctx, credential }) => {
+			if (credential?.key) return { auth: { apiKey: credential.key }, source: "stored credential" };
+			for (const envVar of envVars) {
+				const value = await ctx.env(envVar);
+				if (value) return { auth: { apiKey: value }, source: envVar };
+			}
+			return undefined;
+		},
+	};
+}
+
+/**
+ * Wraps a dynamically imported `OAuthAuth` so provider definitions can
+ * advertise OAuth without importing the implementation. The flow loads on
+ * first `login`/`refresh`/`toAuth` call; callers keep Node-only flow code out
+ * of bundles by loading through a bundler-opaque dynamic import (variable
+ * specifier, see the bedrock lazy wrapper).
+ */
+export function lazyOAuth(input: { name: string; loginLabel?: string; load: () => Promise<OAuthAuth> }): OAuthAuth {
+	let promise: Promise<OAuthAuth> | undefined;
+	const loaded = () => {
+		promise ??= input.load();
+		return promise;
+	};
+	return {
+		name: input.name,
+		loginLabel: input.loginLabel,
+		login: async (interaction) => (await loaded()).login(interaction),
+		refresh: async (credential) => (await loaded()).refresh(credential),
+		toAuth: async (credential) => (await loaded()).toAuth(credential),
+	};
+}

package/packages/ai/src/auth/resolve.ts

@@ -0,0 +1,139 @@
+import type { ProviderEnv } from "../types.ts";
+import type {
+	ApiKeyAuth,
+	ApiKeyCredential,
+	AuthContext,
+	AuthResult,
+	Credential,
+	CredentialStore,
+	OAuthAuth,
+	OAuthCredential,
+	ProviderAuth,
+} from "./types.ts";
+
+export type ModelsErrorCode = "model_source" | "model_validation" | "provider" | "stream" | "auth" | "oauth";
+
+export interface AuthResolutionOverrides {
+	apiKey?: string;
+	env?: ProviderEnv;
+}
+
+export class ModelsError extends Error {
+	readonly code: ModelsErrorCode;
+
+	constructor(code: ModelsErrorCode, message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "ModelsError";
+		this.code = code;
+	}
+}
+
+/**
+ * Auth resolution shared by the `Models` and `ImagesModels` collections.
+ * A stored credential owns the provider: ambient/env is consulted only when
+ * nothing is stored. No silent env fallback after a failed refresh or for a
+ * credential type without a matching handler.
+ */
+export async function resolveProviderAuth(
+	provider: { id: string; auth: ProviderAuth },
+	credentials: CredentialStore,
+	authContext: AuthContext,
+	overrides?: AuthResolutionOverrides,
+): Promise<AuthResult | undefined> {
+	const requestAuthContext = overrides?.env ? overlayEnvAuthContext(authContext, overrides.env) : authContext;
+
+	if (overrides?.apiKey !== undefined && provider.auth.apiKey) {
+		return resolveApiKey(requestAuthContext, provider.auth.apiKey, provider.id, {
+			type: "api_key",
+			key: overrides.apiKey,
+			env: overrides.env,
+		});
+	}
+
+	const stored = await readCredential(credentials, provider.id);
+	if (stored) {
+		if (stored.type === "oauth" && provider.auth.oauth) {
+			return resolveStoredOAuth(credentials, provider.id, provider.auth.oauth, stored);
+		}
+		if (stored.type === "api_key" && provider.auth.apiKey) {
+			const credential = overrides?.env ? { ...stored, env: { ...stored.env, ...overrides.env } } : stored;
+			return resolveApiKey(requestAuthContext, provider.auth.apiKey, provider.id, credential);
+		}
+		return undefined;
+	}
+
+	// Ambient (env vars, AWS profiles, ADC files).
+	return provider.auth.apiKey
+		? resolveApiKey(requestAuthContext, provider.auth.apiKey, provider.id, undefined)
+		: undefined;
+}
+
+function overlayEnvAuthContext(base: AuthContext, env: ProviderEnv): AuthContext {
+	return {
+		env: async (name) => env[name] || (await base.env(name)),
+		fileExists: (path) => base.fileExists(path),
+	};
+}
+
+/**
+ * OAuth resolution with double-checked locking (same pattern as today's
+ * AuthStorage): valid tokens cost zero locks; expired tokens lock, re-check
+ * expiry under the lock, refresh once globally, and persist the rotated
+ * credential before release.
+ */
+async function resolveStoredOAuth(
+	credentials: CredentialStore,
+	providerId: string,
+	oauth: OAuthAuth,
+	stored: OAuthCredential,
+): Promise<AuthResult | undefined> {
+	let credential = stored;
+
+	if (Date.now() >= credential.expires) {
+		// Optimistic check said expired; the authoritative check runs under the lock.
+		let post: Credential | undefined;
+		try {
+			post = await credentials.modify(providerId, async (current) => {
+				if (current?.type !== "oauth") return undefined; // logged out meanwhile
+				if (Date.now() < current.expires) return undefined; // another process/request refreshed
+				try {
+					return await oauth.refresh(current);
+				} catch (error) {
+					throw new ModelsError("oauth", `OAuth refresh failed for ${providerId}`, { cause: error });
+				}
+			});
+		} catch (error) {
+			if (error instanceof ModelsError) throw error;
+			throw new ModelsError("auth", `Credential store modify failed for ${providerId}`, { cause: error });
+		}
+		if (post?.type !== "oauth") return undefined; // logged out meanwhile
+		credential = post;
+	}
+
+	try {
+		return { auth: await oauth.toAuth(credential), source: "OAuth" };
+	} catch (error) {
+		throw new ModelsError("oauth", `OAuth auth derivation failed for ${providerId}`, { cause: error });
+	}
+}
+
+async function resolveApiKey(
+	authContext: AuthContext,
+	apiKey: ApiKeyAuth,
+	providerId: string,
+	credential: ApiKeyCredential | undefined,
+): Promise<AuthResult | undefined> {
+	try {
+		return await apiKey.resolve({ ctx: authContext, credential });
+	} catch (error) {
+		throw new ModelsError("auth", `API key auth failed for provider ${providerId}`, { cause: error });
+	}
+}
+
+async function readCredential(credentials: CredentialStore, providerId: string): Promise<Credential | undefined> {
+	try {
+		return await credentials.read(providerId);
+	} catch (error) {
+		throw new ModelsError("auth", `Credential store read failed for ${providerId}`, { cause: error });
+	}
+}