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

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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
+- add ChatSession.cancelTurn() with abort-persistence barrier @W-23559264@ ([#810](https://github.com/forcedotcom/agentic-dx/pull/810))
+
 ## [0.77.0] - 2026-09-09
 
 _No changes — released alongside dependent packages._

package/dist/mastra-approval-coordinator.js

@@ -275,7 +275,9 @@ export class MastraApprovalCoordinator {
         this.aborted = true;
         const abortError = new Error('The stream was aborted.');
         abortError.name = 'AbortError';
-        this.teardown('abort', abortError, 'aborted');
+        // Canonical cancellation code across harnesses (was harness-specific
+        // `'aborted'`): the abort teardown ends the turn with `finish('cancelled')`.
+        this.teardown('abort', abortError, 'cancelled');
     }
     dispose() {
         if (this.disposed)
@@ -357,8 +359,12 @@ export class MastraApprovalCoordinator {
         const resolve = this.continuationResolver;
         this.continuationResolver = undefined;
         resolve?.('done');
+        // A cancellation (abort) ends the turn with `finish('cancelled')`, never
+        // `error` — the terminal reason a cancelled turn surfaces per the SDK
+        // contract. Every other teardown reason stays `error`.
+        const finishReason = reason === 'abort' ? 'cancelled' : 'error';
         this.initial.push({ type: 'error', error, code });
-        this.initial.push({ type: 'finish', finishReason: 'error' });
+        this.initial.push({ type: 'finish', finishReason });
         this.initial.end();
         this.pendingSuspendIds.clear();
         this.runTeardownCallbacks();

package/dist/mastra-harness.d.ts

@@ -1,7 +1,7 @@
 import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { MCPClient } from '@mastra/mcp';
-import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type McpAuthProviders, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolDeclineReason, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import { McpServerStatus, type AgentHarness, type WithAgentConfig, type HarnessStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type McpAuthProviders, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolDeclineReason, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import type { MastraLanguageModelBuilderContext } from './index.js';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
@@ -520,7 +520,8 @@ export declare class MastraHarness implements MastraAgentHarness {
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST invoke `agent.stream()` with memory context for the thread.
      * - MUST capture the `runId` for tool approval flows.
-     * - MUST return a `ChatStreamResult` with `textStream` and `eventStream`.
+     * - MUST return a `HarnessStreamResult` with `textStream`, `eventStream`, and the `settled`
+     *   barrier (coordinator sink ended + Mastra transcript save flushed) for `cancelTurn()`.
      * - On pre-stream rejection from `agent.stream()`, MUST re-throw without emitting telemetry —
      *   the SDK's chat-session boundary catches the rejection and emits `chat-stream-error`.
      * - MUST install a per-run abort listener on `options.abortSignal` so that aborting
@@ -571,7 +572,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      * harness; this method only supplies the Mastra-specific lowering of each part.
      */
     private toMastraStreamInput;
-    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
+    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<HarnessStreamResult>;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.

package/dist/mastra-harness.js

@@ -1648,7 +1648,8 @@ export class MastraHarness {
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST invoke `agent.stream()` with memory context for the thread.
      * - MUST capture the `runId` for tool approval flows.
-     * - MUST return a `ChatStreamResult` with `textStream` and `eventStream`.
+     * - MUST return a `HarnessStreamResult` with `textStream`, `eventStream`, and the `settled`
+     *   barrier (coordinator sink ended + Mastra transcript save flushed) for `cancelTurn()`.
      * - On pre-stream rejection from `agent.stream()`, MUST re-throw without emitting telemetry —
      *   the SDK's chat-session boundary catches the rejection and emits `chat-stream-error`.
      * - MUST install a per-run abort listener on `options.abortSignal` so that aborting
@@ -1845,9 +1846,21 @@ export class MastraHarness {
             }
         }
         coordinator.start({ runId: output.runId, fullStream: output.fullStream });
+        // Settle barrier for `ChatSession.cancelTurn()`: resolves only once the
+        // coordinator's per-turn sink has ended (natural finish or abort teardown)
+        // AND Mastra's own stream completion has flushed — its `onFinish` / LibSQL
+        // transcript save runs on natural finish and, since `@mastra/core >= 1.62`,
+        // on abort too (W-24001006). Awaiting `output.finishReason` waits out that
+        // save; it never rejects the barrier (an aborted turn is over either way).
+        const coordinatorSettled = new Promise((resolve) => coordinator.onTeardown(resolve));
+        // `Promise.resolve(...)` tolerates a test-stub output with no `finishReason`
+        // (production `MastraModelOutput` always exposes the promise).
+        const persistenceFlushed = Promise.resolve(output.finishReason).then(() => undefined, () => undefined);
+        const settled = Promise.all([coordinatorSettled, persistenceFlushed]).then(() => undefined);
         return {
             eventStream: coordinator.initialSink().generator(),
             textStream: this.readableStreamToAsyncGenerator(output.textStream),
+            settled,
         };
     }
     // ── Tool Execution ───────────────────────────────────────────────

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.77.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.78.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.78.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",