@salesforce/sfdx-agent-harness-mastra 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.31.0] - 2026-07-08
+
+### Fixes
+- **agent-sdk,harness-mastra,harness-claude**: canonical role:tool placement for completed tool calls @W-23351939 ([#649](https://github.com/forcedotcom/agentic-dx/pull/649))
+
+## [0.30.0] - 2026-07-07
+
+### Fixes
+- **harness-mastra**: getMessages() round-trips the tool-call part @W-23351939 ([#648](https://github.com/forcedotcom/agentic-dx/pull/648))
+
+### Chores
+- **deps**: bump the mastra group across 1 directory with 5 updates ([#644](https://github.com/forcedotcom/agentic-dx/pull/644))
+- **deps**: bump @anthropic-ai/bedrock-sdk from 0.31.0 to 0.32.0 ([#645](https://github.com/forcedotcom/agentic-dx/pull/645))
+- **deps-dev**: bump the dev-dependencies group with 3 updates ([#642](https://github.com/forcedotcom/agentic-dx/pull/642))
+
 ## [0.29.0] - 2026-07-03
 
 _No changes — released alongside dependent packages._

package/dist/mastra-harness.js

@@ -12,7 +12,7 @@ import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, RequestContext } from '@m
 import { LibSQLStore } from '@mastra/libsql';
 import { MCPClient } from '@mastra/mcp';
 import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, resolveToolApprovalMode, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
-import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, } from '@salesforce/sfdx-agent-sdk/harness';
+import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, mergeToolResultsIntoAssistant, splitToolResultsIntoToolMessages, } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import { MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 import { SKILL_SEARCH_META_TOOL_NAMES, TOOL_SEARCH_META_TOOL_NAMES } from './skill-bridge.js';
@@ -1619,9 +1619,16 @@ export class MastraHarness {
         // silently bucket null-timestamp rows at epoch and propagate
         // `undefined` to consumers.
         let lastFallback = this.clock.now();
-        return messages
-            .filter((m) => m.role !== 'signal')
-            .map((m) => mapMastraToMessage(m, logBus))
+        const mapped = messages.filter((m) => m.role !== 'signal').map((m) => mapMastraToMessage(m, logBus));
+        // Hoist every completed tool call's `tool-result` part onto its own
+        // `role: 'tool'` message so the consumer-visible layout matches the
+        // cross-harness `getMessages` contract (assistant carries the
+        // `tool-call`; a separate tool message carries the paired result). The
+        // shared normalizer is the single site both harnesses use so the layout
+        // can't drift. Runs before the createdAt backfill so the synthesized tool
+        // messages (which inherit their source's `createdAt`, possibly undefined)
+        // still get a populated timestamp and slot correctly in the sort.
+        return splitToolResultsIntoToolMessages(mapped)
             .map((m) => {
             if (m.createdAt)
                 return m;
@@ -1661,7 +1668,15 @@ export class MastraHarness {
         // record (Mastra's libsql column is non-nullable). Routes through the
         // shared `backfillCreatedAt` helper from `agentic-common` so the SDK
         // and both harnesses can't drift on the per-position step policy.
-        const filled = backfillCreatedAt(messages, this.clock);
+        // Fold any canonical `role: 'tool'` message's result back adjacent to
+        // its `tool-call` in the preceding assistant message (the inverse of the
+        // `splitToolResultsIntoToolMessages` hoist `getMessages` applies). This
+        // recreates the adjacency `mapMessageToMastra` coalesces into a single
+        // `tool-invocation(result)`, so a `getMessages()` → `addContext()`
+        // round-trip stays lossless and never double-stores the call. A no-op for
+        // history that carries no tool messages.
+        const merged = mergeToolResultsIntoAssistant(messages);
+        const filled = backfillCreatedAt(merged, this.clock);
         const mapped = filled.map((m) => mapMessageToMastra(m, threadId, resourceId));
         await memory.saveMessages({ messages: mapped });
     }

package/dist/mastra-message-mapper.d.ts

@@ -15,13 +15,23 @@ import type { LogBus } from '@salesforce/agentic-common';
  */
 export declare function mapMastraToMessage(msg: MastraDBMessage, logBus?: LogBus): Message;
 /**
- * Converts a single Mastra message part to the SDK {@link MessagePart} equivalent.
- * Returns `undefined` for part types that exist in Mastra but have no SDK representation.
+ * Converts a single Mastra message part to zero or more SDK {@link MessagePart}s.
+ *
+ * Most Mastra parts map one-to-one, but a **completed** `tool-invocation` maps to
+ * *two* SDK parts — a `tool-call` (name + args) followed by a `tool-result` — because
+ * a single Mastra object carries both halves once its `state` transitions to `'result'`.
+ * Emitting both keeps `getMessages()` history harness-agnostic: the model's original
+ * tool call (name + args) survives on read exactly as it does on the Claude harness,
+ * which stores the call and result as distinct blocks (#647). Returning an array is what
+ * lets one input part expand to two output parts without a special case in the caller.
+ *
+ * Returns an empty array for part types that exist in Mastra but have no SDK
+ * representation (e.g. `source`, `step-start`, `partial-call`, `data-*`).
  *
  * @param logBus - When supplied, unrecognized part types emit a `warn` log via this bus.
  *   Tests that don't care about logging can omit it.
  */
-export declare function mapMastraPartToMessagePart(part: MastraMessagePart, logBus?: LogBus): MessagePart | undefined;
+export declare function mapMastraPartToMessagePart(part: MastraMessagePart, logBus?: LogBus): MessagePart[];
 /**
  * Converts an SDK {@link Message} into the Mastra persisted message format.
  * The `role` field is normalised: `'tool'` role (which has no Mastra equivalent)

package/dist/mastra-message-mapper.js

@@ -29,6 +29,33 @@ function formatApproxSize(base64Data) {
         return `${kib.toFixed(1)} KB`;
     return `${(kib / 1024).toFixed(1)} MB`;
 }
+/**
+ * Builds the single Mastra `tool-invocation` part that represents a completed
+ * tool call, carrying both the original `args` and the outcome. A successful
+ * result maps to `state: 'result'` with `result`; an errored result
+ * (`isError: true`) maps to `state: 'output-error'` — Mastra's native shape for
+ * a failed invocation. For the error case both the structured `result` AND a
+ * stringified `errorText` are written: the read mapper prefers `result` so a
+ * non-string error payload round-trips as an object, and `errorText` is Mastra's
+ * native error slot (used as the fallback for natively-persisted error
+ * invocations that carry only that). This is the write-side counterpart of the
+ * `mapMastraPartToMessagePart` expansion, so an errored tool result survives a
+ * `getMessages()` → `addContext()` round-trip with its `isError` flag and its
+ * `result` structure intact (the cross-harness `isError` contract, #647).
+ */
+function buildCompletedToolInvocation(toolCallId, toolName, args, result) {
+    if (result.isError === true) {
+        const errorText = typeof result.result === 'string' ? result.result : JSON.stringify(result.result);
+        return {
+            type: 'tool-invocation',
+            toolInvocation: { state: 'output-error', toolCallId, toolName, args, result: result.result, errorText },
+        };
+    }
+    return {
+        type: 'tool-invocation',
+        toolInvocation: { state: 'result', toolCallId, toolName, args, result: result.result },
+    };
+}
 /**
  * Converts a Mastra persisted message into the SDK's {@link Message} type.
  *
@@ -47,10 +74,7 @@ export function mapMastraToMessage(msg, logBus) {
     }
     const parts = [];
     for (const part of msg.content.parts) {
-        const mapped = mapMastraPartToMessagePart(part, logBus);
-        if (mapped) {
-            parts.push(mapped);
-        }
+        parts.push(...mapMastraPartToMessagePart(part, logBus));
     }
     const consolidated = consolidateAdjacentTextParts(parts);
     const isSingleText = consolidated.length === 1 && consolidated[0].type === 'text';
@@ -85,8 +109,18 @@ function consolidateAdjacentTextParts(parts) {
     return result;
 }
 /**
- * Converts a single Mastra message part to the SDK {@link MessagePart} equivalent.
- * Returns `undefined` for part types that exist in Mastra but have no SDK representation.
+ * Converts a single Mastra message part to zero or more SDK {@link MessagePart}s.
+ *
+ * Most Mastra parts map one-to-one, but a **completed** `tool-invocation` maps to
+ * *two* SDK parts — a `tool-call` (name + args) followed by a `tool-result` — because
+ * a single Mastra object carries both halves once its `state` transitions to `'result'`.
+ * Emitting both keeps `getMessages()` history harness-agnostic: the model's original
+ * tool call (name + args) survives on read exactly as it does on the Claude harness,
+ * which stores the call and result as distinct blocks (#647). Returning an array is what
+ * lets one input part expand to two output parts without a special case in the caller.
+ *
+ * Returns an empty array for part types that exist in Mastra but have no SDK
+ * representation (e.g. `source`, `step-start`, `partial-call`, `data-*`).
  *
  * @param logBus - When supplied, unrecognized part types emit a `warn` log via this bus.
  *   Tests that don't care about logging can omit it.
@@ -94,60 +128,98 @@ function consolidateAdjacentTextParts(parts) {
 export function mapMastraPartToMessagePart(part, logBus) {
     switch (part.type) {
         case 'text':
-            return { type: 'text', text: part.text };
+            return [{ type: 'text', text: part.text }];
         case 'reasoning':
-            return { type: 'reasoning', text: part.reasoning };
+            return [{ type: 'reasoning', text: part.reasoning }];
         case 'tool-invocation': {
             const inv = part.toolInvocation;
             if (inv.state === 'partial-call') {
-                return undefined;
-            }
-            if (inv.state === 'result') {
-                return {
-                    type: 'tool-result',
-                    toolCallId: inv.toolCallId,
-                    toolName: inv.toolName,
-                    result: inv.result,
-                };
+                return [];
             }
-            return {
+            const toolCall = {
                 type: 'tool-call',
                 toolCallId: inv.toolCallId,
                 toolName: inv.toolName,
-                args: inv.args,
+                args: (inv.args ?? {}),
             };
+            // A completed invocation carries both the original call (name + args)
+            // and its outcome; surface both so history round-trips the call the
+            // model made, not just its result. Mastra models a completed call in
+            // three states: `result` (success) and `output-error` / `output-denied`
+            // (failure). All three expand to a tool-call + tool-result pair; the
+            // two error states set `isError: true`, matching the SDK
+            // `ToolResultPart` shape and the cross-harness `isError` round-trip
+            // contract (#647). The shared `splitToolResultsIntoToolMessages`
+            // normalizer (run in `getMessages`) then hoists the tool-result onto
+            // its own `role: 'tool'` message.
+            //
+            // KNOWN BEHAVIOR: a completed invocation always carries `args` (the
+            // model's real call), so the expanded `tool-call` reflects what the
+            // model actually invoked. The one exception is inconsistent history a
+            // consumer hand-constructs via `addContext` — a lone `role: 'tool'`
+            // result with no matching `tool-call`. `mergeToolResultsIntoAssistant`
+            // can't fold it (no call to attach to), so it persists as a standalone
+            // `tool-invocation(result)` with `args: {}`, and this read then
+            // fabricates a `tool-call` with those empty args. The SDK never emits
+            // that shape itself; it's an accepted edge of accepting arbitrary
+            // caller-supplied history.
+            if (inv.state === 'result') {
+                return [
+                    toolCall,
+                    { type: 'tool-result', toolCallId: inv.toolCallId, toolName: inv.toolName, result: inv.result },
+                ];
+            }
+            if (inv.state === 'output-error' || inv.state === 'output-denied') {
+                // Prefer the structured `result` (the write path preserves it
+                // alongside `errorText`) so a non-string error payload round-trips
+                // as an object, not a JSON string; fall back to `errorText` for
+                // natively-persisted error invocations that carry only that.
+                return [
+                    toolCall,
+                    {
+                        type: 'tool-result',
+                        toolCallId: inv.toolCallId,
+                        toolName: inv.toolName,
+                        result: inv.result ?? inv.errorText,
+                        isError: true,
+                    },
+                ];
+            }
+            // `call`, `approval-requested`, `approval-responded`: the call was
+            // made but has no outcome yet — surface the tool-call alone.
+            return [toolCall];
         }
         case 'file': {
             // Read path: base64 data is returned verbatim from LibSQL — see ARCHITECTURE.md → "Memory Strategy"
             // for the storage-cost caveat (no blob offloading; full encoded size per attachment per row).
             const fileName = readSalesforceFileName(part.providerMetadata);
             if (part.mimeType === 'image/png' || part.mimeType === 'image/jpeg') {
-                return { type: 'image', mimeType: part.mimeType, data: part.data, ...(fileName ? { fileName } : {}) };
+                return [{ type: 'image', mimeType: part.mimeType, data: part.data, ...(fileName ? { fileName } : {}) }];
             }
             if (part.mimeType === 'application/pdf') {
-                return { type: 'file', mimeType: part.mimeType, data: part.data, ...(fileName ? { fileName } : {}) };
+                return [{ type: 'file', mimeType: part.mimeType, data: part.data, ...(fileName ? { fileName } : {}) }];
             }
             logBus?.warn('Skipping file MastraMessagePart with unsupported mimeType; omitted from message history', {
                 mimeType: part.mimeType,
                 hint: 'Only image/png, image/jpeg, and application/pdf map to SDK message parts.',
             });
-            return undefined;
+            return [];
         }
         // Part types that exist in Mastra but have no SDK equivalent yet.
         case 'source':
         case 'step-start':
-            return undefined;
+            return [];
         default:
             // AI SDK v5 data parts use a `data-*` type prefix for framework-specific
             // metadata (e.g. workspace info). These are harness-internal and expected.
             if (part.type.startsWith('data-')) {
-                return undefined;
+                return [];
             }
             logBus?.warn('Skipping unrecognized MastraMessagePart; omitted from message history', {
                 partType: part.type,
                 hint: 'Update mapMastraPartToMessagePart to handle this type if it should be mapped.',
             });
-            return undefined;
+            return [];
     }
 }
 /**
@@ -161,7 +233,22 @@ export function mapMessageToMastra(msg, threadId, resourceId) {
         parts.push({ type: 'text', text: msg.content });
     }
     else {
-        for (const part of msg.content) {
+        const content = msg.content;
+        for (let i = 0; i < content.length; i++) {
+            const part = content[i];
+            const next = content[i + 1];
+            // Coalesce an adjacent tool-call + tool-result for the same toolCallId
+            // into ONE Mastra `tool-invocation(result)` carrying both `args` and
+            // `result`. This mirrors how Mastra natively persists a completed call
+            // (its MessageList merges the call and result into a single object) and
+            // is the exact inverse of the read-path expansion in
+            // `mapMastraPartToMessagePart`, so a `getMessages()` → `addContext()`
+            // round-trip is lossless and never double-counts the call (#647).
+            if (part.type === 'tool-call' && next?.type === 'tool-result' && next.toolCallId === part.toolCallId) {
+                parts.push(buildCompletedToolInvocation(part.toolCallId, part.toolName, part.args, next));
+                i++; // consumed the paired tool-result
+                continue;
+            }
             parts.push(mapMessagePartToMastra(part));
         }
     }
@@ -212,16 +299,7 @@ export function mapMessagePartToMastra(part) {
                 },
             };
         case 'tool-result':
-            return {
-                type: 'tool-invocation',
-                toolInvocation: {
-                    state: 'result',
-                    toolCallId: part.toolCallId,
-                    toolName: part.toolName,
-                    args: {},
-                    result: part.result,
-                },
-            };
+            return buildCompletedToolInvocation(part.toolCallId, part.toolName, {}, part);
         case 'image':
         case 'file':
             // Mastra persists a single `file` UIMessage part for both. The SDK's `fileName` has no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -29,22 +29,22 @@
   ],
   "dependencies": {
     "@ai-sdk/provider": "^3.0.10",
-    "@anthropic-ai/bedrock-sdk": "^0.31.0",
+    "@anthropic-ai/bedrock-sdk": "^0.32.0",
     "@anthropic-ai/sdk": "^0.106.0",
-    "@mastra/core": "^1.47.0",
-    "@mastra/libsql": "^1.14.2",
-    "@mastra/mcp": "^1.10.0",
-    "@mastra/memory": "^1.21.2",
+    "@mastra/core": "^1.49.0",
+    "@mastra/libsql": "^1.15.0",
+    "@mastra/mcp": "^1.13.0",
+    "@mastra/memory": "^1.22.1",
     "@mastra/schema-compat": "^1.2.11",
     "@salesforce/agentic-common": "0.13.0",
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.30.0"
+    "@salesforce/sfdx-agent-sdk": "0.32.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.30.0",
+    "@salesforce/sfdx-agent-sdk": "0.32.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.20",
@@ -55,11 +55,11 @@
     "eslint-plugin-n": "^18.2.1",
     "globals": "^17.6.0",
     "lint-staged": "^17.0.7",
-    "prettier": "^3.9.0",
+    "prettier": "^3.9.4",
     "rimraf": "^6.1.3",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.0",
+    "typescript-eslint": "^8.62.1",
     "vitest": "^4.1.8"
   },
   "engines": {