@juspay/neurolink 9.79.0 → 9.79.1

package/dist/lib/providers/googleVertex.js

@@ -10,6 +10,7 @@ import { ModelConfigurationManager } from "../core/modelConfiguration.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
 import { ERROR_CODES, NeuroLinkError } from "../utils/errorHandling.js";
+import { applyVertexAnthropicCacheBreakpoints } from "../utils/anthropicCacheBreakpoints.js";
 import { FileDetector } from "../utils/fileDetector.js";
 import { processUnifiedFilesArray } from "../utils/messageBuilder.js";
 import { logger } from "../utils/logger.js";
@@ -2491,9 +2492,27 @@ export class GoogleVertexProvider extends BaseProvider {
                     }, turnContext);
                     let response;
                     try {
+                        // Vertex has no automatic prompt caching — place explicit
+                        // cache_control breakpoints (system, tools, rolling history) so the
+                        // conversation prefix is cached across turns instead of re-billed as
+                        // fresh input every call. Re-applied per step: the stable prefix
+                        // stays byte-identical (consistent cache key) while the rolling
+                        // breakpoint follows the growing tail.
+                        const cachedStream = applyVertexAnthropicCacheBreakpoints({
+                            system: systemPromptWithSchema,
+                            tools,
+                            messages: currentMessages,
+                        });
                         const stream = await client.messages.stream({
                             ...requestParams,
-                            messages: currentMessages,
+                            ...(cachedStream.system !== undefined && {
+                                system: cachedStream.system,
+                            }),
+                            ...(cachedStream.tools &&
+                                cachedStream.tools.length > 0 && {
+                                tools: cachedStream.tools,
+                            }),
+                            messages: cachedStream.messages,
                         });
                         activeStream = stream;
                         // Forward each text delta as it arrives — the Anthropic SDK fires
@@ -2750,6 +2769,17 @@ export class GoogleVertexProvider extends BaseProvider {
                 }
                 metadata.responseTime = Date.now() - startTime;
                 metadata.totalToolExecutions = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
+                // Surface cache metrics once, after the agentic loop, from the
+                // cumulative turnCacheUsage running totals (accumulated via += on every
+                // step above). Assigned here — not per-iteration — so the final values
+                // are unambiguous: analytics sees caching is working and calculateCost
+                // can price the cache-read/write tiers instead of full input rate.
+                if (turnCacheUsage.read > 0) {
+                    usage.cacheReadTokens = turnCacheUsage.read;
+                }
+                if (turnCacheUsage.creation > 0) {
+                    usage.cacheCreationTokens = turnCacheUsage.creation;
+                }
                 const turnOutputAttribute = spanJsonAttribute({
                     text: aggregatedTurnText,
                     ...(structuredOutputRef.value
@@ -3110,6 +3140,12 @@ export class GoogleVertexProvider extends BaseProvider {
         const allToolCalls = [];
         let totalInputTokens = 0;
         let totalOutputTokens = 0;
+        // Cache metrics (Anthropic reports these separately from input_tokens, which
+        // is the uncached remainder). Surfaced on the result so analytics can see
+        // caching is working and calculateCost can price the ~0.1x cache-read /
+        // ~1.25x cache-write tiers instead of billing everything at full input rate.
+        let totalCacheReadTokens = 0;
+        let totalCacheCreationTokens = 0;
         // Track the final Anthropic stop_reason so we can surface finishReason
         // (notably "length" on token truncation) — the legacy native path always
         // reported "stop", hiding truncation from callers.
@@ -3121,13 +3157,36 @@ export class GoogleVertexProvider extends BaseProvider {
                 // Bound the SDK wait so a stalled Vertex/Anthropic call can't hang
                 // generate forever. options.timeout wins if set, otherwise default
                 // to 5 min — generous for tool-heavy turns.
+                // Vertex has no automatic prompt caching — place explicit cache_control
+                // breakpoints (system, tools, rolling history) so the conversation
+                // prefix is cached across turns instead of re-billed as fresh input
+                // every call. Re-applied per step: the stable prefix stays
+                // byte-identical (consistent cache key) while the rolling breakpoint
+                // follows the growing tail.
+                const cachedGenerate = applyVertexAnthropicCacheBreakpoints({
+                    system: systemPromptWithSchema,
+                    tools,
+                    messages: currentMessages,
+                });
                 const response = await withTimeout(client.messages.create({
                     ...requestParams,
-                    messages: currentMessages,
+                    ...(cachedGenerate.system !== undefined && {
+                        system: cachedGenerate.system,
+                    }),
+                    ...(cachedGenerate.tools &&
+                        cachedGenerate.tools.length > 0 && {
+                        tools: cachedGenerate.tools,
+                    }),
+                    messages: cachedGenerate.messages,
                 }), generateTimeoutMs, "Anthropic generate timed out");
-                // Update token counts
+                // Update token counts. input_tokens is the uncached remainder; cache
+                // reads/writes are reported separately and accumulated here so the
+                // result reflects the full picture.
                 totalInputTokens += response.usage?.input_tokens || 0;
                 totalOutputTokens += response.usage?.output_tokens || 0;
+                totalCacheReadTokens += response.usage?.cache_read_input_tokens || 0;
+                totalCacheCreationTokens +=
+                    response.usage?.cache_creation_input_tokens || 0;
                 lastStopReason = response.stop_reason;
                 // Check if we need to handle tool use
                 const toolUseBlocks = response.content.filter((block) => block.type === "tool_use");
@@ -3287,6 +3346,12 @@ export class GoogleVertexProvider extends BaseProvider {
                 input: totalInputTokens,
                 output: totalOutputTokens,
                 total: totalInputTokens + totalOutputTokens,
+                ...(totalCacheReadTokens > 0 && {
+                    cacheReadTokens: totalCacheReadTokens,
+                }),
+                ...(totalCacheCreationTokens > 0 && {
+                    cacheCreationTokens: totalCacheCreationTokens,
+                }),
             },
             responseTime,
             toolsUsed: externalToolCalls.map((tc) => tc.toolName),
@@ -3761,6 +3826,8 @@ export class GoogleVertexProvider extends BaseProvider {
         const inputTokens = usage.input ?? usage.inputTokens ?? 0;
         const outputTokens = usage.output ?? usage.outputTokens ?? 0;
         const totalTokens = usage.total ?? usage.totalTokens ?? inputTokens + outputTokens;
+        const cacheReadTokens = usage.cacheReadTokens ?? 0;
+        const cacheCreationTokens = usage.cacheCreationTokens ?? 0;
         if (inputTokens > 0) {
             span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
         }
@@ -3770,11 +3837,22 @@ export class GoogleVertexProvider extends BaseProvider {
         if (totalTokens > 0) {
             span.setAttribute("gen_ai.usage.total_tokens", totalTokens);
         }
+        if (cacheReadTokens > 0) {
+            span.setAttribute("gen_ai.usage.cache_read_input_tokens", cacheReadTokens);
+        }
+        if (cacheCreationTokens > 0) {
+            span.setAttribute("gen_ai.usage.cache_creation_input_tokens", cacheCreationTokens);
+        }
         try {
+            // Pass cache tokens through so calculateCost prices the ~0.1x cache-read
+            // and ~1.25x cache-write tiers instead of billing cached content at the
+            // full input rate.
             const cost = calculateCost(this.providerName, modelName, {
                 input: inputTokens,
                 output: outputTokens,
                 total: totalTokens,
+                cacheReadTokens,
+                cacheCreationTokens,
             });
             if (typeof cost === "number" && cost > 0) {
                 span.setAttribute("neurolink.cost", cost);

package/dist/lib/types/providers.d.ts

@@ -1797,11 +1797,21 @@ export type VertexGenaiFunctionDeclaration = {
  * Message payload passed to the Anthropic Vertex SDK — mirrors the Anthropic
  * Messages API shape (role + structured content blocks).
  */
+/**
+ * Anthropic ephemeral prompt-cache breakpoint marker. Placed on a content
+ * block / tool / system block to make the rendered prefix up to that point a
+ * cache breakpoint. Vertex has NO automatic caching, so these explicit markers
+ * are the only way the conversation prefix is cached across turns.
+ */
+export type VertexAnthropicCacheControl = {
+    type: "ephemeral";
+};
 export type VertexAnthropicMessage = {
     role: "user" | "assistant";
     content: string | Array<{
         type: "text";
         text: string;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "image";
         source: {
@@ -1809,6 +1819,7 @@ export type VertexAnthropicMessage = {
             media_type: string;
             data: string;
         };
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "document";
         source: {
@@ -1816,23 +1827,38 @@ export type VertexAnthropicMessage = {
             media_type: string;
             data: string;
         };
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "tool_use";
         id: string;
         name: string;
         input: unknown;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "tool_result";
         tool_use_id: string;
         content: string;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "thinking";
         thinking: string;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "redacted_thinking";
         data: string;
+        cache_control?: VertexAnthropicCacheControl;
     }>;
 };
+/**
+ * System prompt block form accepted by the Anthropic Vertex SDK. Used instead
+ * of a bare string when a `cache_control` breakpoint must ride on the system
+ * prompt (a string `system` cannot carry one).
+ */
+export type VertexAnthropicSystemBlock = {
+    type: "text";
+    text: string;
+    cache_control?: VertexAnthropicCacheControl;
+};
 /** Tool definition accepted by the Anthropic Vertex SDK. */
 export type VertexAnthropicTool = {
     name: string;
@@ -1842,6 +1868,26 @@ export type VertexAnthropicTool = {
         properties?: Record<string, unknown>;
         required?: string[];
     };
+    cache_control?: VertexAnthropicCacheControl;
+};
+/** Input to `applyVertexAnthropicCacheBreakpoints`. */
+export type VertexAnthropicCacheInput = {
+    system?: string;
+    tools?: VertexAnthropicTool[];
+    messages: VertexAnthropicMessage[];
+    /**
+     * Cap on how many of the most-recent messages receive a rolling history
+     * breakpoint. Defaults to "use the remaining budget". Two or more gives
+     * cross-turn continuity and resilience against Anthropic's 20-block cache
+     * lookback window on tool-heavy turns.
+     */
+    maxHistoryBreakpoints?: number;
+};
+/** Output of `applyVertexAnthropicCacheBreakpoints` — a cache-annotated request. */
+export type VertexAnthropicCacheOutput = {
+    system?: string | VertexAnthropicSystemBlock[];
+    tools?: VertexAnthropicTool[];
+    messages: VertexAnthropicMessage[];
 };
 /**
  * Content block variants returned by the Anthropic Vertex SDK during streaming

package/dist/lib/utils/anthropicCacheBreakpoints.d.ts

@@ -0,0 +1,15 @@
+import type { VertexAnthropicCacheInput, VertexAnthropicCacheOutput } from "../types/index.js";
+/**
+ * Annotate a native Vertex+Claude request with prompt-cache breakpoints.
+ *
+ * Budget allocation (max 4 markers):
+ *   1. The stable prefix — the last system block when a system prompt is
+ *      present (this single marker caches `tools + system`, since system
+ *      renders after tools); otherwise the last tool definition.
+ *   2-4. A rolling breakpoint on the last few messages, so the
+ *      growing-but-now-stable conversation history is cached and only the
+ *      newest turn is billed as fresh input.
+ *
+ * Pure: the inputs are cloned, never mutated.
+ */
+export declare function applyVertexAnthropicCacheBreakpoints(input: VertexAnthropicCacheInput): VertexAnthropicCacheOutput;

package/dist/lib/utils/anthropicCacheBreakpoints.js

@@ -0,0 +1,98 @@
+/**
+ * Anthropic prompt-cache breakpoint placement for the native Vertex+Claude
+ * request path.
+ *
+ * Vertex does NOT support automatic prompt caching — the only way the
+ * conversation prefix gets cached across turns is explicit `cache_control`
+ * markers in the request. Anthropic renders a request as `tools → system →
+ * messages` and caches the prefix up to each marker, with a hard ceiling of
+ * four markers.
+ *
+ * Without a marker on the message history, the entire (growing, often
+ * tool-result-heavy) conversation falls *after* the last breakpoint and is
+ * re-billed at full input price on every turn. That is the regression this
+ * fixes: it gives the history a rolling breakpoint so the stable prefix is
+ * cached at ~0.1x and only the newest turn is fresh.
+ */
+const EPHEMERAL = { type: "ephemeral" };
+/** Anthropic allows at most four `cache_control` breakpoints per request. */
+const MAX_BREAKPOINTS = 4;
+/**
+ * Annotate a native Vertex+Claude request with prompt-cache breakpoints.
+ *
+ * Budget allocation (max 4 markers):
+ *   1. The stable prefix — the last system block when a system prompt is
+ *      present (this single marker caches `tools + system`, since system
+ *      renders after tools); otherwise the last tool definition.
+ *   2-4. A rolling breakpoint on the last few messages, so the
+ *      growing-but-now-stable conversation history is cached and only the
+ *      newest turn is billed as fresh input.
+ *
+ * Pure: the inputs are cloned, never mutated.
+ */
+export function applyVertexAnthropicCacheBreakpoints(input) {
+    let budget = MAX_BREAKPOINTS;
+    // 1. Stable prefix. A bare string `system` cannot carry cache_control, so
+    // convert it to block form. Marking the last system block caches the whole
+    // tools + system prefix; only fall back to marking the last tool when there
+    // is no system prompt to mark.
+    let system = input.system;
+    let tools = input.tools;
+    const hasSystem = !!input.system && input.system.trim().length > 0;
+    if (hasSystem) {
+        system = [
+            { type: "text", text: input.system, cache_control: EPHEMERAL },
+        ];
+        budget--;
+    }
+    else if (input.tools && input.tools.length > 0) {
+        const lastIndex = input.tools.length - 1;
+        tools = input.tools.map((tool, i) => i === lastIndex ? { ...tool, cache_control: EPHEMERAL } : tool);
+        budget--;
+    }
+    // 2. Rolling history breakpoints over the tail of the conversation.
+    const messages = input.messages.map((m) => ({ ...m }));
+    let remaining = Math.min(budget, input.maxHistoryBreakpoints ?? MAX_BREAKPOINTS);
+    for (let i = messages.length - 1; i >= 0 && remaining > 0; i--) {
+        if (markLastContentBlock(messages, i)) {
+            remaining--;
+        }
+    }
+    return { system, tools, messages };
+}
+/**
+ * Place a cache breakpoint on the last content block of `messages[i]`.
+ * Anthropic attaches `cache_control` to a content block, not the message
+ * envelope, so a string content body is first converted to block form.
+ * Returns false when the message has no markable block (caller then walks to
+ * an earlier message), so an empty turn never silently consumes a breakpoint.
+ */
+function markLastContentBlock(messages, i) {
+    const message = messages[i];
+    if (typeof message.content === "string") {
+        if (message.content.length === 0) {
+            return false;
+        }
+        messages[i] = {
+            ...message,
+            content: [
+                { type: "text", text: message.content, cache_control: EPHEMERAL },
+            ],
+        };
+        return true;
+    }
+    if (!Array.isArray(message.content) || message.content.length === 0) {
+        return false;
+    }
+    // Shallow clone is sufficient: we only ever add a top-level `cache_control`
+    // field to the last block and never mutate nested members (e.g. an image's
+    // `source`). Those nested objects stay shared with the input by reference,
+    // which is safe because they are never written to. If a future block shape
+    // requires mutating nested members, deep-clone that block instead.
+    const content = message.content.map((block) => ({ ...block }));
+    const lastIndex = content.length - 1;
+    content[lastIndex] = { ...content[lastIndex], cache_control: EPHEMERAL };
+    messages[i] = { ...message, content };
+    return true;
+}
+//# sourceMappingURL=anthropicCacheBreakpoints.js.map

package/dist/providers/googleVertex.js

@@ -10,6 +10,7 @@ import { ModelConfigurationManager } from "../core/modelConfiguration.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
 import { ERROR_CODES, NeuroLinkError } from "../utils/errorHandling.js";
+import { applyVertexAnthropicCacheBreakpoints } from "../utils/anthropicCacheBreakpoints.js";
 import { FileDetector } from "../utils/fileDetector.js";
 import { processUnifiedFilesArray } from "../utils/messageBuilder.js";
 import { logger } from "../utils/logger.js";
@@ -2491,9 +2492,27 @@ export class GoogleVertexProvider extends BaseProvider {
                     }, turnContext);
                     let response;
                     try {
+                        // Vertex has no automatic prompt caching — place explicit
+                        // cache_control breakpoints (system, tools, rolling history) so the
+                        // conversation prefix is cached across turns instead of re-billed as
+                        // fresh input every call. Re-applied per step: the stable prefix
+                        // stays byte-identical (consistent cache key) while the rolling
+                        // breakpoint follows the growing tail.
+                        const cachedStream = applyVertexAnthropicCacheBreakpoints({
+                            system: systemPromptWithSchema,
+                            tools,
+                            messages: currentMessages,
+                        });
                         const stream = await client.messages.stream({
                             ...requestParams,
-                            messages: currentMessages,
+                            ...(cachedStream.system !== undefined && {
+                                system: cachedStream.system,
+                            }),
+                            ...(cachedStream.tools &&
+                                cachedStream.tools.length > 0 && {
+                                tools: cachedStream.tools,
+                            }),
+                            messages: cachedStream.messages,
                         });
                         activeStream = stream;
                         // Forward each text delta as it arrives — the Anthropic SDK fires
@@ -2750,6 +2769,17 @@ export class GoogleVertexProvider extends BaseProvider {
                 }
                 metadata.responseTime = Date.now() - startTime;
                 metadata.totalToolExecutions = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
+                // Surface cache metrics once, after the agentic loop, from the
+                // cumulative turnCacheUsage running totals (accumulated via += on every
+                // step above). Assigned here — not per-iteration — so the final values
+                // are unambiguous: analytics sees caching is working and calculateCost
+                // can price the cache-read/write tiers instead of full input rate.
+                if (turnCacheUsage.read > 0) {
+                    usage.cacheReadTokens = turnCacheUsage.read;
+                }
+                if (turnCacheUsage.creation > 0) {
+                    usage.cacheCreationTokens = turnCacheUsage.creation;
+                }
                 const turnOutputAttribute = spanJsonAttribute({
                     text: aggregatedTurnText,
                     ...(structuredOutputRef.value
@@ -3110,6 +3140,12 @@ export class GoogleVertexProvider extends BaseProvider {
         const allToolCalls = [];
         let totalInputTokens = 0;
         let totalOutputTokens = 0;
+        // Cache metrics (Anthropic reports these separately from input_tokens, which
+        // is the uncached remainder). Surfaced on the result so analytics can see
+        // caching is working and calculateCost can price the ~0.1x cache-read /
+        // ~1.25x cache-write tiers instead of billing everything at full input rate.
+        let totalCacheReadTokens = 0;
+        let totalCacheCreationTokens = 0;
         // Track the final Anthropic stop_reason so we can surface finishReason
         // (notably "length" on token truncation) — the legacy native path always
         // reported "stop", hiding truncation from callers.
@@ -3121,13 +3157,36 @@ export class GoogleVertexProvider extends BaseProvider {
                 // Bound the SDK wait so a stalled Vertex/Anthropic call can't hang
                 // generate forever. options.timeout wins if set, otherwise default
                 // to 5 min — generous for tool-heavy turns.
+                // Vertex has no automatic prompt caching — place explicit cache_control
+                // breakpoints (system, tools, rolling history) so the conversation
+                // prefix is cached across turns instead of re-billed as fresh input
+                // every call. Re-applied per step: the stable prefix stays
+                // byte-identical (consistent cache key) while the rolling breakpoint
+                // follows the growing tail.
+                const cachedGenerate = applyVertexAnthropicCacheBreakpoints({
+                    system: systemPromptWithSchema,
+                    tools,
+                    messages: currentMessages,
+                });
                 const response = await withTimeout(client.messages.create({
                     ...requestParams,
-                    messages: currentMessages,
+                    ...(cachedGenerate.system !== undefined && {
+                        system: cachedGenerate.system,
+                    }),
+                    ...(cachedGenerate.tools &&
+                        cachedGenerate.tools.length > 0 && {
+                        tools: cachedGenerate.tools,
+                    }),
+                    messages: cachedGenerate.messages,
                 }), generateTimeoutMs, "Anthropic generate timed out");
-                // Update token counts
+                // Update token counts. input_tokens is the uncached remainder; cache
+                // reads/writes are reported separately and accumulated here so the
+                // result reflects the full picture.
                 totalInputTokens += response.usage?.input_tokens || 0;
                 totalOutputTokens += response.usage?.output_tokens || 0;
+                totalCacheReadTokens += response.usage?.cache_read_input_tokens || 0;
+                totalCacheCreationTokens +=
+                    response.usage?.cache_creation_input_tokens || 0;
                 lastStopReason = response.stop_reason;
                 // Check if we need to handle tool use
                 const toolUseBlocks = response.content.filter((block) => block.type === "tool_use");
@@ -3287,6 +3346,12 @@ export class GoogleVertexProvider extends BaseProvider {
                 input: totalInputTokens,
                 output: totalOutputTokens,
                 total: totalInputTokens + totalOutputTokens,
+                ...(totalCacheReadTokens > 0 && {
+                    cacheReadTokens: totalCacheReadTokens,
+                }),
+                ...(totalCacheCreationTokens > 0 && {
+                    cacheCreationTokens: totalCacheCreationTokens,
+                }),
             },
             responseTime,
             toolsUsed: externalToolCalls.map((tc) => tc.toolName),
@@ -3761,6 +3826,8 @@ export class GoogleVertexProvider extends BaseProvider {
         const inputTokens = usage.input ?? usage.inputTokens ?? 0;
         const outputTokens = usage.output ?? usage.outputTokens ?? 0;
         const totalTokens = usage.total ?? usage.totalTokens ?? inputTokens + outputTokens;
+        const cacheReadTokens = usage.cacheReadTokens ?? 0;
+        const cacheCreationTokens = usage.cacheCreationTokens ?? 0;
         if (inputTokens > 0) {
             span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
         }
@@ -3770,11 +3837,22 @@ export class GoogleVertexProvider extends BaseProvider {
         if (totalTokens > 0) {
             span.setAttribute("gen_ai.usage.total_tokens", totalTokens);
         }
+        if (cacheReadTokens > 0) {
+            span.setAttribute("gen_ai.usage.cache_read_input_tokens", cacheReadTokens);
+        }
+        if (cacheCreationTokens > 0) {
+            span.setAttribute("gen_ai.usage.cache_creation_input_tokens", cacheCreationTokens);
+        }
         try {
+            // Pass cache tokens through so calculateCost prices the ~0.1x cache-read
+            // and ~1.25x cache-write tiers instead of billing cached content at the
+            // full input rate.
             const cost = calculateCost(this.providerName, modelName, {
                 input: inputTokens,
                 output: outputTokens,
                 total: totalTokens,
+                cacheReadTokens,
+                cacheCreationTokens,
             });
             if (typeof cost === "number" && cost > 0) {
                 span.setAttribute("neurolink.cost", cost);

package/dist/types/providers.d.ts

@@ -1797,11 +1797,21 @@ export type VertexGenaiFunctionDeclaration = {
  * Message payload passed to the Anthropic Vertex SDK — mirrors the Anthropic
  * Messages API shape (role + structured content blocks).
  */
+/**
+ * Anthropic ephemeral prompt-cache breakpoint marker. Placed on a content
+ * block / tool / system block to make the rendered prefix up to that point a
+ * cache breakpoint. Vertex has NO automatic caching, so these explicit markers
+ * are the only way the conversation prefix is cached across turns.
+ */
+export type VertexAnthropicCacheControl = {
+    type: "ephemeral";
+};
 export type VertexAnthropicMessage = {
     role: "user" | "assistant";
     content: string | Array<{
         type: "text";
         text: string;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "image";
         source: {
@@ -1809,6 +1819,7 @@ export type VertexAnthropicMessage = {
             media_type: string;
             data: string;
         };
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "document";
         source: {
@@ -1816,23 +1827,38 @@ export type VertexAnthropicMessage = {
             media_type: string;
             data: string;
         };
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "tool_use";
         id: string;
         name: string;
         input: unknown;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "tool_result";
         tool_use_id: string;
         content: string;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "thinking";
         thinking: string;
+        cache_control?: VertexAnthropicCacheControl;
     } | {
         type: "redacted_thinking";
         data: string;
+        cache_control?: VertexAnthropicCacheControl;
     }>;
 };
+/**
+ * System prompt block form accepted by the Anthropic Vertex SDK. Used instead
+ * of a bare string when a `cache_control` breakpoint must ride on the system
+ * prompt (a string `system` cannot carry one).
+ */
+export type VertexAnthropicSystemBlock = {
+    type: "text";
+    text: string;
+    cache_control?: VertexAnthropicCacheControl;
+};
 /** Tool definition accepted by the Anthropic Vertex SDK. */
 export type VertexAnthropicTool = {
     name: string;
@@ -1842,6 +1868,26 @@ export type VertexAnthropicTool = {
         properties?: Record<string, unknown>;
         required?: string[];
     };
+    cache_control?: VertexAnthropicCacheControl;
+};
+/** Input to `applyVertexAnthropicCacheBreakpoints`. */
+export type VertexAnthropicCacheInput = {
+    system?: string;
+    tools?: VertexAnthropicTool[];
+    messages: VertexAnthropicMessage[];
+    /**
+     * Cap on how many of the most-recent messages receive a rolling history
+     * breakpoint. Defaults to "use the remaining budget". Two or more gives
+     * cross-turn continuity and resilience against Anthropic's 20-block cache
+     * lookback window on tool-heavy turns.
+     */
+    maxHistoryBreakpoints?: number;
+};
+/** Output of `applyVertexAnthropicCacheBreakpoints` — a cache-annotated request. */
+export type VertexAnthropicCacheOutput = {
+    system?: string | VertexAnthropicSystemBlock[];
+    tools?: VertexAnthropicTool[];
+    messages: VertexAnthropicMessage[];
 };
 /**
  * Content block variants returned by the Anthropic Vertex SDK during streaming

package/dist/utils/anthropicCacheBreakpoints.d.ts

@@ -0,0 +1,15 @@
+import type { VertexAnthropicCacheInput, VertexAnthropicCacheOutput } from "../types/index.js";
+/**
+ * Annotate a native Vertex+Claude request with prompt-cache breakpoints.
+ *
+ * Budget allocation (max 4 markers):
+ *   1. The stable prefix — the last system block when a system prompt is
+ *      present (this single marker caches `tools + system`, since system
+ *      renders after tools); otherwise the last tool definition.
+ *   2-4. A rolling breakpoint on the last few messages, so the
+ *      growing-but-now-stable conversation history is cached and only the
+ *      newest turn is billed as fresh input.
+ *
+ * Pure: the inputs are cloned, never mutated.
+ */
+export declare function applyVertexAnthropicCacheBreakpoints(input: VertexAnthropicCacheInput): VertexAnthropicCacheOutput;