@codehz/ai 0.8.0 → 0.8.2

package/dist/index.d.mts

@@ -127,6 +127,42 @@ type OutputItem = MessageItem | ReasoningItem | ToolCallItem | OpaqueItem | Serv
 /** replay 材料的类型等价于 InputItem */
 type ReplayItem = InputItem;
 //#endregion
+//#region src/types/cache.d.ts
+/** Request-level portable prompt cache controls and provider extensions. */
+type PromptCacheMode = "off" | "auto" | "explicit";
+type PromptCacheSettings = {
+  /** Cache strategy; when omitted, the adapter/provider decides. */mode?: PromptCacheMode; /** Session or tenant routing hint; providers may ignore it. */
+  key?: string; /** Provider-specific retention hint. */
+  ttl?: "short" | "long" | string;
+};
+type ProviderCacheOptions = {
+  responses?: {
+    promptCacheKey?: string;
+    promptCacheRetention?: "in_memory" | "24h";
+    promptCacheMode?: "implicit" | "explicit" | "off";
+  };
+  chatCompletions?: {
+    promptCacheKey?: string;
+    promptCacheRetention?: "in_memory" | "24h";
+  };
+  messages?: {
+    cacheTtl?: "5m" | "1h";
+    betaHeader?: string;
+  };
+  gemini?: {
+    cachedContent?: string;
+  };
+  ollama?: {
+    keepAlive?: string | number;
+  };
+};
+type PromptCacheMetadata = {
+  requestedMode: PromptCacheMode;
+  appliedMode: "off" | "implicit" | "explicit" | "unsupported";
+  keyApplied: boolean;
+  ttlApplied: boolean;
+};
+//#endregion
 //#region src/types/request.d.ts
 type ToolDefinition = {
   name: string;
@@ -197,7 +233,11 @@ type AIRequest = {
    * Messages `thinking`, Ollama `think`, Gemini `thinkingConfig`).
    * Unsupported levels throw.
    */
-  reasoningLevel?: ReasoningLevel; /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
+  reasoningLevel?: ReasoningLevel; /** Portable request-level prompt cache strategy and routing hint. */
+  cache?: PromptCacheSettings; /** Typed provider-native cache extensions; unsupported fields are ignored by other adapters. */
+  providerOptions?: {
+    cache?: ProviderCacheOptions;
+  }; /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
   signal?: AbortSignal;
 };
 //#endregion
@@ -691,7 +731,7 @@ declare class AdapterAuxiliaryState {
   constructor(request: NormalizedRequest);
   recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): void;
   recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): void;
-  recordProviderMetadata(source: string, metadata: Record<string, unknown> | undefined): void;
+  recordProviderMetadata(source: string | undefined, metadata: Record<string, unknown> | undefined): void;
   finalize(factory: EventFactory, options?: AuxiliaryFinalizeOptions): Promise<AuxiliaryFinalizeResult>;
   private shouldAttemptLookup;
 }
@@ -886,6 +926,11 @@ type ResponsesAPIRequest = {
     effort: string;
   }; /** 服务端多轮续写；opaque replay 的 response id 映射到此字段，而非 item_reference */
   previous_response_id?: string;
+  prompt_cache_key?: string;
+  prompt_cache_options?: {
+    mode?: "implicit" | "explicit" | "off";
+    retention?: "in_memory" | "24h";
+  };
   stream: true;
 };
 /** EasyInputMessage：content 可为 string，或 input_* content parts */
