@dex-ai/anthropic 0.1.6

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dex-ai/anthropic",
+  "version": "0.1.6",
+  "description": "Anthropic Messages 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,48 @@
+/** Anthropic-specific error class. */
+
+export class AnthropicError extends Error {
+	readonly status: number;
+	readonly code: string | null;
+	readonly type: string | null;
+
+	constructor(
+		status: number,
+		code: string | null,
+		type: string | null,
+		message: string,
+	) {
+		super(message);
+		this.name = "AnthropicError";
+		this.status = status;
+		this.code = code;
+		this.type = type;
+	}
+
+	static async fromResponse(res: Response): Promise<AnthropicError> {
+		let body: string;
+		try {
+			body = await res.text();
+		} catch {
+			body = "";
+		}
+
+		let code: string | null = null;
+		let type: string | null = null;
+		let message = `${res.status} ${res.statusText}`;
+
+		try {
+			const json = JSON.parse(body) as {
+				error?: { message?: string; type?: string };
+				type?: string;
+			};
+			if (json.error) {
+				message = json.error.message ?? message;
+				type = json.error.type ?? json.type ?? null;
+			}
+		} catch {
+			if (body) message += ` — ${body.slice(0, 200)}`;
+		}
+
+		return new AnthropicError(res.status, code, type, message);
+	}
+}

package/src/extension.ts

