@codehz/ai 0.8.1 → 0.9.0

package/README.md

@@ -97,7 +97,11 @@ type AIRequest = {
   temperature?: number; // provider/model-defined generation parameter
   maxOutputTokens?: number; // 最大输出 token
   reasoningLevel?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; // 可移植思考力度
-  include?: { usage?; billing?; providerMetadata? };
+  include?: {
+    usage?: "off" | "best_effort" | "required";
+    billing?: "off" | "best_effort" | "required";
+    providerMetadata?: "off" | "best_effort";
+  };
 };
 ```
 
@@ -530,7 +534,9 @@ const r2 = await collectStream(client.stream({ input, tools }));
 
 ## 辅助信息采集
 
-usage / billing / providerMetadata 由 adapter 在流结束时经 `response.auxiliary` 与 `AIResponse` 字段交付。`AuxiliaryCollector` 是 provider 内部实现细节，`0.5.0` 起不再从根入口导出。`lookup` / `postprocessBilling` 为 experimental 扩展点，库内 HTTP adapter 默认未接线。
+`usage` / `billing` / `providerMetadata` 由 adapter 在流结束时经 `response.auxiliary` 与 `AIResponse` 字段交付。`AuxiliaryCollector` 是 provider 内部实现细节，`0.5.0` 起不再从根入口导出。`lookup` / `postprocessBilling` 为 experimental 扩展点，库内 HTTP adapter 默认未接线。
+
+`usage` 与 `billing` 的 `include` 支持三种模式：`off` 表示不采集；`best_effort`（默认）表示尽可能采集，缺失时静默；`required` 表示缺失时发出 `USAGE_MISSING` 或 `BILLING_MISSING` warning。估算 billing 仍会发出 `BILLING_ESTIMATED` warning。
 
 ## 开发命令
 

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;
@@ -171,8 +207,8 @@ type McpServerTool = {
 /** Provider 托管执行的工具声明（不进客户端 tool loop） */
 type ServerToolDefinition = WebSearchServerTool | CodeExecutionServerTool | McpServerTool;
 type IncludeSettings = {
-  usage?: "off" | "best_effort";
-  billing?: "off" | "best_effort";
+  usage?: "off" | "best_effort" | "required";
+  billing?: "off" | "best_effort" | "required";
   providerMetadata?: "off" | "best_effort";
 };
 /** Portable reasoning / thinking effort. Mapped per-adapter to provider wire fields. */
@@ -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 */
@@ -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);
@@ -1091,11 +1091,11 @@ var AdapterAuxiliaryState = class {
 			billing: built.billing,
 			auxiliary: built.auxiliary
 		}));
-		if (this.request.include?.usage !== "off" && !built.usage) events.push(factory.responseWarning("Usage information was not provided by the provider", WarningCode.USAGE_MISSING));
-		if (this.request.include?.billing !== "off") {
+		if (this.request.include?.usage === "required" && !built.usage) events.push(factory.responseWarning("Usage information was not provided by the provider", WarningCode.USAGE_MISSING));
+		if (this.request.include?.billing === "required") {
 			if (!built.billing) events.push(factory.responseWarning("Billing information was not provided by the provider", WarningCode.BILLING_MISSING));
 			else if (built.billing.isEstimated) events.push(factory.responseWarning("Billing amount is an estimate", WarningCode.BILLING_ESTIMATED));
-		}
+		} else if (built.billing?.isEstimated) events.push(factory.responseWarning("Billing amount is an estimate", WarningCode.BILLING_ESTIMATED));
 		return {
 			events,
 			usage: built.usage,
@@ -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)
 	});
 }
@@ -2279,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;
 }
 /**
@@ -3351,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) {
@@ -3390,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
 	});
@@ -3825,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
@@ -4224,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");
@@ -4525,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");