@salesforce/sfdx-agent-harness-mastra 0.78.0 → 0.79.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to `@salesforce/sfdx-agent-harness-mastra` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.79.0] - 2026-09-14
+
+### Fixes
+- **harness-mastra**: stamp Anthropic cache_control in the Mastra pass-through @W-24130072@ ([#811](https://github.com/forcedotcom/agentic-dx/pull/811))
+
 ## [0.78.0] - 2026-09-14
 
 ### Features

package/dist/pass-through-anthropic.d.ts

@@ -105,6 +105,19 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
 }): LanguageModelV3;
+/**
+ * Stamps `cache_control: {type:'ephemeral'}` on up to three of Anthropic's four
+ * allowed breakpoints: the last tool (caches the constant tools block), the
+ * system prompt (sent as a `text` block carrying the breakpoint), and a
+ * rolling breakpoint on the last cache-eligible block of the last message —
+ * the growing history is the majority of per-step input on a multi-step turn,
+ * so this breakpoint is load-bearing, not incidental: dropping it would leave
+ * only the turn-constant tools/system cached and forfeit most of the win.
+ * Mutates only `commonParams`'s own arrays — which
+ * `translate*ToAnthropic` builds fresh per request — never the caller's
+ * original `LanguageModelV3` prompt/tool objects.
+ */
+export declare function applyCacheBreakpoints(commonParams: Omit<Anthropic.Messages.MessageCreateParamsStreaming, 'stream'>): void;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into Anthropic's Messages API shape
  * — top-level `system` string + `MessageParam[]` of role-tagged content blocks.

package/dist/pass-through-anthropic.js

@@ -177,8 +177,76 @@ async function buildAnthropicRequest(ctx, options) {
     }
     if (options.stopSequences !== undefined)
         commonParams.stop_sequences = [...options.stopSequences];
+    // Anthropic caching is opt-in per request (unlike OpenAI's automatic
+    // prefix cache) — nothing caches without an explicit `cache_control`
+    // breakpoint. `Model.supportsPromptCache` is the gate (`true` for the
+    // Claude family, `false` for GPT); see `applyCacheBreakpoints`.
+    if (info.model.supportsPromptCache && !isPromptCacheKillSwitchEngaged())
+        applyCacheBreakpoints(commonParams);
     return { client, commonParams, toolSchemas };
 }
+/**
+ * Internal, undocumented escape hatch — NOT a consumer-facing `AgentConfig`
+ * field or a documented environment variable. Exists solely so an operator can
+ * disable cache-control stamping process-wide if a provider-side caching bug
+ * surfaces in production, without a code rollback. Read fresh on every request
+ * (not cached) so it can be flipped at runtime.
+ */
+function isPromptCacheKillSwitchEngaged() {
+    return process.env['SF_MASTRA_DISABLE_PROMPT_CACHE'] === 'true';
+}
+/** Content-block types that accept `cache_control` on the Anthropic Messages
+ * API. Deliberately excludes `thinking` / `redacted_thinking`, which reject it. */
+const CACHE_ELIGIBLE_BLOCK_TYPES = new Set([
+    'text',
+    'tool_use',
+    'tool_result',
+    'image',
+    'document',
+]);
+/** Shared marker object stamped onto up to 3 locations per request, reused
+ * across every request and every agent for the process lifetime — never
+ * mutate this in place; construct a new object if a call site ever needs a
+ * different breakpoint shape (e.g. a `ttl`). */
+const CACHE_CONTROL_EPHEMERAL = Object.freeze({ type: 'ephemeral' });
+/**
+ * Stamps `cache_control: {type:'ephemeral'}` on up to three of Anthropic's four
+ * allowed breakpoints: the last tool (caches the constant tools block), the
+ * system prompt (sent as a `text` block carrying the breakpoint), and a
+ * rolling breakpoint on the last cache-eligible block of the last message —
+ * the growing history is the majority of per-step input on a multi-step turn,
+ * so this breakpoint is load-bearing, not incidental: dropping it would leave
+ * only the turn-constant tools/system cached and forfeit most of the win.
+ * Mutates only `commonParams`'s own arrays — which
+ * `translate*ToAnthropic` builds fresh per request — never the caller's
+ * original `LanguageModelV3` prompt/tool objects.
+ */
+export function applyCacheBreakpoints(commonParams) {
+    const tools = commonParams.tools;
+    if (tools !== undefined && tools.length > 0) {
+        const lastTool = tools[tools.length - 1];
+        if (lastTool !== undefined)
+            lastTool.cache_control = CACHE_CONTROL_EPHEMERAL;
+    }
+    if (typeof commonParams.system === 'string') {
+        commonParams.system = [{ type: 'text', text: commonParams.system, cache_control: CACHE_CONTROL_EPHEMERAL }];
+    }
+    else if (Array.isArray(commonParams.system) && commonParams.system.length > 0) {
+        commonParams.system[commonParams.system.length - 1].cache_control = CACHE_CONTROL_EPHEMERAL;
+    }
+    const lastMessage = commonParams.messages[commonParams.messages.length - 1];
+    const content = lastMessage?.content;
+    if (Array.isArray(content)) {
+        for (let i = content.length - 1; i >= 0; i--) {
+            const block = content[i];
+            if (block !== undefined && CACHE_ELIGIBLE_BLOCK_TYPES.has(block.type)) {
+                block.cache_control =
+                    CACHE_CONTROL_EPHEMERAL;
+                break;
+            }
+        }
+    }
+}
 async function doGenerate(ctx, options) {
     const { client, commonParams, toolSchemas } = await buildAnthropicRequest(ctx, options);
     // Forward the turn's AbortSignal into the SDK's RequestOptions so firing the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -42,12 +42,12 @@
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.79.0"
+    "@salesforce/sfdx-agent-sdk": "0.80.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.79.0",
+    "@salesforce/sfdx-agent-sdk": "0.80.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",