@schlenkr/ragents 0.1.0

package/packages/ai/src/api/ai-sdk-transport.ts

@@ -0,0 +1,53 @@
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import type { ImagesModel, Model, ProviderHeaders } from "../types.ts";
+import { headersToRecord } from "../utils/headers.ts";
+
+interface SdkOptions<TModel> {
+	apiKey?: string;
+	headers?: ProviderHeaders;
+	onPayload?: (payload: unknown, model: TModel) => unknown | Promise<unknown>;
+	onResponse?: (response: { status: number; headers: Record<string, string> }, model: TModel) => void | Promise<void>;
+}
+
+export function createSdkProvider<TModel extends Model<string> | ImagesModel<string>>(model: TModel, options?: SdkOptions<TModel>) {
+	const headers = new Headers();
+	const suppressedHeaders = new Set<string>();
+	for (const source of [model.headers, options?.headers]) {
+		for (const [name, value] of Object.entries(source ?? {})) {
+			if (value === null) {
+				headers.delete(name);
+				suppressedHeaders.add(name.toLowerCase());
+			} else {
+				headers.set(name, value);
+				suppressedHeaders.delete(name.toLowerCase());
+			}
+		}
+	}
+	if (!options?.apiKey && !headers.has("authorization")) {
+		throw new Error(`No API key for provider: ${model.provider}`);
+	}
+	return createOpenRouter({
+		baseURL: model.baseUrl,
+		apiKey: options?.apiKey ?? "unused",
+		headers: headersToRecord(headers),
+		compatibility: "strict",
+		fetch: async (input, init) => {
+			const requestHeaders = new Headers(init?.headers);
+			for (const name of suppressedHeaders) requestHeaders.delete(name);
+			const payload = JSON.parse(String(init?.body));
+			const replacement = await options?.onPayload?.(payload, model);
+			const response = await globalThis.fetch(input, {
+				...init,
+				headers: requestHeaders,
+				body: JSON.stringify(replacement === undefined ? payload : replacement),
+			});
+			try {
+				await options?.onResponse?.({ status: response.status, headers: headersToRecord(response.headers) }, model);
+				return response;
+			} catch (error) {
+				await response.body?.cancel();
+				throw error;
+			}
+		},
+	});
+}

package/packages/ai/src/api/ai-sdk.lazy.ts

@@ -0,0 +1,4 @@
+import type { ProviderStreams } from "../types.ts";
+import { lazyApi } from "./lazy.ts";
+
+export const aiSdkApi = (): ProviderStreams => lazyApi(() => import("./ai-sdk.ts"));

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