@@ -0,0 +1,213 @@
+/**
+ * Anthropic Extension — provides models via the Messages API.
+ */
+
+import type {
+	Extension,
+	Model,
+	StreamPart,
+	ModelRequest,
+	ThinkingLevel,
+} from "@dex-ai/sdk";
+import { createAnthropicStream } from "./stream";
+
+/* ------------------------------------------------------------------ */
+/* Options                                                             */
+/* ------------------------------------------------------------------ */
+
+export interface AnthropicExtensionOptions {
+	/** API key. Falls back to ANTHROPIC_API_KEY. */
+	readonly apiKey?: string;
+	/** Base URL (without trailing slash). Falls back to ANTHROPIC_BASE_URL → https://api.anthropic.com */
+	readonly baseUrl?: string;
+	/** Extension name (used as provider name in Agent.create). Default: "anthropic". */
+	readonly name?: string;
+	/** Model IDs to register statically. Discovered models are added alongside these. */
+	readonly models?: ReadonlyArray<string | ModelConfig>;
+	/** Messages endpoint path appended to baseUrl. Default: "/v1/messages". */
+	readonly messagesPath?: string;
+	/**
+	 * Models endpoint path for discovery.
+	 * Default: "/v1/models". Set to null to disable discovery.
+	 */
+	readonly modelsPath?: string | null;
+	/** Anthropic API version header. Default: "2023-06-01". */
+	readonly anthropicVersion?: string;
+	/** Emit raw-chunk parts during streaming. Default: false. */
+	readonly rawChunks?: boolean;
+	/** Additional headers sent with every request. */
+	readonly headers?: Record<string, string>;
+	/** Fetch override (for retry wrappers, testing). */
+	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: AnthropicExtensionOptions): string {
+	const raw =
+		opts.baseUrl ||
+		process.env.ANTHROPIC_BASE_URL ||
+		"https://api.anthropic.com";
+	return raw.replace(/\/+$/, "");
+}
+
+function resolveApiKey(opts: AnthropicExtensionOptions): string {
+	const key =
+		opts.apiKey ||
+		process.env.ANTHROPIC_API_KEY;
+	if (!key) {
+		throw new Error(
+			"@dex-ai/anthropic: no API key found. Set apiKey or ANTHROPIC_API_KEY.",
+		);
+	}
+	return key;
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                   */
+/* ------------------------------------------------------------------ */
+
+export function anthropicExtension(
+	opts: AnthropicExtensionOptions = {},
+): Extension {
+	const extName = opts.name ?? "anthropic";
+	const baseUrl = resolveBaseUrl(opts);
+	const apiKey = resolveApiKey(opts);
+	const rawChunks = opts.rawChunks ?? false;
+	const messagesPath = opts.messagesPath ?? "/v1/messages";
+	const anthropicVersion = opts.anthropicVersion ?? "2023-06-01";
+	const doFetch =
+		opts.fetch ?? ((url: string, init: RequestInit) => fetch(url, init));
+
+	function createStreamFn(
+		modelId: string,
+		modelMaxTokens?: number,
+	): (req: ModelRequest) => AsyncIterable<StreamPart> {
+		return createAnthropicStream(
+			{
+				baseUrl,
+				apiKey,
+				modelId,
+				providerName: extName,
+				rawChunks,
+				messagesPath,
+				anthropicVersion,
+				doFetch,
+				...(opts.headers !== undefined ? { headers: opts.headers } : {}),
+			},
+			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 ?? "/v1/models") : null;
+			if (!modelsPath) return;
+
+			try {
+				const modelsUrl = modelsPath.startsWith("http")
+					? modelsPath
+					: `${baseUrl}${modelsPath}`;
+
+				const res = await doFetch(modelsUrl, {
+					method: "GET",
+					headers: {
+						"x-api-key": apiKey,
+						"anthropic-version": anthropicVersion,
+						...(opts.headers !== undefined ? opts.headers : {}),
+					},
+				});
+				if (!res.ok) return; // silently skip if discovery fails
+
+				const json = (await res.json()) as any;
+				const modelList: Array<{
+					id: string;
+					display_name?: string;
+					max_tokens?: number;
+					max_input_tokens?: number;
+					capabilities?: {
+						thinking?: { supported?: boolean };
+						image_input?: { supported?: boolean };
+					};
+				}> = json.data ?? (Array.isArray(json) ? json : []);
+
+				// Add discovered models not already statically configured
+				const staticIds = new Set(staticModels.map((m) => m.id));
+				for (const m of modelList) {
+					if (!m.id || staticIds.has(m.id)) continue;
+
+					const hasThinking = m.capabilities?.thinking?.supported ?? false;
+					const hasImage = m.capabilities?.image_input?.supported ?? false;
+					const inputModes: ("text" | "image")[] = hasImage
+						? ["text", "image"]
+						: ["text"];
+
+					allModels.push({
+						id: m.id,
+						...(m.display_name ? { name: m.display_name } : {}),
+						...(m.max_input_tokens
+							? { contextWindow: m.max_input_tokens }
+							: {}),
+						...(m.max_tokens ? { maxTokens: m.max_tokens } : {}),
+						reasoning: hasThinking,
+						...(hasThinking
+							? {
+									thinkingLevels: [
+										"off",
+										"min",
+										"low",
+										"med",
+										"high",
+										"max",
+									] as ThinkingLevel[],
+								}
+							: {}),
+						input: inputModes,
+						stream: createStreamFn(m.id, m.max_tokens),
+					});
+				}
+			} catch {
+				// Discovery failed — proceed with static models only
+			}
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { anthropicExtension } from "./extension";
+export type { AnthropicExtensionOptions, ModelConfig } from "./extension";
+
+import type { ProviderDescriptor } from "@dex-ai/sdk";
+import { anthropicExtension } from "./extension";
+
+export const descriptor: ProviderDescriptor = {
+	type: "anthropic",
+	label: "Anthropic",
+	fields: [
+		{ key: "apiKey", label: "API Key", required: true, secret: true, envVar: "ANTHROPIC_API_KEY", hint: "sk-ant-... (or press Enter to use ANTHROPIC_API_KEY env var)" },
+		{ key: "baseUrl", label: "Base URL", required: false, default: "https://api.anthropic.com", hint: "Custom endpoint for proxies" },
+		{ 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 anthropicExtension({
+			...(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,35 @@
+/** 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) };
+				}
+				// ignore comments / other fields
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}

package/src/stream.ts

@@ -0,0 +1,382 @@
+/**
+ * Anthropic Messages API streaming: POST /v1/messages → StreamPart async iterable.
+ */
+
+import type {
+	StreamPart,
+	ModelRequest,
+	FinishReason,
+	Usage,
+	ResponseMeta,
+	Content,
+	Message,
+} from "@dex-ai/sdk";
+import { parseSSE } from "./sse";
+import { AnthropicError } from "./errors";
+import {
+	messagesToAnthropic,
+	toolToAnthropic,
+	toolChoiceToAnthropic,
+} from "./translate";
+import { thinkingToAnthropicConfig } from "./thinking";
+
+/* ------------------------------------------------------------------ */
+/* Types                                                               */
+/* ------------------------------------------------------------------ */
+
+interface ToolBlockAccumulator {
+	id: string;
+	name: string;
+	inputJson: string;
+}
+
+interface StreamOptions {
+	baseUrl: string;
+	apiKey: string;
+	modelId: string;
+	providerName: string;
+	rawChunks: boolean;
+	messagesPath: string;
+	anthropicVersion: string;
+	doFetch: (url: string, init: RequestInit) => Promise<Response>;
+	headers?: Record<string, string> | undefined;
+}
+
+/* ------------------------------------------------------------------ */
+/* FinishReason mapping                                                */
+/* ------------------------------------------------------------------ */
+
+function mapStopReason(reason: string | undefined | null): FinishReason {
+	switch (reason) {
+		case "end_turn":
+			return "stop";
+		case "tool_use":
+			return "tool-calls";
+		case "max_tokens":
+			return "length";
+		case "stop_sequence":
+			return "stop";
+		default:
+			return "stop";
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* createAnthropicStream                                               */
+/* ------------------------------------------------------------------ */
+
+export function createAnthropicStream(
+	opts: StreamOptions,
+	modelMaxTokens?: number,
+): (req: ModelRequest) => AsyncIterable<StreamPart> {
+	const {
+		baseUrl,
+		apiKey,
+		modelId,
+		providerName,
+		rawChunks,
+		messagesPath,
+		anthropicVersion,
+		doFetch,
+	} = opts;
+	const url = `${baseUrl}${messagesPath}`;
+
+	return async function* stream(req: ModelRequest): AsyncIterable<StreamPart> {
+		const startedAt = Date.now();
+
+		// Build Anthropic request body
+		const { system, messages } = messagesToAnthropic(req.messages, {
+			...(req.cacheBreakpoints
+				? { cacheBreakpoints: req.cacheBreakpoints }
+				: {}),
+		});
+		const body: Record<string, unknown> = {
+			model: modelId,
+			messages,
+			max_tokens: req.maxTokens ?? modelMaxTokens ?? 8192,
+			stream: true,
+		};
+
+		if (system.length > 0) body.system = system;
+		if (req.temperature !== undefined) body.temperature = req.temperature;
+		if (req.topP !== undefined) body.top_p = req.topP;
+		if (req.stopSequences?.length) body.stop_sequences = req.stopSequences;
+
+		// Tools
+		if (req.tools?.length) {
+			const tools = req.tools.map(toolToAnthropic);
+			// Cache breakpoint on last tool — caches entire system+tools prefix
+			if (tools.length > 0) {
+				tools[tools.length - 1] = {
+					...tools[tools.length - 1]!,
+					cache_control: { type: "ephemeral" },
+				};
+			}
+			body.tools = tools;
+			const tc = toolChoiceToAnthropic(req.toolChoice);
+			if (tc !== undefined) body.tool_choice = tc;
+		}
+
+		// Extended thinking
+		const thinkingConfig = thinkingToAnthropicConfig(
+			req.thinking,
+			modelMaxTokens,
+		);
+		if (thinkingConfig) {
+			body.thinking = thinkingConfig;
+		}
+
+		// Provider options pass-through
+		if (req.providerOptions) Object.assign(body, req.providerOptions);
+
+		const init: RequestInit = {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"x-api-key": apiKey,
+				"anthropic-version": anthropicVersion,
+				...opts.headers,
+			},
+			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 AnthropicError.fromResponse(res);
+			yield { type: "error", error, recoverable: false };
+			return;
+		}
+
+		if (!res.body) {
+			yield {
+				type: "error",
+				error: new Error("anthropic 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 toolBlocks: Map<number, ToolBlockAccumulator> = new Map();
+		const usage: {
+			inputTokens: number;
+			outputTokens: number;
+			cachedInputTokens?: number;
+			cacheCreationInputTokens?: number;
+		} = {
+			inputTokens: 0,
+			outputTokens: 0,
+		};
+		let finishReason: FinishReason = "stop";
+		let currentBlockIdx = -1;
+		let responseId: string | undefined;
+
+		try {
+			for await (const frame of parseSSE(res.body)) {
+				if (rawChunks) {
+					yield { type: "raw-chunk", providerName, data: frame.data };
+				}
+
+				let event: any;
+				try {
+					event = JSON.parse(frame.data);
+				} catch {
+					continue;
+				}
+
+				const eventType = event.type as string | undefined;
+
+				switch (eventType) {
+					case "message_start": {
+						if (event.message?.id) responseId = event.message.id as string;
+						if (event.message?.usage) {
+							const u = event.message.usage as Record<string, unknown>;
+							usage.inputTokens = (u.input_tokens as number) ?? 0;
+							if (u.cache_read_input_tokens !== undefined) {
+								usage.cachedInputTokens = u.cache_read_input_tokens as number;
+							}
+							if (u.cache_creation_input_tokens !== undefined) {
+								usage.cacheCreationInputTokens =
+									u.cache_creation_input_tokens as number;
+							}
+						}
+						break;
+					}
+
+					case "content_block_start": {
+						currentBlockIdx = (event.index as number) ?? 0;
+						const block = event.content_block as
+							| { type: string; id?: string; name?: string }
+							| undefined;
+						if (block?.type === "tool_use") {
+							toolBlocks.set(currentBlockIdx, {
+								id: block.id ?? "",
+								name: block.name ?? "",
+								inputJson: "",
+							});
+						}
+						break;
+					}
+
+					case "content_block_delta": {
+						const delta = event.delta as
+							| {
+									type: string;
+									text?: string;
+									thinking?: string;
+									partial_json?: string;
+							  }
+							| undefined;
+						if (!delta) break;
+
+						if (delta.type === "text_delta" && delta.text) {
+							textParts.push(delta.text);
+							yield { type: "text-delta", delta: delta.text };
+						} else if (delta.type === "thinking_delta" && delta.thinking) {
+							reasoningParts.push(delta.thinking);
+							yield { type: "reasoning-delta", delta: delta.thinking };
+						} else if (
+							delta.type === "input_json_delta" &&
+							delta.partial_json !== undefined
+						) {
+							const idx = (event.index as number) ?? currentBlockIdx;
+							const tool = toolBlocks.get(idx);
+							if (tool) {
+								tool.inputJson += delta.partial_json;
+								yield {
+									type: "tool-call-delta",
+									toolCallId: tool.id,
+									toolName: tool.name,
+									inputDelta: delta.partial_json,
+								};
+							}
+						}
+						break;
+					}
+
+					case "content_block_stop": {
+						const idx = (event.index as number) ?? currentBlockIdx;
+						const tool = toolBlocks.get(idx);
+						if (tool) {
+							let input: unknown = {};
+							try {
+								input = tool.inputJson ? JSON.parse(tool.inputJson) : {};
+							} catch {
+								input = tool.inputJson;
+							}
+							yield {
+								type: "tool-call",
+								toolCallId: tool.id,
+								toolName: tool.name,
+								input,
+							};
+						}
+						break;
+					}
+
+					case "message_delta": {
+						const d = event.delta as { stop_reason?: string } | undefined;
+						if (d?.stop_reason) {
+							finishReason = mapStopReason(d.stop_reason);
+						}
+						const u = event.usage as { output_tokens?: number } | undefined;
+						if (u?.output_tokens !== undefined) {
+							usage.outputTokens = u.output_tokens;
+						}
+						break;
+					}
+
+					case "message_stop": {
+						// End of stream
+						break;
+					}
+
+					case "error": {
+						const errMsg =
+							(event.error as { message?: string })?.message ??
+							JSON.stringify(event);
+						yield { type: "error", error: new Error(errMsg) };
+						break;
+					}
+
+					default:
+						// ping, unknown events — ignore
+						break;
+				}
+			}
+		} catch (err: unknown) {
+			if (err instanceof Error && err.name === "AbortError") {
+				yield { type: "abort", reason: err };
+				return;
+			}
+			yield { type: "error", error: err, recoverable: false };
+			return;
+		}
+
+		// 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 [, tool] of toolBlocks) {
+			let input: unknown = {};
+			try {
+				input = tool.inputJson ? JSON.parse(tool.inputJson) : {};
+			} catch {
+				input = tool.inputJson;
+			}
+			contentParts.push({
+				type: "tool-call",
+				toolCallId: tool.id,
+				toolName: tool.name,
+				input,
+			});
+		}
+
+		const finalUsage: Usage = {
+			inputTokens: usage.inputTokens,
+			outputTokens: usage.outputTokens,
+			totalTokens: usage.inputTokens + usage.outputTokens,
+			...(usage.cachedInputTokens !== undefined
+				? { cachedInputTokens: usage.cachedInputTokens }
+				: {}),
+			...(usage.cacheCreationInputTokens !== undefined
+				? { cacheCreationInputTokens: usage.cacheCreationInputTokens }
+				: {}),
+		};
+
+		const message: Message = { role: "assistant", content: contentParts };
+		yield { type: "message-stop", message };
+		yield { type: "finish", reason: finishReason, usage: finalUsage };
+		yield {
+			type: "response-stop",
+			meta: {
+				...meta,
+				...(responseId !== undefined ? { id: responseId } : {}),
+				endedAt: Date.now(),
+			},
+			usage: finalUsage,
+			finishReason,
+		};
+	};
+}

package/src/thinking.ts

@@ -0,0 +1,37 @@
+/** ThinkingLevel → Anthropic thinking config. */
+
+import type { ThinkingLevel } from "@dex-ai/sdk";
+
+export interface AnthropicThinkingConfig {
+	type: "enabled";
+	budget_tokens: number;
+}
+
+/**
+ * Map SDK ThinkingLevel to Anthropic's thinking config object.
+ * Returns undefined when thinking is disabled (field should be omitted).
+ */
+export function thinkingToAnthropicConfig(
+	thinking: ThinkingLevel | { readonly budgetTokens: number } | undefined,
+	maxTokens?: number,
+): AnthropicThinkingConfig | undefined {
+	if (thinking === undefined || thinking === "off") return undefined;
+
+	if (typeof thinking === "object" && "budgetTokens" in thinking) {
+		if (thinking.budgetTokens <= 0) return undefined;
+		return { type: "enabled", budget_tokens: thinking.budgetTokens };
+	}
+
+	const effective = maxTokens ?? 16384;
+	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 { type: "enabled", budget_tokens: budget };
+}

package/src/translate.ts

@@ -0,0 +1,290 @@
+/**
+ * Translate SDK types ↔ Anthropic Messages API wire format.
+ */
+
+import type {
+	Content,
+	Message,
+	ToolChoice,
+	ToolOutput,
+	AnyTool,
+} from "@dex-ai/sdk";
+import { resolveJsonSchema } from "@dex-ai/sdk";
+
+/* ------------------------------------------------------------------ */
+/* Anthropic wire types                                                */
+/* ------------------------------------------------------------------ */
+
+export type AnthropicCacheControl = { type: "ephemeral" };
+
+export type AnthropicContentBlock =
+	| { type: "text"; text: string; cache_control?: AnthropicCacheControl }
+	| {
+			type: "image";
+			source: { type: "base64"; media_type: string; data: string };
+			cache_control?: AnthropicCacheControl;
+	  }
+	| { type: "tool_use"; id: string; name: string; input: unknown }
+	| {
+			type: "tool_result";
+			tool_use_id: string;
+			content: string;
+			is_error?: boolean;
+	  };
+
+export type AnthropicSystemBlock = {
+	type: "text";
+	text: string;
+	cache_control?: AnthropicCacheControl;
+};
+
+export interface AnthropicMessage {
+	role: "user" | "assistant";
+	content: AnthropicContentBlock[];
+}
+
+export interface AnthropicTool {
+	name: string;
+	description: string | undefined;
+	input_schema: unknown;
+	cache_control?: AnthropicCacheControl;
+}
+
+export type AnthropicToolChoice =
+	| { type: "auto" }
+	| { type: "any" }
+	| { type: "none" }
+	| { type: "tool"; name: string };
+
+/* ------------------------------------------------------------------ */
+/* SDK Content → Anthropic content block                               */
+/* ------------------------------------------------------------------ */
+
+function contentToAnthropic(c: Content): AnthropicContentBlock | null {
+	switch (c.type) {
+		case "text": {
+			const cc = (c as { cacheControl?: { type: string } }).cacheControl;
+			return {
+				type: "text",
+				text: c.text,
+				...(cc ? { cache_control: { type: "ephemeral" as const } } : {}),
+			};
+		}
+		case "image": {
+			let b64: string;
+			if (c.image instanceof URL) {
+				// URLs not directly supported — would need to download
+				// For now, treat as empty placeholder
+				b64 = "";
+			} else if (typeof c.image === "string") {
+				b64 = c.image.startsWith("data:")
+					? (c.image.split(",")[1] ?? c.image)
+					: c.image;
+			} else {
+				// c.image is typed as Uint8Array, but after JSON round-trip (session
+				// resume) it may be a plain object: {0: 72, 1: 101, ...} or
+				// {type: "Buffer", data: [...]}. Handle both cases.
+				const raw = c.image as unknown;
+				let buf: Buffer;
+				if (
+					ArrayBuffer.isView(raw) ||
+					raw instanceof ArrayBuffer ||
+					Array.isArray(raw)
+				) {
+					buf = Buffer.from(raw as any);
+				} else if (
+					typeof raw === "object" &&
+					raw !== null &&
+					"type" in raw &&
+					(raw as any).type === "Buffer" &&
+					Array.isArray((raw as any).data)
+				) {
+					// Deserialized Node Buffer: {type: "Buffer", data: [...]}
+					buf = Buffer.from((raw as any).data);
+				} else if (typeof raw === "object" && raw !== null) {
+					// Deserialized Uint8Array: plain object with numeric keys
+					const values = Object.values(raw as Record<string, number>);
+					buf = Buffer.from(values);
+				} else {
+					buf = Buffer.from(raw as any);
+				}
+				b64 = buf.toString("base64");
+			}
+			return {
+				type: "image",
+				source: {
+					type: "base64",
+					media_type: c.mediaType ?? "image/png",
+					data: b64,
+				},
+			};
+		}
+		case "tool-call":
+			return {
+				type: "tool_use",
+				id: c.toolCallId,
+				name: c.toolName,
+				input: c.input ?? {},
+			};
+		case "tool-result": {
+			const text = toolOutputToString(c.output);
+			const isError =
+				c.output.type === "error-text" || c.output.type === "error-json";
+			return {
+				type: "tool_result",
+				tool_use_id: c.toolCallId,
+				content: text,
+				...(isError ? { is_error: true } : {}),
+			};
+		}
+		case "file": {
+			const label = c.name ?? "untitled";
+			return { type: "text", text: `[file: ${label} (${c.mediaType})]` };
+		}
+		case "reasoning":
+			// Skip reasoning in outbound messages — Anthropic handles it internally
+			return null;
+		default:
+			return null;
+	}
+}
+
+function toolOutputToString(output: ToolOutput): string {
+	switch (output.type) {
+		case "text":
+		case "error-text":
+			return typeof output.value === "string"
+				? output.value
+				: JSON.stringify(output.value);
+		case "json":
+		case "error-json":
+			return JSON.stringify(output.value);
+		case "content": {
+			return output.value
+				.filter((p) => p.type === "text")
+				.map((p) => (p as { type: "text"; text: string }).text)
+				.join("\n");
+		}
+		default:
+			return "";
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* SDK Message[] → Anthropic { system, messages }                      */
+/* ------------------------------------------------------------------ */
+
+export function messagesToAnthropic(
+	messages: ReadonlyArray<Message>,
+	opts?: { cacheBreakpoints?: ReadonlyArray<number> },
+): {
+	system: AnthropicSystemBlock[];
+	messages: AnthropicMessage[];
+} {
+	const systemBlocks: AnthropicSystemBlock[] = [];
+	const out: AnthropicMessage[] = [];
+
+	// Track which SDK message index maps to which output message index.
+	// Needed to apply cacheBreakpoints to the correct output position.
+	const sdkIdxToOutIdx: number[] = []; // sdkIdxToOutIdx[sdkIdx] = outIdx
+
+	for (let sdkIdx = 0; sdkIdx < messages.length; sdkIdx++) {
+		const m = messages[sdkIdx]!;
+
+		if (m.role === "system") {
+			// Collect system messages into system blocks array
+			for (const c of m.content) {
+				if (c.type !== "text") continue;
+				const block: AnthropicSystemBlock = {
+					type: "text",
+					text: c.text,
+					...((c as { cacheControl?: { type: string } }).cacheControl
+						? { cache_control: { type: "ephemeral" as const } }
+						: {}),
+				};
+				systemBlocks.push(block);
+			}
+			sdkIdxToOutIdx.push(-1); // system messages don't map to out
+			continue;
+		}
+
+		// Map role: tool → user (tool_result goes inside user turn)
+		const role: "user" | "assistant" =
+			m.role === "assistant" ? "assistant" : "user";
+
+		// Convert content
+		const blocks: AnthropicContentBlock[] = [];
+		for (const c of m.content) {
+			const block = contentToAnthropic(c);
+			if (block) blocks.push(block);
+		}
+
+		if (blocks.length === 0) {
+			sdkIdxToOutIdx.push(-1);
+			continue;
+		}
+
+		// Anthropic requires alternating user/assistant. Merge consecutive same-role.
+		const last = out[out.length - 1];
+		if (last && last.role === role) {
+			last.content.push(...blocks);
+			sdkIdxToOutIdx.push(out.length - 1); // merged into existing
+		} else {
+			sdkIdxToOutIdx.push(out.length);
+			out.push({ role, content: blocks });
+		}
+	}
+
+	// Apply cache breakpoints to the last content block of marked messages
+	if (opts?.cacheBreakpoints && opts.cacheBreakpoints.length > 0) {
+		for (const breakIdx of opts.cacheBreakpoints) {
+			if (breakIdx < 0 || breakIdx >= sdkIdxToOutIdx.length) continue;
+			const outIdx = sdkIdxToOutIdx[breakIdx]!;
+			if (outIdx < 0) continue;
+			const msg = out[outIdx];
+			if (!msg || msg.content.length === 0) continue;
+
+			const lastBlock = msg.content[msg.content.length - 1]!;
+			msg.content[msg.content.length - 1] = {
+				...lastBlock,
+				cache_control: { type: "ephemeral" },
+			} as AnthropicContentBlock;
+		}
+	}
+
+	return { system: systemBlocks, messages: out };
+}
+
+/* ------------------------------------------------------------------ */
+/* SDK Tool → Anthropic tool                                           */
+/* ------------------------------------------------------------------ */
+
+export function toolToAnthropic(tool: AnyTool): AnthropicTool {
+	const schema = tool.parameters;
+	const jsonSchema = schema
+		? resolveJsonSchema(schema)
+		: { type: "object", properties: {} };
+
+	return {
+		name: tool.name,
+		description: tool.description,
+		input_schema: jsonSchema,
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* SDK ToolChoice → Anthropic tool_choice                              */
+/* ------------------------------------------------------------------ */
+
+export function toolChoiceToAnthropic(
+	choice: ToolChoice | undefined,
+): AnthropicToolChoice | undefined {
+	if (choice === undefined) return undefined;
+	if (choice === "auto") return { type: "auto" };
+	if (choice === "required") return { type: "any" };
+	if (choice === "none") return { type: "none" };
+	if (typeof choice === "object" && "toolName" in choice) {
+		return { type: "tool", name: choice.toolName };
+	}
+	return undefined;
+}