@@ -919,7 +964,7 @@ type ResponsesFunctionCall = {
 type ResponsesFunctionCallOutput = {
   type: "function_call_output";
   call_id: string;
-  output: string;
+  output: string | ResponsesInputContentPart[];
   id?: string;
   status?: "in_progress" | "completed" | "incomplete";
 };
@@ -1025,7 +1070,7 @@ type MessagesAPIRequest = {
   model: string;
   max_tokens: number;
   messages: MessagesAPIMessage[];
-  system?: string;
+  system?: string | MessagesAPIContentBlock[];
   tools?: MessagesAPITool[];
   tool_choice?: {
     type: "auto" | "none";
@@ -1055,34 +1100,45 @@ type MessagesAPIImageSource = {
   type: "url";
   url: string;
 };
+type MessagesCacheControl = {
+  type: "ephemeral";
+  ttl?: "5m" | "1h";
+};
 type MessagesAPIContentBlock = {
   type: "text";
   text: string;
+  cache_control?: MessagesCacheControl;
 } | {
   type: "image";
   source: MessagesAPIImageSource;
+  cache_control?: MessagesCacheControl;
 } | {
   type: "thinking";
   thinking: string;
   signature?: string;
+  cache_control?: MessagesCacheControl;
 } | {
   type: "redacted_thinking";
   data: string;
+  cache_control?: MessagesCacheControl;
 } | {
   type: "tool_use";
   id: string;
   name: string;
   input: Record<string, unknown>;
+  cache_control?: MessagesCacheControl;
 } | {
   type: "tool_result";
   tool_use_id: string;
   content: string | MessagesAPIContentBlock[];
   is_error?: boolean;
+  cache_control?: MessagesCacheControl;
 };
 type MessagesAPITool = {
   name: string;
   description?: string;
   input_schema: Record<string, unknown>;
+  cache_control?: MessagesCacheControl;
 };
 //#endregion
 //#region src/adapters/messages/adapter.d.ts
@@ -1114,6 +1170,8 @@ type ChatRequest = {
   temperature?: number;
   max_tokens?: number; /** Portable reasoningLevel → reasoning_effort */
   reasoning_effort?: string;
+  prompt_cache_key?: string;
+  prompt_cache_retention?: "in_memory" | "24h";
   stream: true;
   n: 1;
 };
@@ -1172,6 +1230,7 @@ type OllamaChatRequest = {
   model: string;
   messages: OllamaMessage[];
   stream: true;
+  keep_alive?: string | number;
   tools?: OllamaTool[]; /** Portable reasoningLevel → think；minimal/xhigh/max 不支持 */
   think?: boolean | "low" | "medium" | "high";
   options?: {
@@ -1253,6 +1312,7 @@ type GeminiFunctionCallingConfig = {
 };
 type GeminiGenerateContentRequest = {
   contents: GeminiContent[];
+  cachedContent?: string;
   systemInstruction?: {
     parts: Array<{
       text: string;
@@ -1477,5 +1537,5 @@ declare function assertMockRequest(request: NormalizedRequest, expectation: Mock
 //#region src/adapters/mock/streaming.d.ts
 declare function withMockStreaming(handler: MockStaticHandler, options: MockTextStreamOptions): MockHandler;
 //#endregion
-export { type AIClient, AIError, AIMappingError, AIProviderError, AIRecoverableError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, type AdapterKind, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type Citation, type CodeExecutionServerTool, type CompressRequest, type CompressResult, type ContainerFileCitation, type ContentBlock, type ContextCompressCapable, type CreateAIClientOptions, type ErrorCode, type FetchFn, GeminiAdapter, type GeminiAdapterOptions, type IncludeSettings, type InputItem, type InstructionBlock, type JsonContentBlock, KNOWN_ADAPTER_KINDS, type KnownAdapterKind, type KnownErrorCode, type KnownWarningCode, type McpServerTool, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, MockAdapter, type MockAdapterOptions, type MockAuxiliaryStep, type MockCompleteStep, type MockCompressHandler, type MockErrorStep, type MockHandler, type MockHandlerContext, type MockHistoryRecord, type MockInputExpectation, type MockInterruptStep, type MockMessageStep, type MockOutputStep, type MockReasoningStep, type MockRequestExpectation, type MockServerToolCallStep, type MockServerToolDiscoveryStep, type MockServerToolResultStep, type MockStaticHandler, type MockStep, type MockTextStreamOptions, type MockThrowStep, type MockToolCallStep, type MockWarningStep, type NormalizedRequest, OllamaAdapter, type OllamaAdapterOptions, type OpaqueItem, type OutputItem, REASONING_LEVELS, REASONING_LEVEL_SET, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningLevel, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type ServerToolCallItem, type ServerToolCompletedEvent, type ServerToolDefinition, type ServerToolDeltaEvent, type ServerToolDiscoveryCompletedEvent, type ServerToolDiscoveryItem, type ServerToolResultCompletedEvent, type ServerToolResultItem, type ServerToolStartedEvent, type StopReason, type StreamEventBase, type StreamWarning, type TextContentBlock, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type UrlCitation, type Usage, WarningCode, type WarningCodeName, type WarningCodeValue, type WebSearchServerTool, type WebSearchUserLocation, assertMockRequest, blockToText, coalesceContentBlocks, collectStream, contentBlocksToText, createAIClient, extractText, imageBlock, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, opaqueBlock, opaqueItem, reasoningItem, replayFromOutput, serverToolCallItem, serverToolDiscoveryItem, serverToolResultItem, streamWarningKey, supportsContextCompress, textBlock, toolCallItem, toolResultItem, withMockStreaming };
+export { type AIClient, AIError, AIMappingError, AIProviderError, AIRecoverableError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, type AdapterKind, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type Citation, type CodeExecutionServerTool, type CompressRequest, type CompressResult, type ContainerFileCitation, type ContentBlock, type ContextCompressCapable, type CreateAIClientOptions, type ErrorCode, type FetchFn, GeminiAdapter, type GeminiAdapterOptions, type IncludeSettings, type InputItem, type InstructionBlock, type JsonContentBlock, KNOWN_ADAPTER_KINDS, type KnownAdapterKind, type KnownErrorCode, type KnownWarningCode, type McpServerTool, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, MockAdapter, type MockAdapterOptions, type MockAuxiliaryStep, type MockCompleteStep, type MockCompressHandler, type MockErrorStep, type MockHandler, type MockHandlerContext, type MockHistoryRecord, type MockInputExpectation, type MockInterruptStep, type MockMessageStep, type MockOutputStep, type MockReasoningStep, type MockRequestExpectation, type MockServerToolCallStep, type MockServerToolDiscoveryStep, type MockServerToolResultStep, type MockStaticHandler, type MockStep, type MockTextStreamOptions, type MockThrowStep, type MockToolCallStep, type MockWarningStep, type NormalizedRequest, OllamaAdapter, type OllamaAdapterOptions, type OpaqueItem, type OutputItem, type PromptCacheMetadata, type PromptCacheMode, type PromptCacheSettings, type ProviderCacheOptions, REASONING_LEVELS, REASONING_LEVEL_SET, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningLevel, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type ServerToolCallItem, type ServerToolCompletedEvent, type ServerToolDefinition, type ServerToolDeltaEvent, type ServerToolDiscoveryCompletedEvent, type ServerToolDiscoveryItem, type ServerToolResultCompletedEvent, type ServerToolResultItem, type ServerToolStartedEvent, type StopReason, type StreamEventBase, type StreamWarning, type TextContentBlock, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type UrlCitation, type Usage, WarningCode, type WarningCodeName, type WarningCodeValue, type WebSearchServerTool, type WebSearchUserLocation, assertMockRequest, blockToText, coalesceContentBlocks, collectStream, contentBlocksToText, createAIClient, extractText, imageBlock, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, opaqueBlock, opaqueItem, reasoningItem, replayFromOutput, serverToolCallItem, serverToolDiscoveryItem, serverToolResultItem, streamWarningKey, supportsContextCompress, textBlock, toolCallItem, toolResultItem, withMockStreaming };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1064,7 +1064,7 @@ var AdapterAuxiliaryState = class {
 	recordProviderMetadata(source, metadata) {
 		if (this.request.include?.providerMetadata === "off" || !metadata || isEmptyRecord(metadata)) return;
 		this.collector.recordMetadata(metadata);
-		this.metadataSources.add(source);
+		if (source) this.metadataSources.add(source);
 	}
 	async finalize(factory, options = {}) {
 		if (options.lookup && this.shouldAttemptLookup()) await this.collector.tryLookup(options.lookup, options.lookupTimeoutMs);
@@ -1119,6 +1119,102 @@ function isEmptyRecord(value) {
 	return Object.keys(value).length === 0;
 }
 //#endregion
+//#region src/provider/prompt-cache.ts
+function requestedPromptCacheMode(request) {
+	return request.cache?.mode ?? "auto";
+}
+function promptCacheAdapterForKind(kind) {
+	if (kind === "responses" || kind === "chat-completions" || kind === "messages" || kind === "gemini" || kind === "ollama") return kind;
+}
+function promptCacheMetadata(request, adapter, overrides = {}) {
+	const requestedMode = requestedPromptCacheMode(request);
+	if (requestedMode === "off") return {
+		requestedMode,
+		appliedMode: "off",
+		keyApplied: false,
+		ttlApplied: false
+	};
+	const native = request.providerOptions?.cache;
+	const portable = request.cache;
+	let appliedMode = "implicit";
+	let keyApplied = false;
+	let ttlApplied = false;
+	if (adapter === "responses") {
+		const nativeOptions = native?.responses;
+		const mode = nativeOptions?.promptCacheMode ?? (requestedMode === "explicit" ? "explicit" : void 0);
+		keyApplied = mode !== "off" && Boolean(nativeOptions?.promptCacheKey ?? portable?.key);
+		ttlApplied = mode !== "off" && Boolean(nativeOptions?.promptCacheRetention ?? mapPromptCacheRetention(portable?.ttl));
+		appliedMode = mode === "off" ? "off" : mode === "explicit" ? "explicit" : "implicit";
+	} else if (adapter === "chat-completions") {
+		const options = native?.chatCompletions;
+		keyApplied = Boolean(options?.promptCacheKey ?? portable?.key);
+		ttlApplied = Boolean(options?.promptCacheRetention ?? mapPromptCacheRetention(portable?.ttl));
+		appliedMode = requestedMode === "explicit" || Boolean(options?.promptCacheKey || options?.promptCacheRetention) ? "explicit" : "implicit";
+	} else if (adapter === "messages") {
+		const hasStablePrefix = Boolean(request.instructions) || request.input.length > 0 || (request.tools?.length ?? 0) > 0;
+		const explicitRequested = requestedMode === "explicit" || native?.messages?.cacheTtl !== void 0;
+		const explicit = explicitRequested && hasStablePrefix;
+		appliedMode = explicit ? "explicit" : explicitRequested ? "unsupported" : "implicit";
+		ttlApplied = explicit && Boolean(native?.messages?.cacheTtl ?? mapAnthropicCacheTtl(portable?.ttl));
+	} else if (adapter === "gemini") if (native?.gemini?.cachedContent) appliedMode = "explicit";
+	else appliedMode = requestedMode === "explicit" ? "unsupported" : "implicit";
+	else if (adapter === "ollama") {
+		const keepAlive = native?.ollama?.keepAlive;
+		appliedMode = requestedMode === "explicit" && keepAlive === void 0 ? "unsupported" : requestedMode === "explicit" ? "explicit" : "implicit";
+	}
+	return {
+		requestedMode,
+		appliedMode: overrides.explicitApplied === true ? "explicit" : appliedMode,
+		keyApplied: overrides.keyApplied ?? keyApplied,
+		ttlApplied: overrides.ttlApplied ?? ttlApplied
+	};
+}
+function applyPromptCacheFields(body, request, adapter) {
+	const portable = request.cache;
+	const native = request.providerOptions?.cache;
+	const metadata = promptCacheMetadata(request, adapter);
+	if (portable?.mode === "off") return metadata;
+	if (adapter === "responses") {
+		const options = native?.responses;
+		const key = options?.promptCacheKey ?? portable?.key;
+		const mode = options?.promptCacheMode ?? (portable?.mode === "explicit" ? "explicit" : void 0);
+		const retention = options?.promptCacheRetention ?? mapPromptCacheRetention(portable?.ttl);
+		if (mode !== "off" && key) body.prompt_cache_key = key;
+		if (mode || retention) body.prompt_cache_options = {
+			...mode ? { mode } : {},
+			...mode !== "off" && retention ? { retention } : {}
+		};
+		return metadata;
+	}
+	if (adapter === "chat-completions") {
+		const options = native?.chatCompletions;
+		const key = options?.promptCacheKey ?? portable?.key;
+		const retention = options?.promptCacheRetention ?? mapPromptCacheRetention(portable?.ttl);
+		if (key) body.prompt_cache_key = key;
+		if (retention) body.prompt_cache_retention = retention;
+		return metadata;
+	}
+	if (adapter === "gemini") {
+		const cachedContent = native?.gemini?.cachedContent;
+		if (cachedContent) body.cachedContent = cachedContent;
+		return metadata;
+	}
+	if (adapter === "ollama") {
+		const keepAlive = native?.ollama?.keepAlive;
+		if (keepAlive !== void 0) body.keep_alive = keepAlive;
+	}
+	return metadata;
+}
+function mapPromptCacheRetention(ttl) {
+	if (ttl === "short") return "in_memory";
+	if (ttl === "long") return "24h";
+	if (ttl === "in_memory" || ttl === "24h") return ttl;
+}
+function mapAnthropicCacheTtl(ttl) {
+	if (ttl === "short" || ttl === "5m") return "5m";
+	if (ttl === "long" || ttl === "1h") return "1h";
+}
+//#endregion
 //#region src/provider/base.ts
 var AdapterBase = class {
 	/**
@@ -1201,7 +1297,10 @@ var AdapterBase = class {
 		yield factory.responseCompleted(payload);
 	}
 	createAuxiliaryState(request) {
-		return new AdapterAuxiliaryState(request);
+		const auxiliary = new AdapterAuxiliaryState(request);
+		const adapter = promptCacheAdapterForKind(this.kind);
+		if (adapter) auxiliary.recordProviderMetadata(void 0, { promptCache: promptCacheMetadata(request, adapter) });
+		return auxiliary;
 	}
 };
 function mergeWarnings(...groups) {
@@ -1564,6 +1663,7 @@ function usageFromChatCompletions(raw) {
 		outputTokens: num(raw.completion_tokens),
 		totalTokens: num(raw.total_tokens),
 		cachedInputTokens: num(raw.prompt_tokens_details?.cached_tokens),
+		cacheWriteInputTokens: num(raw.cache_write_tokens ?? raw.prompt_tokens_details?.cache_write_tokens),
 		reasoningTokens: num(raw.completion_tokens_details?.reasoning_tokens)
 	});
 }
@@ -1574,6 +1674,7 @@ function usageFromOpenAIResponses(raw) {
 		outputTokens: num(raw.output_tokens),
 		totalTokens: num(raw.total_tokens),
 		cachedInputTokens: num(raw.input_tokens_details?.cached_tokens),
+		cacheWriteInputTokens: num(raw.cache_write_tokens ?? raw.input_tokens_details?.cache_write_tokens),
 		reasoningTokens: num(raw.output_tokens_details?.reasoning_tokens)
 	});
 }
@@ -2111,6 +2212,29 @@ function mapResponsesMessageContent(role, blocks, field) {
 		throw new AIRequestError(`${mapper$7.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
 	});
 }
+function mapResponsesToolResultOutput(blocks, field) {
+	mapper$7.ensureBlocks(blocks, field, [
+		"text",
+		"json",
+		"image"
+	], "only text/json/image blocks are supported");
+	if (!blocks.some((block) => block.type === "image")) return mapper$7.textFromBlocks(blocks, field);
+	return blocks.map((block) => {
+		if (block.type === "text") return {
+			type: "input_text",
+			text: block.text
+		};
+		if (block.type === "json") return {
+			type: "input_text",
+			text: JSON.stringify(block.json)
+		};
+		if (block.type === "image") return {
+			type: "input_image",
+			image_url: block.imageUrl
+		};
+		throw new AIRequestError(`${mapper$7.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
+	});
+}
 function mapReasoningInput(item, index) {
 	const text = mapper$7.textFromBlocks(mapper$7.ensureReasoningBlocks(item.content, "reasoning content"), "reasoning content");
 	const id = item.id && item.id.length > 0 ? item.id : `reasoning_replay_${index}`;
@@ -2186,7 +2310,7 @@ function mapResponsesCore(request, options) {
 			});
 			break;
 		case "tool_result": {
-			const output = mapper$7.textFromBlocks(item.content, `tool_result ${item.callId} content`);
+			const output = mapResponsesToolResultOutput(item.content, `tool_result ${item.callId} content`);
 			input.push({
 				type: "function_call_output",
 				call_id: item.callId,
@@ -2256,6 +2380,7 @@ function buildResponsesRequest(request, options) {
 	if (request.maxOutputTokens !== void 0) body.max_output_tokens = request.maxOutputTokens;
 	if (request.metadata) body.metadata = request.metadata;
 	if (request.reasoningLevel !== void 0) body.reasoning = mapResponsesReasoning(request.reasoningLevel);
+	applyPromptCacheFields(body, request, "responses");
 	return body;
 }
 /**
@@ -3207,6 +3332,15 @@ function mapMessagesUserContent(blocks, field) {
 	}
 	return blocks.map((block) => canonicalToMessagesBlock(block, field));
 }
+function mapMessagesToolResultContent(blocks, field) {
+	mapper$6.ensureBlocks(blocks, field, [
+		"text",
+		"json",
+		"image"
+	], "only text/json/image blocks are supported");
+	if (!blocks.some((block) => block.type === "image")) return mapper$6.textFromBlocks(blocks, field);
+	return blocks.map((block) => canonicalToMessagesBlock(block, field));
+}
 function buildMessagesRequest(request, options) {
 	mapper$6.assertNoServerTools(request.serverTools);
 	const messages = [];
@@ -3252,7 +3386,7 @@ function buildMessagesRequest(request, options) {
 				break;
 			}
 			case "tool_result": {
-				const content = mapper$6.textFromBlocks(item.content, `tool_result ${item.callId} content`);
+				const content = mapMessagesToolResultContent(item.content, `tool_result ${item.callId} content`);
 				const block = {
 					type: "tool_result",
 					tool_use_id: item.callId,
@@ -3319,8 +3453,45 @@ function buildMessagesRequest(request, options) {
 	});
 	if (request.temperature !== void 0) body.temperature = request.temperature;
 	if (request.reasoningLevel !== void 0) body.thinking = mapMessagesThinking(request.reasoningLevel, body.max_tokens);
+	applyMessagesPromptCache(body, request, systemPrompt);
 	return body;
 }
+function applyMessagesPromptCache(body, request, systemPrompt) {
+	const requestedMode = requestedPromptCacheMode(request);
+	if (requestedMode === "off") return;
+	if (requestedMode !== "explicit" && request.providerOptions?.cache?.messages?.cacheTtl === void 0) return;
+	const ttl = request.providerOptions?.cache?.messages?.cacheTtl ?? mapAnthropicCacheTtl(request.cache?.ttl);
+	const cacheControl = {
+		type: "ephemeral",
+		...ttl ? { ttl } : {}
+	};
+	if (systemPrompt) {
+		body.system = [{
+			type: "text",
+			text: systemPrompt,
+			cache_control: cacheControl
+		}];
+		return;
+	}
+	const lastMessage = body.messages[body.messages.length - 1];
+	if (lastMessage) {
+		if (typeof lastMessage.content === "string") {
+			lastMessage.content = [{
+				type: "text",
+				text: lastMessage.content,
+				cache_control: cacheControl
+			}];
+			return;
+		}
+		const lastBlock = lastMessage.content[lastMessage.content.length - 1];
+		if (lastBlock) {
+			lastBlock.cache_control = cacheControl;
+			return;
+		}
+	}
+	const lastTool = body.tools?.[body.tools.length - 1];
+	if (lastTool) lastTool.cache_control = cacheControl;
+}
 new NormalizedRequestMapper("messages");
 /** 用 response 级别的命名空间合成 content block 的 item ID，避免多轮工具循环 ID 碰撞 */
 function synthesizeItemId(kind, blockIndex, responseId) {
@@ -3358,7 +3529,8 @@ async function* mapMessagesStream(host, providerRequest, factory, request) {
 		headers: host.mergeHeaders({
 			"Content-Type": "application/json",
 			"x-api-key": host.apiKey ?? "",
-			"anthropic-version": host.apiVersion
+			"anthropic-version": host.apiVersion,
+			...request.providerOptions?.cache?.messages?.betaHeader ? { "anthropic-beta": request.providerOptions.cache.messages.betaHeader } : {}
 		}),
 		body: providerRequest
 	});
@@ -3688,6 +3860,29 @@ function mapChatUserContent(blocks, field) {
 		throw new AIRequestError(`${mapper$4.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
 	});
 }
+function mapChatToolResultContent(blocks, field) {
+	mapper$4.ensureBlocks(blocks, field, [
+		"text",
+		"json",
+		"image"
+	], "only text/json/image blocks are supported");
+	if (!blocks.some((block) => block.type === "image")) return mapper$4.textFromBlocks(blocks, field);
+	return blocks.map((block) => {
+		if (block.type === "text") return {
+			type: "text",
+			text: block.text
+		};
+		if (block.type === "json") return {
+			type: "text",
+			text: JSON.stringify(block.json)
+		};
+		if (block.type === "image") return {
+			type: "image_url",
+			image_url: { url: block.imageUrl }
+		};
+		throw new AIRequestError(`${mapper$4.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
+	});
+}
 function mapChatMessageContent(role, blocks, field) {
 	if (role === "user") return mapChatUserContent(blocks, field);
 	return mapper$4.textFromBlocks(blocks, field) || null;
@@ -3731,7 +3926,7 @@ function buildChatCompletionsRequest(request, options) {
 				role: "tool",
 				tool_call_id: item.callId,
 				name: item.toolName,
-				content: mapper$4.textFromBlocks(item.content, `tool_result ${item.callId} content`)
+				content: mapChatToolResultContent(item.content, `tool_result ${item.callId} content`)
 			});
 			break;
 		case "reasoning":
@@ -3770,6 +3965,7 @@ function buildChatCompletionsRequest(request, options) {
 	if (request.maxOutputTokens !== void 0) body.max_tokens = request.maxOutputTokens;
 	if (request.metadata) body.metadata = request.metadata;
 	if (request.reasoningLevel !== void 0) body.reasoning_effort = mapChatCompletionsReasoningEffort(request.reasoningLevel);
+	applyPromptCacheFields(body, request, "chat-completions");
 	return body;
 }
 //#endregion
@@ -4057,6 +4253,21 @@ function mapOllamaUserMessage(blocks, field) {
 		...images.length > 0 ? { images } : {}
 	};
 }
+function mapOllamaToolResultContent(blocks, field) {
+	mapper$3.ensureBlocks(blocks, field, [
+		"text",
+		"json",
+		"image"
+	], "only text/json/image blocks are supported");
+	const textBlocks = [];
+	const images = [];
+	for (const block of blocks) if (block.type === "image") images.push(mapOllamaImageData(block.imageUrl, field));
+	else textBlocks.push(block);
+	return {
+		content: contentBlocksToText(textBlocks),
+		...images.length > 0 ? { images } : {}
+	};
+}
 function buildOllamaRequest(request, options) {
 	mapper$3.assertNoServerTools(request.serverTools);
 	const messages = [];
@@ -4104,7 +4315,7 @@ function buildOllamaRequest(request, options) {
 			if (queue && queue.length > 0) queue.shift();
 			messages.push({
 				role: "tool",
-				content: mapper$3.textFromBlocks(item.content, `tool_result ${item.callId} content`)
+				...mapOllamaToolResultContent(item.content, `tool_result ${item.callId} content`)
 			});
 			break;
 		}
@@ -4154,6 +4365,7 @@ function buildOllamaRequest(request, options) {
 		if (request.maxOutputTokens !== void 0) body.options.num_predict = request.maxOutputTokens;
 	}
 	if (request.reasoningLevel !== void 0) body.think = mapOllamaThink(request.reasoningLevel);
+	applyPromptCacheFields(body, request, "ollama");
 	return body;
 }
 new NormalizedRequestMapper("ollama");
@@ -4330,6 +4542,29 @@ function mapGeminiImagePart(imageUrl, field) {
 		data: dataUrl.data
 	} };
 }
+function mapGeminiToolResultContent(blocks, field) {
+	mapper$1.ensureBlocks(blocks, field, [
+		"text",
+		"json",
+		"image"
+	], "only text/json/image blocks are supported");
+	const textBlocks = [];
+	const imageParts = [];
+	for (const block of blocks) if (block.type === "image") imageParts.push(mapGeminiImagePart(block.imageUrl, field));
+	else textBlocks.push(block);
+	const text = contentBlocksToText(textBlocks);
+	let response;
+	try {
+		const parsed = text ? JSON.parse(text) : {};
+		response = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { result: text };
+	} catch {
+		response = { result: text };
+	}
+	return {
+		response,
+		imageParts
+	};
+}
 function textPartsFromBlocks(blocks, field) {
 	return mapper$1.ensureTextBlocks(blocks, field).map((block) => {
 		if (block.type === "text") return { text: block.text };
@@ -4381,19 +4616,13 @@ function buildGeminiRequest(request, options) {
 			} });
 			break;
 		case "tool_result": {
-			let response;
-			try {
-				const text = mapper$1.textFromBlocks(item.content, `tool_result ${item.callId} content`);
-				const parsed = text ? JSON.parse(text) : {};
-				response = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { result: text };
-			} catch {
-				response = { result: mapper$1.textFromBlocks(item.content, `tool_result ${item.callId} content`) };
-			}
+			const { response, imageParts } = mapGeminiToolResultContent(item.content, `tool_result ${item.callId} content`);
 			appendPart(contents, "user", { functionResponse: {
 				id: item.callId,
 				name: item.toolName,
 				response
 			} });
+			for (const imagePart of imageParts) appendPart(contents, "user", imagePart);
 			break;
 		}
 		case "reasoning":
@@ -4438,6 +4667,7 @@ function buildGeminiRequest(request, options) {
 	if (request.maxOutputTokens !== void 0) generationConfig.maxOutputTokens = request.maxOutputTokens;
 	if (request.reasoningLevel !== void 0) generationConfig.thinkingConfig = mapGeminiThinking(request.reasoningLevel);
 	if (Object.keys(generationConfig).length > 0) body.generationConfig = generationConfig;
+	applyPromptCacheFields(body, request, "gemini");
 	return body;
 }
 new NormalizedRequestMapper("gemini");