@@ -0,0 +1,273 @@
+import { jsonSchema, streamText, stepCountIs, type LanguageModelUsage, type ProviderMetadata } from "ai";
+import { calculateCost, clampThinkingLevel } from "../models.ts";
+import type { AssistantMessage, Context, Model, SimpleStreamOptions, StreamFunction, StreamOptions, ToolCall } from "../types.ts";
+import { formatProviderError, normalizeProviderError } from "../utils/error-body.ts";
+import { AssistantMessageEventStream } from "../utils/event-stream.ts";
+import { parseStreamingJson } from "../utils/json-parse.ts";
+import { getProviderEnvValue } from "../utils/provider-env.ts";
+import { convertMessages } from "./ai-sdk-messages.ts";
+import { createSdkProvider } from "./ai-sdk-transport.ts";
+import { buildBaseOptions } from "./simple-options.ts";
+
+export interface OpenRouterOptions extends StreamOptions {
+	toolChoice?: "auto" | "none" | "required" | { type: "function"; function: { name: string } };
+	reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+
+export const stream: StreamFunction<"openai-completions", OpenRouterOptions> = (model, context, options) => {
+	const events = new AssistantMessageEventStream();
+	void runStream(model, context, options, events);
+	return events;
+};
+
+async function runStream(model: Model<"openai-completions">, context: Context, options: OpenRouterOptions | undefined, events: AssistantMessageEventStream) {
+	const output: AssistantMessage = {
+		role: "assistant",
+		content: [],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+		stopReason: "stop",
+		timestamp: Date.now(),
+	};
+	const controller = new AbortController();
+	const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+	try {
+		const retention = options?.cacheRetention ?? (getProviderEnvValue("AGENT_CACHE_RETENTION", options?.env) === "long" ? "long" : "short");
+		const cacheControl = retention !== "none" && (model.compat?.cacheControlFormat === "anthropic" || model.id.startsWith("anthropic/"))
+			? { type: "ephemeral" as const, ...(retention === "long" ? { ttl: "1h" as const } : {}) }
+			: undefined;
+		const messages = convertMessages(context, model, cacheControl);
+		const provider = createSdkProvider(model, {
+			...options,
+			headers: { ...(retention !== "none" && options?.sessionId ? { "x-session-id": options.sessionId } : {}), ...options?.headers },
+			onPayload: async (payload, target) => {
+				applyRequestCompatibility(payload, model, cacheControl);
+				return options?.onPayload?.(payload, target);
+			},
+		});
+		const effort = options?.reasoningEffort;
+		const offEffort = model.thinkingLevelMap?.off;
+		const reasoning = effort ? { effort: model.thinkingLevelMap?.[effort] ?? effort }
+			: typeof offEffort === "string" ? { effort: offEffort } : { enabled: false };
+		const hasPdf = context.messages.some((message) => message.role === "user" && Array.isArray(message.content)
+			&& message.content.some((part) => part.type === "file" && part.mimeType === "application/pdf"));
+		const result = streamText({
+			model: provider.chat(model.id),
+			instructions: messages.filter((message) => message.role === "system"),
+			messages: messages.filter((message) => message.role !== "system"),
+			tools: Object.fromEntries((context.tools ?? []).map((tool) => [tool.name, {
+				description: tool.description,
+				inputSchema: jsonSchema(tool.parameters, { validate: async (value) => ({ success: true as const, value }) }),
+			}])),
+			toolChoice: typeof options?.toolChoice === "object" ? { type: "tool", toolName: options.toolChoice.function.name } : options?.toolChoice,
+			temperature: options?.temperature,
+			maxOutputTokens: options?.maxTokens,
+			maxRetries: options?.maxRetries ?? 0,
+			streamRetries: 0,
+			abortSignal: signal,
+			timeout: options?.timeoutMs,
+			stopWhen: stepCountIs(1),
+			includeRawChunks: true,
+			onError: () => {},
+			providerOptions: { openrouter: {
+				...(model.reasoning ? { reasoning } : {}),
+				...(model.compat?.openRouterRouting ? { provider: { ...model.compat.openRouterRouting } } : {}),
+				...(hasPdf ? { plugins: [{ id: "file-parser", pdf: { engine: "native" } }] } : {}),
+			} },
+		});
+		const indices = new Map<string, number>();
+		const argumentsById = new Map<string, string>();
+		const rawTools = new Map<number, { id?: string; name?: string; input: string }>();
+		let rawThinkingIndex: number | undefined;
+		let hasFinishReason = false;
+		let finished = false;
+		for await (const part of result.fullStream) {
+			switch (part.type) {
+				case "raw": {
+					const chunk = part.rawValue as { id?: string; model?: string; choices?: Array<{ finish_reason?: string | null; delta?: {
+						reasoning?: string; reasoning_content?: string; reasoning_text?: string; reasoning_details?: unknown[];
+						tool_calls?: Array<{ index: number; id?: string; function?: { name?: string; arguments?: string } }>;
+					} }> };
+					if (chunk.id) output.responseId = chunk.id;
+					if (chunk.model) output.responseModel = chunk.model;
+					if (chunk.choices?.[0]?.finish_reason != null) hasFinishReason = true;
+					const delta = chunk.choices?.[0]?.delta;
+					for (const fragment of delta?.tool_calls ?? []) {
+						const tool = rawTools.get(fragment.index) ?? { input: "" };
+						tool.id ??= fragment.id;
+						tool.name ??= fragment.function?.name;
+						tool.input += fragment.function?.arguments ?? "";
+						rawTools.set(fragment.index, tool);
+						if (tool.id && tool.name && !indices.has(tool.id)) {
+							const contentIndex = output.content.length;
+							indices.set(tool.id, contentIndex);
+							argumentsById.set(tool.id, "");
+							output.content.push({ type: "toolCall", id: tool.id, name: tool.name, arguments: {} });
+							events.push({ type: "toolcall_start", contentIndex, partial: output });
+						}
+					}
+					const thinking = delta?.reasoning_content || delta?.reasoning_text;
+					if (!thinking || delta?.reasoning || delta?.reasoning_details?.length) break;
+					if (rawThinkingIndex === undefined) {
+						rawThinkingIndex = output.content.length;
+						output.content.push({ type: "thinking", thinking: "" });
+						events.push({ type: "thinking_start", contentIndex: rawThinkingIndex, partial: output });
+					}
+					const block = output.content[rawThinkingIndex];
+					if (block.type === "thinking") block.thinking += thinking;
+					events.push({ type: "thinking_delta", contentIndex: rawThinkingIndex, delta: thinking, partial: output });
+					break;
+				}
+				case "start-step":
+					events.push({ type: "start", partial: output });
+					break;
+				case "text-start":
+				case "reasoning-start": {
+					const contentIndex = output.content.length;
+					indices.set(part.id, contentIndex);
+					output.content.push(part.type === "text-start" ? { type: "text", text: "" } : { type: "thinking", thinking: "" });
+					events.push({ type: part.type === "text-start" ? "text_start" : "thinking_start", contentIndex, partial: output });
+					break;
+				}
+				case "text-delta":
+				case "reasoning-delta": {
+					const contentIndex = requireIndex(indices, part.id);
+					const block = output.content[contentIndex];
+					if (block.type === "text") block.text += part.text;
+					if (block.type === "thinking") block.thinking += part.text;
+					events.push({ type: part.type === "text-delta" ? "text_delta" : "thinking_delta", contentIndex, delta: part.text, partial: output });
+					break;
+				}
+				case "text-end":
+				case "reasoning-end": {
+					const contentIndex = requireIndex(indices, part.id);
+					const block = output.content[contentIndex];
+					if (block.type === "text") events.push({ type: "text_end", contentIndex, content: block.text, partial: output });
+					if (block.type === "thinking") {
+						const details = reasoningDetails(part.providerMetadata);
+						if (details) block.thinkingSignature = JSON.stringify(details);
+						events.push({ type: "thinking_end", contentIndex, content: block.thinking, partial: output });
+					}
+					break;
+				}
+				case "tool-input-start": {
+					if (indices.has(part.id)) break;
+					const contentIndex = output.content.length;
+					indices.set(part.id, contentIndex);
+					argumentsById.set(part.id, "");
+					output.content.push({ type: "toolCall", id: part.id, name: part.toolName, arguments: {} });
+					events.push({ type: "toolcall_start", contentIndex, partial: output });
+					break;
+				}
+				case "tool-input-delta": {
+					const contentIndex = requireIndex(indices, part.id);
+					const input = (argumentsById.get(part.id) ?? "") + part.delta;
+					argumentsById.set(part.id, input);
+					(output.content[contentIndex] as ToolCall).arguments = parseStreamingJson(input);
+					events.push({ type: "toolcall_delta", contentIndex, delta: part.delta, partial: output });
+					break;
+				}
+				case "tool-call": {
+					const contentIndex = requireIndex(indices, part.toolCallId);
+					const toolCall = output.content[contentIndex] as ToolCall;
+					const rawTool = [...rawTools.values()].find((tool) => tool.id === part.toolCallId);
+					if (rawTool) toolCall.arguments = parseStreamingJson(rawTool.input);
+					const details = reasoningDetails(part.providerMetadata);
+					if (details) toolCall.thoughtSignature = JSON.stringify(details);
+					events.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
+					break;
+				}
+				case "finish-step": {
+					output.responseId = part.response.id;
+					output.responseModel = part.response.modelId;
+					output.usage = convertUsage(part.usage, model);
+					const details = reasoningDetails(part.providerMetadata);
+					if (details) {
+						const block = output.content.find((item) => item.type === "thinking");
+						if (block) block.thinkingSignature = JSON.stringify(details);
+						else {
+							const tool = output.content.find((item) => item.type === "toolCall");
+							if (tool) tool.thoughtSignature = JSON.stringify(details);
+							else output.content.push({ type: "thinking", thinking: "", redacted: true, thinkingSignature: JSON.stringify(details) });
+						}
+					}
+					break;
+				}
+				case "finish":
+					if (part.finishReason === "stop") output.stopReason = "stop";
+					else if (part.finishReason === "length") output.stopReason = "length";
+					else if (part.finishReason === "tool-calls") output.stopReason = "toolUse";
+					else throw new Error(`Provider finish_reason: ${part.rawFinishReason ?? part.finishReason}`);
+					finished = true;
+					break;
+				case "abort": throw new Error(part.reason ?? "Request aborted");
+				case "error": throw part.error;
+			}
+		}
+		if (signal.aborted) throw new Error("Request aborted");
+		if (!finished || !hasFinishReason) throw new Error("Provider stream ended without a finish reason");
+		if (rawThinkingIndex !== undefined) {
+			const block = output.content[rawThinkingIndex];
+			if (block.type === "thinking") events.push({ type: "thinking_end", contentIndex: rawThinkingIndex, content: block.thinking, partial: output });
+		}
+		events.push({ type: "done", reason: output.stopReason as "stop" | "length" | "toolUse", message: output });
+	} catch (error) {
+		controller.abort();
+		output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+		output.errorMessage = formatProviderError(normalizeProviderError(error), model.provider === "relay" ? `Relay ${model.baseUrl}` : undefined);
+		events.push({ type: "error", reason: output.stopReason, error: output });
+	} finally {
+		events.end();
+	}
+}
+
+function requireIndex(indices: Map<string, number>, id: string): number {
+	const index = indices.get(id);
+	if (index === undefined) throw new Error(`Provider emitted a delta without a start: ${id}`);
+	return index;
+}
+
+function reasoningDetails(metadata: ProviderMetadata | undefined) {
+	const details = metadata?.openrouter?.reasoning_details;
+	return Array.isArray(details) && details.length > 0 ? details : undefined;
+}
+
+function convertUsage(usage: LanguageModelUsage, model: Model<"openai-completions">): AssistantMessage["usage"] {
+	const cacheRead = usage.inputTokenDetails.cacheReadTokens ?? 0;
+	const cacheWrite = usage.inputTokenDetails.cacheWriteTokens ?? 0;
+	const input = Math.max(0, (usage.inputTokens ?? 0) - cacheRead - cacheWrite);
+	const output = usage.outputTokens ?? 0;
+	const result = {
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		reasoning: usage.outputTokenDetails.reasoningTokens ?? 0,
+		totalTokens: input + output + cacheRead + cacheWrite,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+	calculateCost(model, result);
+	return result;
+}
+
+function applyRequestCompatibility(payload: unknown, model: Model<"openai-completions">, cacheControl: { type: "ephemeral"; ttl?: "1h" } | undefined) {
+	const body = payload as { messages: Array<{ role: string; reasoning?: string; reasoning_content?: string }>; tools?: Array<{ cache_control?: unknown }> };
+	if (model.compat?.requiresReasoningContentOnAssistantMessages) {
+		for (const message of body.messages) {
+			if (message.role === "assistant") message.reasoning_content = message.reasoning ?? "";
+		}
+	}
+	if (cacheControl && body.tools?.length) body.tools[body.tools.length - 1].cache_control = cacheControl;
+	if (!body.tools && body.messages.some((message) => message.role === "tool")) body.tools = [];
+}
+
+export const streamSimple: StreamFunction<"openai-completions", SimpleStreamOptions> = (model, context, options) => {
+	const reasoning = options?.reasoning ? clampThinkingLevel(model, options.reasoning) : undefined;
+	return stream(model, context, {
+		...buildBaseOptions(model, context, options, options?.apiKey),
+		reasoningEffort: reasoning === "off" ? undefined : reasoning,
+		toolChoice: (options as OpenRouterOptions | undefined)?.toolChoice,
+	});
+};

package/packages/ai/src/api/lazy.ts

@@ -0,0 +1,75 @@
+import type { Api, AssistantMessage, AssistantMessageEvent, Model, ProviderStreams } from "../types.ts";
+import { AssistantMessageEventStream } from "../utils/event-stream.ts";
+
+function createSetupErrorMessage(model: Model<Api>, error: unknown): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "error",
+		errorMessage: error instanceof Error ? error.message : String(error),
+		timestamp: Date.now(),
+	};
+}
+
+function hasResult(
+	source: AsyncIterable<AssistantMessageEvent>,
+): source is AsyncIterable<AssistantMessageEvent> & { result(): Promise<AssistantMessage> } {
+	return typeof (source as { result?: unknown }).result === "function";
+}
+
+async function forwardStream(
+	target: AssistantMessageEventStream,
+	source: AsyncIterable<AssistantMessageEvent>,
+): Promise<void> {
+	for await (const event of source) {
+		target.push(event);
+	}
+	target.end(hasResult(source) ? await source.result() : undefined);
+}
+
+/**
+ * Returns a stream synchronously while running async setup (auth resolution,
+ * lazy module loading) behind it. Setup failures terminate the stream with an
+ * error event.
+ */
+export function lazyStream(
+	model: Model<Api>,
+	setup: () => Promise<AsyncIterable<AssistantMessageEvent>>,
+): AssistantMessageEventStream {
+	const outer = new AssistantMessageEventStream();
+
+	setup()
+		.then((inner) => forwardStream(outer, inner))
+		.catch((error) => {
+			const message = createSetupErrorMessage(model, error);
+			outer.push({ type: "error", reason: "error", error: message });
+			outer.end(message);
+		});
+
+	return outer;
+}
+
+/**
+ * Wraps a dynamically imported API implementation module as `ProviderStreams`.
+ * The module loads on first stream call; the host's import cache deduplicates
+ * loads. Load failures terminate the returned stream with an error event.
+ */
+export function lazyApi(load: () => Promise<ProviderStreams>): ProviderStreams {
+	return {
+		stream: (model, context, options) =>
+			lazyStream(model, async () => (await load()).stream(model, context, options)),
+		streamSimple: (model, context, options) =>
+			lazyStream(model, async () => (await load()).streamSimple(model, context, options)),
+	};
+}

