@dex-ai/google 0.1.3

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dex-ai/google",
+  "version": "0.1.3",
+  "description": "Google Gemini API provider for @dex-ai/sdk.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.1",
+    "zod-to-json-schema": "^3.24.0"
+  },
+  "devDependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,39 @@
+/** Google Gemini API error class. */
+
+export class GeminiError extends Error {
+	readonly status: number;
+	readonly code: string | null;
+
+	constructor(status: number, code: string | null, message: string) {
+		super(message);
+		this.name = "GeminiError";
+		this.status = status;
+		this.code = code;
+	}
+
+	static async fromResponse(res: Response): Promise<GeminiError> {
+		let body: string;
+		try {
+			body = await res.text();
+		} catch {
+			body = "";
+		}
+
+		let code: string | null = null;
+		let message = `${res.status} ${res.statusText}`;
+
+		try {
+			const json = JSON.parse(body) as {
+				error?: { message?: string; status?: string; code?: number };
+			};
+			if (json.error) {
+				message = json.error.message ?? message;
+				code = json.error.status ?? null;
+			}
+		} catch {
+			if (body) message += ` — ${body.slice(0, 200)}`;
+		}
+
+		return new GeminiError(res.status, code, message);
+	}
+}

package/src/extension.ts

@@ -0,0 +1,189 @@
+/**
+ * Google Gemini Extension — provides models via the Gemini API.
+ */
+
+import type {
+	Extension,
+	Model,
+	StreamPart,
+	ModelRequest,
+	ThinkingLevel,
+} from "@dex-ai/sdk";
+import { createGeminiStream } from "./stream";
+
+/* ------------------------------------------------------------------ */
+/* Options                                                             */
+/* ------------------------------------------------------------------ */
+
+export interface GoogleExtensionOptions {
+	/** API key. Falls back to GOOGLE_API_KEY → GEMINI_API_KEY. */
+	readonly apiKey?: string;
+	/** Base URL. Default: https://generativelanguage.googleapis.com/v1beta */
+	readonly baseUrl?: string;
+	/** Extension name. Default: "google". */
+	readonly name?: string;
+	/** Model IDs to register statically. Discovery adds more. */
+	readonly models?: ReadonlyArray<string | ModelConfig>;
+	/**
+	 * Models endpoint path for discovery.
+	 * Default: "/models". Set to null to disable.
+	 */
+	readonly modelsPath?: string | null;
+	/** Emit raw-chunk parts during streaming. Default: false. */
+	readonly rawChunks?: boolean;
+	/** Fetch override. */
+	readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+export interface ModelConfig {
+	readonly id: string;
+	readonly name?: string;
+	readonly contextWindow?: number;
+	readonly maxTokens?: number;
+	readonly reasoning?: boolean;
+	readonly thinkingLevels?: ReadonlyArray<ThinkingLevel>;
+	readonly input?: ReadonlyArray<"text" | "image">;
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+function resolveBaseUrl(opts: GoogleExtensionOptions): string {
+	const raw =
+		opts.baseUrl ||
+		process.env.GOOGLE_BASE_URL ||
+		"https://generativelanguage.googleapis.com/v1beta";
+	return raw.replace(/\/+$/, "");
+}
+
+function resolveApiKey(opts: GoogleExtensionOptions): string {
+	const key =
+		opts.apiKey ||
+		process.env.GOOGLE_API_KEY ||
+		process.env.GEMINI_API_KEY;
+	if (!key) {
+		throw new Error(
+			"@dex-ai/google: no API key found. Set apiKey, GOOGLE_API_KEY, or GEMINI_API_KEY.",
+		);
+	}
+	return key;
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                   */
+/* ------------------------------------------------------------------ */
+
+export function googleExtension(
+	opts: GoogleExtensionOptions = {},
+): Extension {
+	const extName = opts.name ?? "google";
+	const baseUrl = resolveBaseUrl(opts);
+	const apiKey = resolveApiKey(opts);
+	const rawChunks = opts.rawChunks ?? false;
+	const doFetch =
+		opts.fetch ?? ((url: string, init: RequestInit) => fetch(url, init));
+
+	function createStreamFn(
+		modelId: string,
+		modelMaxTokens?: number,
+	): (req: ModelRequest) => AsyncIterable<StreamPart> {
+		return createGeminiStream(
+			{ baseUrl, apiKey, modelId, providerName: extName, rawChunks, doFetch },
+			modelMaxTokens,
+		);
+	}
+
+	// Static models from config
+	const staticModels: Model[] = (opts.models ?? []).map((m) => {
+		const cfg: ModelConfig = typeof m === "string" ? { id: m } : m;
+		return {
+			id: cfg.id,
+			...(cfg.name !== undefined ? { name: cfg.name } : {}),
+			...(cfg.contextWindow !== undefined
+				? { contextWindow: cfg.contextWindow }
+				: {}),
+			...(cfg.maxTokens !== undefined ? { maxTokens: cfg.maxTokens } : {}),
+			...(cfg.reasoning !== undefined ? { reasoning: cfg.reasoning } : {}),
+			...(cfg.thinkingLevels !== undefined
+				? { thinkingLevels: cfg.thinkingLevels }
+				: {}),
+			...(cfg.input !== undefined ? { input: cfg.input } : {}),
+			stream: createStreamFn(cfg.id, cfg.maxTokens),
+		};
+	});
+
+	const allModels: Model[] = [...staticModels];
+
+	return {
+		name: extName,
+		get models() {
+			return allModels;
+		},
+
+		async init() {
+			const modelsPath =
+				opts.modelsPath !== null ? (opts.modelsPath ?? "/models") : null;
+			if (!modelsPath) return;
+
+			try {
+				const modelsUrl = `${baseUrl}${modelsPath}?key=${apiKey}`;
+				const res = await doFetch(modelsUrl, { method: "GET" });
+				if (!res.ok) return;
+
+				const json = (await res.json()) as any;
+				const modelList: Array<{
+					name: string;
+					displayName?: string;
+					inputTokenLimit?: number;
+					outputTokenLimit?: number;
+					supportedGenerationMethods?: string[];
+				}> = json.models ?? (Array.isArray(json) ? json : []);
+
+				const staticIds = new Set(staticModels.map((m) => m.id));
+				for (const m of modelList) {
+					if (!m.name) continue;
+					// Model name format: "models/gemini-2.0-flash" → strip prefix
+					const id = m.name.startsWith("models/")
+						? m.name.slice(7)
+						: m.name;
+					if (staticIds.has(id)) continue;
+
+					// Only include models that support generateContent
+					const methods = m.supportedGenerationMethods ?? [];
+					if (!methods.includes("generateContent")) continue;
+
+					const isReasoning = id.includes("2.5") || id.includes("3.");
+
+					allModels.push({
+						id,
+						...(m.displayName ? { name: m.displayName } : {}),
+						...(m.inputTokenLimit
+							? { contextWindow: m.inputTokenLimit }
+							: {}),
+						...(m.outputTokenLimit
+							? { maxTokens: m.outputTokenLimit }
+							: {}),
+						reasoning: isReasoning,
+						...(isReasoning
+							? {
+									thinkingLevels: [
+										"off",
+										"min",
+										"low",
+										"med",
+										"high",
+										"max",
+									] as ThinkingLevel[],
+								}
+							: {}),
+						input: ["text", "image"],
+						stream: createStreamFn(id, m.outputTokenLimit),
+					});
+				}
+			} catch {
+				// Discovery failed — proceed with static models only
+			}
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { googleExtension } from "./extension";
+export type { GoogleExtensionOptions, ModelConfig } from "./extension";
+
+import type { ProviderDescriptor } from "@dex-ai/sdk";
+import { googleExtension } from "./extension";
+
+export const descriptor: ProviderDescriptor = {
+	type: "google",
+	label: "Google Gemini",
+	fields: [
+		{ key: "apiKey", label: "API Key", required: true, secret: true, envVar: "GOOGLE_API_KEY", hint: "Press Enter to use GOOGLE_API_KEY env var" },
+		{ key: "baseUrl", label: "Base URL", required: false, hint: "Custom endpoint (leave blank for default)" },
+		{ key: "models", label: "Models", required: false, hint: "Comma-separated model IDs, or leave blank to auto-discover" },
+	],
+	create(config) {
+		const models = config.models as string[] | undefined;
+		return googleExtension({
+			...(config.name ? { name: config.name as string } : {}),
+			...(config.apiKey ? { apiKey: config.apiKey as string } : {}),
+			...(config.baseUrl ? { baseUrl: config.baseUrl as string } : {}),
+			...(models ? { models } : {}),
+			...(models?.length ? { modelsPath: null } : {}),
+		});
+	},
+};

package/src/sse.ts

@@ -0,0 +1,34 @@
+/** Minimal SSE line parser for streaming API responses. */
+
+export interface SSEFrame {
+	data: string;
+}
+
+/** Parse a ReadableStream<Uint8Array> into SSE frames. Yields each `data:` payload (trimmed of the prefix). */
+export async function* parseSSE(
+	body: ReadableStream<Uint8Array>,
+): AsyncGenerator<SSEFrame> {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let nl: number;
+			while ((nl = buffer.indexOf("\n")) !== -1) {
+				const line = buffer.slice(0, nl).replace(/\r$/, "");
+				buffer = buffer.slice(nl + 1);
+				if (!line) continue;
+				if (line.startsWith("data: ")) {
+					yield { data: line.slice(6) };
+				} else if (line.startsWith("data:")) {
+					yield { data: line.slice(5) };
+				}
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}

package/src/stream.ts

@@ -0,0 +1,301 @@
+/**
+ * Gemini streaming: POST /v1beta/models/{model}:streamGenerateContent?alt=sse → StreamPart
+ */
+
+import type {
+	StreamPart,
+	ModelRequest,
+	FinishReason,
+	Usage,
+	ResponseMeta,
+	Content,
+	Message,
+} from "@dex-ai/sdk";
+import { parseSSE } from "./sse";
+import { GeminiError } from "./errors";
+import {
+	messagesToGemini,
+	toolsToGemini,
+	toolChoiceToGemini,
+} from "./translate";
+import { thinkingToGeminiConfig } from "./thinking";
+
+/* ------------------------------------------------------------------ */
+/* Types                                                               */
+/* ------------------------------------------------------------------ */
+
+interface StreamOptions {
+	baseUrl: string;
+	apiKey: string;
+	modelId: string;
+	providerName: string;
+	rawChunks: boolean;
+	doFetch: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+/* ------------------------------------------------------------------ */
+/* FinishReason mapping                                                */
+/* ------------------------------------------------------------------ */
+
+function mapFinishReason(reason: string | undefined | null): FinishReason {
+	switch (reason) {
+		case "STOP":
+			return "stop";
+		case "MAX_TOKENS":
+			return "length";
+		case "SAFETY":
+		case "RECITATION":
+			return "content-filter";
+		default:
+			return "stop";
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* createGeminiStream                                                   */
+/* ------------------------------------------------------------------ */
+
+export function createGeminiStream(
+	opts: StreamOptions,
+	modelMaxTokens?: number,
+): (req: ModelRequest) => AsyncIterable<StreamPart> {
+	const { baseUrl, apiKey, modelId, providerName, rawChunks, doFetch } = opts;
+
+	return async function* stream(req: ModelRequest): AsyncIterable<StreamPart> {
+		const startedAt = Date.now();
+		const url = `${baseUrl}/models/${modelId}:streamGenerateContent?alt=sse&key=${apiKey}`;
+
+		// Build request body
+		const { systemInstruction, contents } = messagesToGemini(req.messages);
+		const body: Record<string, unknown> = { contents };
+
+		if (systemInstruction) {
+			body.systemInstruction = { parts: [{ text: systemInstruction }] };
+		}
+
+		// Generation config
+		const genConfig: Record<string, unknown> = {};
+		if (req.maxTokens !== undefined) genConfig.maxOutputTokens = req.maxTokens;
+		else if (modelMaxTokens !== undefined)
+			genConfig.maxOutputTokens = modelMaxTokens;
+		if (req.temperature !== undefined)
+			genConfig.temperature = req.temperature;
+		if (req.topP !== undefined) genConfig.topP = req.topP;
+		if (req.stopSequences?.length)
+			genConfig.stopSequences = req.stopSequences;
+		if (req.seed !== undefined) genConfig.seed = req.seed;
+
+		// Thinking config (Gemini 2.5+)
+		const thinkingConfig = thinkingToGeminiConfig(
+			req.thinking,
+			modelMaxTokens,
+		);
+		if (thinkingConfig) {
+			genConfig.thinkingConfig = thinkingConfig;
+		}
+
+		if (Object.keys(genConfig).length > 0) {
+			body.generationConfig = genConfig;
+		}
+
+		// Tools
+		if (req.tools?.length) {
+			body.tools = [toolsToGemini(req.tools)];
+			const tc = toolChoiceToGemini(req.toolChoice);
+			if (tc !== undefined) body.toolConfig = tc;
+		}
+
+		// Provider options pass-through
+		if (req.providerOptions) Object.assign(body, req.providerOptions);
+
+		const init: RequestInit = {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+		};
+		if (req.signal) (init as { signal: AbortSignal }).signal = req.signal;
+
+		let res: Response;
+		try {
+			res = await doFetch(url, init);
+		} catch (err: unknown) {
+			if (err instanceof Error && err.name === "AbortError") {
+				yield { type: "abort", reason: err };
+				return;
+			}
+			throw err;
+		}
+
+		if (!res.ok) {
+			const error = await GeminiError.fromResponse(res);
+			yield { type: "error", error, recoverable: false };
+			return;
+		}
+
+		if (!res.body) {
+			yield {
+				type: "error",
+				error: new Error("gemini stream: empty response body"),
+				recoverable: false,
+			};
+			return;
+		}
+
+		const meta: ResponseMeta = { providerName, modelId, startedAt };
+		yield { type: "response-start", meta };
+		yield { type: "message-start", role: "assistant" };
+
+		// Accumulation state
+		const textParts: string[] = [];
+		const reasoningParts: string[] = [];
+		const toolCalls: Array<{
+			id: string;
+			name: string;
+			args: Record<string, unknown>;
+		}> = [];
+		let finishReason: FinishReason = "stop";
+		let usage: Usage = { inputTokens: 0, outputTokens: 0 };
+
+		try {
+			for await (const frame of parseSSE(res.body)) {
+				if (rawChunks) {
+					yield { type: "raw-chunk", providerName, data: frame.data };
+				}
+
+				let chunk: any;
+				try {
+					chunk = JSON.parse(frame.data);
+				} catch {
+					continue;
+				}
+
+				// Usage metadata
+				if (chunk.usageMetadata) {
+					const u = chunk.usageMetadata as Record<string, unknown>;
+					usage = {
+						inputTokens: (u.promptTokenCount as number) ?? 0,
+						outputTokens: (u.candidatesTokenCount as number) ?? 0,
+						totalTokens: (u.totalTokenCount as number) ?? undefined,
+						...(u.cachedContentTokenCount !== undefined
+							? {
+									cachedInputTokens:
+										u.cachedContentTokenCount as number,
+								}
+							: {}),
+						...(u.thoughtsTokenCount !== undefined
+							? {
+									reasoningTokens:
+										u.thoughtsTokenCount as number,
+								}
+							: {}),
+					};
+				}
+
+				// Candidates
+				const candidates = chunk.candidates as
+					| Array<{
+							content?: { parts?: Array<Record<string, unknown>> };
+							finishReason?: string;
+					  }>
+					| undefined;
+				if (!candidates?.length) continue;
+
+				const candidate = candidates[0]!;
+				if (candidate.finishReason) {
+					finishReason = mapFinishReason(candidate.finishReason);
+				}
+
+				const parts = candidate.content?.parts;
+				if (!parts) continue;
+
+				for (const part of parts) {
+					// Text
+					if (part.text && typeof part.text === "string") {
+						// Check if this is a "thought" part
+						if (part.thought === true) {
+							reasoningParts.push(part.text as string);
+							yield {
+								type: "reasoning-delta",
+								delta: part.text as string,
+							};
+						} else {
+							textParts.push(part.text as string);
+							yield {
+								type: "text-delta",
+								delta: part.text as string,
+							};
+						}
+					}
+
+					// Function call
+					if (part.functionCall) {
+						const fc = part.functionCall as {
+							name: string;
+							args: Record<string, unknown>;
+						};
+						const callId = `call_${toolCalls.length}`;
+						toolCalls.push({
+							id: callId,
+							name: fc.name,
+							args: fc.args ?? {},
+						});
+						yield {
+							type: "tool-call-delta",
+							toolCallId: callId,
+							toolName: fc.name,
+							inputDelta: JSON.stringify(fc.args ?? {}),
+						};
+						yield {
+							type: "tool-call",
+							toolCallId: callId,
+							toolName: fc.name,
+							input: fc.args ?? {},
+						};
+					}
+				}
+			}
+		} catch (err: unknown) {
+			if (err instanceof Error && err.name === "AbortError") {
+				yield { type: "abort", reason: err };
+				return;
+			}
+			yield { type: "error", error: err, recoverable: false };
+			return;
+		}
+
+		// Detect tool-calls finish reason
+		if (toolCalls.length > 0 && finishReason === "stop") {
+			finishReason = "tool-calls";
+		}
+
+		// Assemble final message
+		const contentParts: Content[] = [];
+		if (reasoningParts.length > 0) {
+			contentParts.push({
+				type: "reasoning",
+				text: reasoningParts.join(""),
+			});
+		}
+		if (textParts.length > 0) {
+			contentParts.push({ type: "text", text: textParts.join("") });
+		}
+		for (const tc of toolCalls) {
+			contentParts.push({
+				type: "tool-call",
+				toolCallId: tc.id,
+				toolName: tc.name,
+				input: tc.args,
+			});
+		}
+
+		const message: Message = { role: "assistant", content: contentParts };
+		yield { type: "message-stop", message };
+		yield { type: "finish", reason: finishReason, usage };
+		yield {
+			type: "response-stop",
+			meta: { ...meta, endedAt: Date.now() },
+			usage,
+			finishReason,
+		};
+	};
+}

package/src/thinking.ts

@@ -0,0 +1,36 @@
+/** ThinkingLevel → Gemini thinkingConfig mapping. */
+
+import type { ThinkingLevel } from "@dex-ai/sdk";
+
+export interface GeminiThinkingConfig {
+	thinkingBudget: number;
+}
+
+/**
+ * Map SDK ThinkingLevel to Gemini's thinkingConfig.
+ * Returns undefined when thinking is disabled.
+ */
+export function thinkingToGeminiConfig(
+	thinking: ThinkingLevel | { readonly budgetTokens: number } | undefined,
+	maxTokens?: number,
+): GeminiThinkingConfig | undefined {
+	if (thinking === undefined || thinking === "off") return undefined;
+
+	if (typeof thinking === "object" && "budgetTokens" in thinking) {
+		if (thinking.budgetTokens <= 0) return undefined;
+		return { thinkingBudget: thinking.budgetTokens };
+	}
+
+	const effective = maxTokens ?? 8192;
+	const pct: Record<ThinkingLevel, number> = {
+		off: 0,
+		min: 0.1,
+		low: 0.25,
+		med: 0.5,
+		high: 0.75,
+		max: 1.0,
+	};
+	const budget = Math.round(effective * (pct[thinking] ?? 0.5));
+	if (budget <= 0) return undefined;
+	return { thinkingBudget: budget };
+}

package/src/translate.ts

@@ -0,0 +1,204 @@
+/**
+ * Translate SDK types ↔ Google Gemini API wire format.
+ */
+
+import type {
+	Content,
+	Message,
+	ToolChoice,
+	ToolOutput,
+	AnyTool,
+} from "@dex-ai/sdk";
+import { resolveJsonSchema } from "@dex-ai/sdk";
+
+/* ------------------------------------------------------------------ */
+/* Gemini wire types                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface GeminiPart {
+	text?: string;
+	inlineData?: { mimeType: string; data: string };
+	functionCall?: { name: string; args: Record<string, unknown> };
+	functionResponse?: { name: string; response: unknown };
+}
+
+export interface GeminiContent {
+	role: "user" | "model";
+	parts: GeminiPart[];
+}
+
+export interface GeminiFunctionDeclaration {
+	name: string;
+	description?: string;
+	parameters?: unknown;
+}
+
+export interface GeminiTool {
+	functionDeclarations: GeminiFunctionDeclaration[];
+}
+
+export type GeminiToolConfig =
+	| { functionCallingConfig: { mode: "AUTO" | "ANY" | "NONE" } }
+	| { functionCallingConfig: { mode: "ANY"; allowedFunctionNames: string[] } };
+
+/* ------------------------------------------------------------------ */
+/* SDK Message[] → Gemini contents[]                                   */
+/* ------------------------------------------------------------------ */
+
+function toolOutputToString(output: ToolOutput): unknown {
+	switch (output.type) {
+		case "text":
+		case "error-text":
+			return { result: output.value };
+		case "json":
+		case "error-json":
+			return typeof output.value === "object" && output.value !== null
+				? output.value
+				: { result: output.value };
+		case "content":
+			return {
+				result: output.value
+					.filter((p) => p.type === "text")
+					.map((p) => (p as { type: "text"; text: string }).text)
+					.join("\n"),
+			};
+		default:
+			return { result: "" };
+	}
+}
+
+export function messagesToGemini(messages: ReadonlyArray<Message>): {
+	systemInstruction: string | undefined;
+	contents: GeminiContent[];
+} {
+	let systemInstruction: string | undefined;
+	const contents: GeminiContent[] = [];
+
+	for (const m of messages) {
+		if (m.role === "system") {
+			const text = m.content
+				.filter((c) => c.type === "text")
+				.map((c) => (c as { text: string }).text)
+				.join("\n");
+			systemInstruction = systemInstruction
+				? systemInstruction + "\n" + text
+				: text;
+			continue;
+		}
+
+		// Map roles: assistant → model, user/tool → user
+		const role: "user" | "model" = m.role === "assistant" ? "model" : "user";
+		const parts: GeminiPart[] = [];
+
+		for (const c of m.content) {
+			switch (c.type) {
+				case "text":
+					parts.push({ text: c.text });
+					break;
+				case "image": {
+					let b64: string;
+					let mimeType = c.mediaType ?? "image/png";
+					if (c.image instanceof URL) {
+						// Gemini doesn't support URL images in REST; skip
+						parts.push({ text: `[image: ${c.image.href}]` });
+						break;
+					} else if (typeof c.image === "string") {
+						if (c.image.startsWith("data:")) {
+							const [header, data] = c.image.split(",");
+							mimeType = header?.match(/data:([^;]+)/)?.[1] ?? mimeType;
+							b64 = data ?? c.image;
+						} else {
+							b64 = c.image;
+						}
+					} else {
+						b64 = Buffer.from(c.image).toString("base64");
+					}
+					parts.push({ inlineData: { mimeType, data: b64 } });
+					break;
+				}
+				case "tool-call":
+					parts.push({
+						functionCall: {
+							name: c.toolName,
+							args:
+								typeof c.input === "object" && c.input !== null
+									? (c.input as Record<string, unknown>)
+									: {},
+						},
+					});
+					break;
+				case "tool-result":
+					parts.push({
+						functionResponse: {
+							name: c.toolName,
+							response: toolOutputToString(c.output),
+						},
+					});
+					break;
+				case "file":
+					parts.push({
+						text: `[file: ${c.name ?? "untitled"} (${c.mediaType})]`,
+					});
+					break;
+				case "reasoning":
+					// Skip — Gemini handles thinking internally
+					break;
+			}
+		}
+
+		if (parts.length === 0) continue;
+
+		// Gemini requires alternating user/model. Merge consecutive same-role.
+		const last = contents[contents.length - 1];
+		if (last && last.role === role) {
+			last.parts.push(...parts);
+		} else {
+			contents.push({ role, parts });
+		}
+	}
+
+	return { systemInstruction, contents };
+}
+
+/* ------------------------------------------------------------------ */
+/* SDK Tool → Gemini tool                                              */
+/* ------------------------------------------------------------------ */
+
+export function toolsToGemini(tools: ReadonlyArray<AnyTool>): GeminiTool {
+	const declarations: GeminiFunctionDeclaration[] = tools.map((tool) => {
+		const schema = tool.parameters;
+		const parameters = schema ? resolveJsonSchema(schema) : undefined;
+
+		return {
+			name: tool.name,
+			...(tool.description !== undefined
+				? { description: tool.description }
+				: {}),
+			...(parameters !== undefined ? { parameters } : {}),
+		};
+	});
+
+	return { functionDeclarations: declarations };
+}
+
+/* ------------------------------------------------------------------ */
+/* SDK ToolChoice → Gemini toolConfig                                   */
+/* ------------------------------------------------------------------ */
+
+export function toolChoiceToGemini(
+	choice: ToolChoice | undefined,
+): GeminiToolConfig | undefined {
+	if (choice === undefined || choice === "auto")
+		return { functionCallingConfig: { mode: "AUTO" } };
+	if (choice === "required") return { functionCallingConfig: { mode: "ANY" } };
+	if (choice === "none") return { functionCallingConfig: { mode: "NONE" } };
+	if (typeof choice === "object" && "toolName" in choice) {
+		return {
+			functionCallingConfig: {
+				mode: "ANY",
+				allowedFunctionNames: [choice.toolName],
+			},
+		};
+	}
+	return undefined;
+}