@salesforce/sfdx-agent-harness-mastra 0.30.0 → 0.31.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.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

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.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.
  *
@@ -115,15 +142,51 @@ export function mapMastraPartToMessagePart(part, logBus) {
                 toolName: inv.toolName,
                 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') {
-                // A completed invocation carries both the original call (name + args)
-                // and its result; surface both so history round-trips the call the
-                // model made, not just its outcome.
                 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': {
@@ -182,16 +245,7 @@ export function mapMessageToMastra(msg, threadId, resourceId) {
             // `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({
-                    type: 'tool-invocation',
-                    toolInvocation: {
-                        state: 'result',
-                        toolCallId: part.toolCallId,
-                        toolName: part.toolName,
-                        args: part.args,
-                        result: next.result,
-                    },
-                });
+                parts.push(buildCompletedToolInvocation(part.toolCallId, part.toolName, part.args, next));
                 i++; // consumed the paired tool-result
                 continue;
             }
@@ -245,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.30.0",
+  "version": "0.31.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -40,11 +40,11 @@
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.31.0"
+    "@salesforce/sfdx-agent-sdk": "0.32.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.31.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",