package/packages/ai/src/api/openrouter-images.lazy.ts

@@ -0,0 +1,10 @@
+import type { ImagesModel, ProviderImages } from "../types.ts";
+
+export const openrouterImagesApi = (): ProviderImages => ({
+	generateImages: async (model, context, options) =>
+		(await import("./openrouter-images.ts")).generateImages(
+			model as ImagesModel<"openrouter-images">,
+			context,
+			options,
+		),
+});

package/packages/ai/src/api/openrouter-images.ts

@@ -0,0 +1,98 @@
+import { convertDataContentToBase64String, generateText } from "ai";
+import type {
+	AssistantImages,
+	ImagesContext,
+	ImagesFunction,
+	ImagesModel,
+	ImagesOptions,
+} from "../types.ts";
+import { formatProviderError, normalizeProviderError } from "../utils/error-body.ts";
+import { sanitizeSurrogates } from "../utils/sanitize-unicode.ts";
+import { createSdkProvider } from "./ai-sdk-transport.ts";
+
+export const generateImages: ImagesFunction<"openrouter-images", ImagesOptions> = async (
+	model: ImagesModel<"openrouter-images">,
+	context: ImagesContext,
+	options?: ImagesOptions,
+) => {
+	const output: AssistantImages = {
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		output: [],
+		stopReason: "stop",
+		timestamp: Date.now(),
+	};
+
+	try {
+		const provider = createSdkProvider(model, options ?? {});
+		const result = await generateText({
+			model: provider.chat(model.id, {
+				extraBody: {
+					stream: false,
+					modalities: model.output.includes("text") ? ["image", "text"] : ["image"],
+				},
+			}),
+			messages: [{
+				role: "user",
+				content: context.input.map((item) => item.type === "text"
+					? { type: "text" as const, text: sanitizeSurrogates(item.text) }
+					: { type: "file" as const, data: item.data, mediaType: item.mimeType }),
+			}],
+			maxRetries: options?.maxRetries ?? 0,
+			abortSignal: options?.signal,
+			timeout: options?.timeoutMs,
+		});
+		if (result.files.length === 0) throw new Error("Image generation returned no images");
+		const images = result.files.map((file) => ({
+			type: "image" as const,
+			mimeType: file.mediaType,
+			data: convertDataContentToBase64String(file.uint8Array),
+		}));
+		output.responseId = result.response.id;
+		const rawUsage = result.steps[0]?.usage.raw;
+		if (rawUsage) {
+			output.usage = parseUsage(rawUsage, model);
+		}
+		if (result.text.length > 0) {
+			output.output.push({ type: "text", text: result.text });
+		}
+		output.output.push(...images);
+		return output;
+	} catch (error) {
+		output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+		output.errorMessage = formatProviderError(normalizeProviderError(error));
+		return output;
+	}
+};
+
+function parseUsage(
+	rawUsage: {
+		prompt_tokens?: number;
+		completion_tokens?: number;
+		prompt_tokens_details?: { cached_tokens?: number; cache_write_tokens?: number };
+	},
+	model: ImagesModel<"openrouter-images">,
+) {
+	const promptTokens = rawUsage.prompt_tokens || 0;
+	const cacheReadTokens = rawUsage.prompt_tokens_details?.cached_tokens || 0;
+	const cacheWriteTokens = rawUsage.prompt_tokens_details?.cache_write_tokens || 0;
+	const input = Math.max(0, promptTokens - cacheReadTokens - cacheWriteTokens);
+	const output = rawUsage.completion_tokens || 0;
+	const usage = {
+		input,
+		output,
+		cacheRead: cacheReadTokens,
+		cacheWrite: cacheWriteTokens,
+		totalTokens: input + output + cacheReadTokens + cacheWriteTokens,
+		cost: {
+			input: (model.cost.input / 1000000) * input,
+			output: (model.cost.output / 1000000) * output,
+			cacheRead: (model.cost.cacheRead / 1000000) * cacheReadTokens,
+			cacheWrite: (model.cost.cacheWrite / 1000000) * cacheWriteTokens,
+			total: 0,
+		},
+	};
+	usage.cost.total = usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+	return usage;
+}

