@@ -8,6 +8,8 @@ import {
88 } from "ai";
99 import { logApiEvent } from "./api-log.ts";
1010 import {
11+ getCacheFamily,
12+ getCachingProviderOptions,
1113 getThinkingProviderOptions,
1214 parseModelString,
1315 type ThinkingEffort,
@@ -624,12 +626,83 @@ export function isOpenAIGPT(modelString: string): boolean {
624626 );
625627 }
626628
629+export function annotateAnthropicCacheBreakpoints(
630+ turnMessages: CoreMessage[],
631+ systemPrompt?: string,
632+): {
633+ messages: CoreMessage[];
634+ systemPrompt?: string;
635+ diagnostics: { breakpointsAdded: number; stableIdx: number };
636+} {
637+ const finalMessages = [...turnMessages];
638+ let breakpointsAdded = 0;
639+
640+ // Breakpoint 2: The last user message or 2nd to last message,
641+ // to cache the conversation history minus the very last turn.
642+ const stableIdx = finalMessages.length > 2 ? finalMessages.length - 2 : -1;
643+ if (stableIdx >= 0 && finalMessages[stableIdx]) {
644+ const msg = finalMessages[stableIdx];
645+ finalMessages[stableIdx] = {
646+ ...msg,
647+ providerOptions: {
648+ ...(msg?.providerOptions ?? {}),
649+ anthropic: {
650+ ...((msg?.providerOptions?.anthropic as Record<string, unknown>) ??
651+ {}),
652+ cacheControl: { type: "ephemeral" },
653+ },
654+ },
655+ } as CoreMessage;
656+ breakpointsAdded++;
657+ }
658+
659+ // Breakpoint 1: the system prompt
660+ let finalSystemPrompt = systemPrompt;
661+ if (systemPrompt) {
662+ finalMessages.unshift({
663+ role: "system",
664+ content: systemPrompt,
665+ providerOptions: {
666+ anthropic: { cacheControl: { type: "ephemeral" } },
667+ },
668+ });
669+ finalSystemPrompt = undefined; // Do not send as top-level system
670+ breakpointsAdded++;
671+ }
672+
673+ return {
674+ messages: finalMessages,
675+ ...(finalSystemPrompt !== undefined
676+ ? { systemPrompt: finalSystemPrompt }
677+ : {}),
678+ diagnostics: { breakpointsAdded, stableIdx },
679+ };
680+}
681+
627682 /**
628683 * Run a single agent turn against the model.
629684 *
630685 * Yields TurnEvents as they arrive, then yields a final TurnCompleteEvent
631686 * (or TurnErrorEvent on failure).
632687 */
688+// helper for deep merge
689+const mergeDeep = (
690+ target: Record<string, unknown>,
691+ source: Record<string, unknown>,
692+) => {
693+ const output: Record<string, unknown> = { ...target };
694+ for (const key in source) {
695+ const sVal = source[key];
696+ const tVal = target[key];
697+ if (isRecord(sVal) && isRecord(tVal)) {
698+ output[key] = { ...tVal, ...sVal };
699+ } else {
700+ output[key] = sVal;
701+ }
702+ }
703+ return output;
704+};
705+
633706 export async function* runTurn(options: {
634707 model: CoreModel;
635708 modelString: string;
@@ -640,6 +713,9 @@ export async function* runTurn(options: {
640713 thinkingEffort?: ThinkingEffort;
641714 pruningMode?: ContextPruningMode;
642715 toolResultPayloadCapBytes?: number;
716+ promptCachingEnabled?: boolean;
717+ openaiPromptCacheRetention?: "in_memory" | "24h";
718+ googleCachedContent?: string | null;
643719 }): AsyncGenerator<TurnEvent> {
644720 const {
645721 model,
@@ -650,6 +726,9 @@ export async function* runTurn(options: {
650726 signal,
651727 thinkingEffort,
652728 pruningMode = "balanced",
729+ promptCachingEnabled = true,
730+ openaiPromptCacheRetention = "in_memory",
731+ googleCachedContent = null,
653732 toolResultPayloadCapBytes = DEFAULT_TOOL_RESULT_PAYLOAD_CAP_BYTES,
654733 } = options;
655734
@@ -745,8 +824,21 @@ export async function* runTurn(options: {
745824 diagnostics: getMessageDiagnostics(turnMessages),
746825 });
747826 }
748-
749- const mergedProviderOptions = {
827+ const cacheFamily = getCacheFamily(modelString);
828+ const googleExplicitCachingCompatible = toolCount === 0 && !systemPrompt;
829+ const cacheOpts = getCachingProviderOptions(modelString, {
830+ enabled: promptCachingEnabled,
831+ openaiRetention: openaiPromptCacheRetention,
832+ googleCachedContent,
833+ googleExplicitCachingCompatible,
834+ });
835+ logApiEvent("prompt caching configured", {
836+ enabled: promptCachingEnabled,
837+ cacheFamily,
838+ cacheOpts,
839+ googleExplicitCachingCompatible,
840+ });
841+ let mergedProviderOptions = {
750842 ...(thinkingOpts ?? {}),
751843 ...(isOpenAIGPT(modelString)
752844 ? {
@@ -771,9 +863,26 @@ export async function* runTurn(options: {
771863 : {}),
772864 };
773865
866+ if (cacheOpts) {
867+ mergedProviderOptions = mergeDeep(mergedProviderOptions, cacheOpts);
868+ }
869+
870+ let finalMessages = turnMessages;
871+ let finalSystemPrompt = systemPrompt;
872+
873+ if (cacheFamily === "anthropic" && promptCachingEnabled) {
874+ const annotated = annotateAnthropicCacheBreakpoints(
875+ turnMessages,
876+ systemPrompt,
877+ );
878+ finalMessages = annotated.messages;
879+ finalSystemPrompt = annotated.systemPrompt;
880+ logApiEvent("Anthropic prompt caching", annotated.diagnostics);
881+ }
882+
774883 const streamOpts: StreamTextOptions = {
775884 model,
776- messages: turnMessages,
885+ messages: finalMessages,
777886 tools: toolSet,
778887 stopWhen: stepCountIs(MAX_STEPS),
779888 onStepFinish: (step: StepResult<ToolSet>) => {
@@ -807,7 +916,9 @@ export async function* runTurn(options: {
807916 return undefined;
808917 },
809918
810- ...(systemPrompt && !useInstructions ? { system: systemPrompt } : {}),
919+ ...(finalSystemPrompt && !useInstructions
920+ ? { system: finalSystemPrompt }
921+ : {}),
811922 ...(Object.keys(mergedProviderOptions).length > 0
812923 ? { providerOptions: mergedProviderOptions }
813924 : {}),