package/packages/ai/src/api/simple-options.ts

@@ -0,0 +1,77 @@
+import type {
+	Api,
+	Context,
+	Model,
+	SimpleStreamOptions,
+	StreamOptions,
+	ThinkingBudgets,
+	ThinkingLevel,
+} from "../types.ts";
+import { estimateContextTokens } from "../utils/estimate.ts";
+
+const CONTEXT_SAFETY_TOKENS = 4096;
+const MIN_MAX_TOKENS = 1;
+
+export function clampMaxTokensToContext(model: Model<Api>, context: Context, maxTokens: number): number {
+	if (model.contextWindow <= 0) return Math.max(MIN_MAX_TOKENS, maxTokens);
+	const available = model.contextWindow - estimateContextTokens(context).tokens - CONTEXT_SAFETY_TOKENS;
+	return Math.min(maxTokens, Math.max(MIN_MAX_TOKENS, available));
+}
+
+export function buildBaseOptions(
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+	apiKey?: string,
+): StreamOptions {
+	return {
+		temperature: options?.temperature,
+		maxTokens: clampMaxTokensToContext(model, context, options?.maxTokens ?? model.maxTokens),
+		signal: options?.signal,
+		apiKey: apiKey || options?.apiKey,
+		transport: options?.transport,
+		cacheRetention: options?.cacheRetention,
+		sessionId: options?.sessionId,
+		headers: options?.headers,
+		onPayload: options?.onPayload,
+		onResponse: options?.onResponse,
+		timeoutMs: options?.timeoutMs,
+		websocketConnectTimeoutMs: options?.websocketConnectTimeoutMs,
+		maxRetries: options?.maxRetries,
+		maxRetryDelayMs: options?.maxRetryDelayMs,
+		metadata: options?.metadata,
+		env: options?.env,
+	};
+}
+
+export function clampReasoning(effort: ThinkingLevel | undefined): Exclude<ThinkingLevel, "xhigh" | "max"> | undefined {
+	return effort === "xhigh" || effort === "max" ? "high" : effort;
+}
+
+export function adjustMaxTokensForThinking(
+	// Undefined means no explicit caller cap. Use the model cap and fit thinking inside it.
+	baseMaxTokens: number | undefined,
+	modelMaxTokens: number,
+	reasoningLevel: ThinkingLevel,
+	customBudgets?: ThinkingBudgets,
+): { maxTokens: number; thinkingBudget: number } {
+	const defaultBudgets: ThinkingBudgets = {
+		minimal: 1024,
+		low: 2048,
+		medium: 8192,
+		high: 16384,
+	};
+	const budgets = { ...defaultBudgets, ...customBudgets };
+
+	const minOutputTokens = 1024;
+	const level = clampReasoning(reasoningLevel)!;
+	let thinkingBudget = budgets[level]!;
+	const maxTokens =
+		baseMaxTokens === undefined ? modelMaxTokens : Math.min(baseMaxTokens + thinkingBudget, modelMaxTokens);
+
+	if (maxTokens <= thinkingBudget) {
+		thinkingBudget = Math.max(0, maxTokens - minOutputTokens);
+	}
+
+	return { maxTokens, thinkingBudget };
+}