@salesforce/sfdx-agent-harness-mastra 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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.19.0] - 2026-06-12
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude**: add tool-call-delta ChatEvent for streaming tool-call args @W-22965697@ ([#597](https://github.com/forcedotcom/agentic-dx/pull/597))
+- **agent-sdk,harness-mastra,harness-claude**: add tool-progress ChatEvent variant @W-22951127@ ([#594](https://github.com/forcedotcom/agentic-dx/pull/594))
+
+### Fixes
+- **harness-claude**: map SDKResultSuccess.is_error to ChatEvent.error ([#593](https://github.com/forcedotcom/agentic-dx/pull/593))
+
 ## [0.18.0] - 2026-06-11
 
 ### Fixes

package/dist/mastra-approval-coordinator.d.ts

@@ -142,6 +142,29 @@ export declare class MastraApprovalCoordinator {
      * `agent.approveToolCall(...)` / `declineToolCall(...)`.
      */
     private currentRunId;
+    /**
+     * `toolCallId` of the MCP tool call currently in-flight on this turn,
+     * or `null` when no MCP tool is awaiting a result. Tracked at
+     * `routeEnriched` time: set when a MCP-namespaced `tool-call` arrives,
+     * cleared on the matching `tool-result`.
+     *
+     * Used by {@link emitMcpProgress} to attribute incoming
+     * `notifications/progress` (which only carry a `progressToken`) to the
+     * right `toolCallId` for the `tool-progress` ChatEvent.
+     *
+     * Mastra serializes MCP tool execution per workflow step, so at most
+     * one MCP tool call is in flight per coordinator at any time —
+     * matching the "currentMcpToolCallId" field's scalar shape.
+     */
+    private currentMcpToolCallId;
+    /**
+     * Captures the (Mastra-namespaced) tool name for each `toolCallId`
+     * routed through `routeEnriched`. Used by {@link emitMcpProgress} to
+     * stamp `toolName` on the `tool-progress` ChatEvent so AG-UI Activity
+     * translators don't have to consult the originating `tool-call` event
+     * to route progress chunks.
+     */
+    private readonly toolNameForCallId;
     /**
      * ToolCallIds Mastra is currently suspended on. Mastra retains a separate
      * workflow snapshot step per id, so the pump must drive one resume per
@@ -175,6 +198,33 @@ export declare class MastraApprovalCoordinator {
     private timedOut;
     constructor(opts: MastraApprovalCoordinatorOptions);
     initialSink(): GenSink<ChatEvent>;
+    /**
+     * Mastra's current run id. The harness's MCP-progress dispatcher uses
+     * this to filter incoming `notifications/progress` to the coordinator
+     * whose run produced the originating tool call (the upstream server
+     * received the progressToken Mastra injected from `context.runId`).
+     */
+    getCurrentRunId(): string;
+    /**
+     * Issue #591: dispatch an MCP `notifications/progress` notification
+     * received via `mcpClient.progress.onUpdate(...)` to the consumer's
+     * eventStream as a `tool-progress` ChatEvent.
+     *
+     * Caller (the harness MCP-progress listener) is responsible for
+     * filtering by `progressToken === coordinator.getCurrentRunId()` so this
+     * method only sees notifications belonging to its own turn.
+     *
+     * Drops the notification (no event surfaced) when no MCP tool call is
+     * currently in flight — the only path that produces `currentMcpToolCallId
+     * === null` after a turn started is "progress arrived after the matching
+     * tool-result." Losing a stragglier is preferable to surfacing a
+     * progress event without a meaningful toolCallId.
+     */
+    emitMcpProgress(params: {
+        progress: number;
+        total?: number;
+        message?: string;
+    }): void;
     onTeardown(callback: () => void): void;
     private runTeardownCallbacks;
     /**

package/dist/mastra-approval-coordinator.js

@@ -78,6 +78,29 @@ export class MastraApprovalCoordinator {
      * `agent.approveToolCall(...)` / `declineToolCall(...)`.
      */
     currentRunId = '';
+    /**
+     * `toolCallId` of the MCP tool call currently in-flight on this turn,
+     * or `null` when no MCP tool is awaiting a result. Tracked at
+     * `routeEnriched` time: set when a MCP-namespaced `tool-call` arrives,
+     * cleared on the matching `tool-result`.
+     *
+     * Used by {@link emitMcpProgress} to attribute incoming
+     * `notifications/progress` (which only carry a `progressToken`) to the
+     * right `toolCallId` for the `tool-progress` ChatEvent.
+     *
+     * Mastra serializes MCP tool execution per workflow step, so at most
+     * one MCP tool call is in flight per coordinator at any time —
+     * matching the "currentMcpToolCallId" field's scalar shape.
+     */
+    currentMcpToolCallId = null;
+    /**
+     * Captures the (Mastra-namespaced) tool name for each `toolCallId`
+     * routed through `routeEnriched`. Used by {@link emitMcpProgress} to
+     * stamp `toolName` on the `tool-progress` ChatEvent so AG-UI Activity
+     * translators don't have to consult the originating `tool-call` event
+     * to route progress chunks.
+     */
+    toolNameForCallId = new Map();
     /**
      * ToolCallIds Mastra is currently suspended on. Mastra retains a separate
      * workflow snapshot step per id, so the pump must drive one resume per
@@ -123,6 +146,43 @@ export class MastraApprovalCoordinator {
     initialSink() {
         return this.initial;
     }
+    /**
+     * Mastra's current run id. The harness's MCP-progress dispatcher uses
+     * this to filter incoming `notifications/progress` to the coordinator
+     * whose run produced the originating tool call (the upstream server
+     * received the progressToken Mastra injected from `context.runId`).
+     */
+    getCurrentRunId() {
+        return this.currentRunId;
+    }
+    /**
+     * Issue #591: dispatch an MCP `notifications/progress` notification
+     * received via `mcpClient.progress.onUpdate(...)` to the consumer's
+     * eventStream as a `tool-progress` ChatEvent.
+     *
+     * Caller (the harness MCP-progress listener) is responsible for
+     * filtering by `progressToken === coordinator.getCurrentRunId()` so this
+     * method only sees notifications belonging to its own turn.
+     *
+     * Drops the notification (no event surfaced) when no MCP tool call is
+     * currently in flight — the only path that produces `currentMcpToolCallId
+     * === null` after a turn started is "progress arrived after the matching
+     * tool-result." Losing a stragglier is preferable to surfacing a
+     * progress event without a meaningful toolCallId.
+     */
+    emitMcpProgress(params) {
+        if (this.aborted || this.disposed)
+            return;
+        const toolCallId = this.currentMcpToolCallId;
+        if (!toolCallId)
+            return;
+        this.initial.push({
+            type: 'tool-progress',
+            toolCallId,
+            toolName: this.toolNameForCallId.get(toolCallId) ?? 'unknown',
+            output: { ...params },
+        });
+    }
     onTeardown(callback) {
         if (this.aborted || this.disposed) {
             queueMicrotask(callback);
@@ -548,6 +608,21 @@ export class MastraApprovalCoordinator {
         if (this.aborted || this.disposed)
             return;
         const enriched = this.maybeEnrich(event);
+        // Issue #591: track in-flight MCP tool call so progress notifications
+        // arriving via `progress.onUpdate(...)` can be attributed to the
+        // right `toolCallId`. Set on enriched (i.e. MCP-namespaced) tool-call;
+        // cleared on the matching tool-result. Non-MCP tools don't carry
+        // `serverName` (the lookup returns undefined) so this never fires
+        // for built-ins, consumer-declared tools, or workspace tools.
+        if (enriched.type === 'tool-call' && enriched.serverName !== undefined) {
+            this.currentMcpToolCallId = enriched.toolCallId;
+            this.toolNameForCallId.set(enriched.toolCallId, enriched.toolName);
+        }
+        else if (enriched.type === 'tool-result' &&
+            enriched.serverName !== undefined &&
+            this.currentMcpToolCallId === enriched.toolCallId) {
+            this.currentMcpToolCallId = null;
+        }
         this.initial.push(enriched);
     }
     maybeEnrich(event) {

package/dist/mastra-event-adapter.d.ts

@@ -33,6 +33,8 @@ import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
  * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
  * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
  * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
+ * | `tool-output`           | `tool-progress`           | `{ toolCallId, toolName, output }`                     |
+ * | `tool-call-delta`       | `tool-call-delta`         | `{ toolCallId, toolName?, argsTextDelta }`             |
  * | `step-start`            | `step-start`              | `{ stepIndex }` from step metadata                     |
  * | `step-finish`           | `step-finish`             | `{ stepIndex, finishReason, usage }` from `stepResult` |
  * | `finish`                | `finish`                  | `{ finishReason, usage }` from `output`                |
@@ -44,9 +46,8 @@ import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
  * | `reasoning-start`,      |                           |                                                        |
  * | `reasoning-end`         |                           |                                                        |
  * | `source`, `file`,       | *(skipped)*               | Known but unsupported — future ChatEvent candidates    |
- * | `tool-call-delta`,      |                           |                                                        |
  * | `tool-call-suspended`,  |                           |                                                        |
- * | `object`, `tool-output` |                           |                                                        |
+ * | `object`                |                           |                                                        |
  * | *(all others)*          | *(skipped)*               | Logged via `LogBus.debug` with `{ chunkType, rawChunk }` |
  *
  * Stateful per stream — a new instance must be created for each `MastraHarness.stream()` call.

package/dist/mastra-event-adapter.js

@@ -34,6 +34,8 @@
  * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
  * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
  * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
+ * | `tool-output`           | `tool-progress`           | `{ toolCallId, toolName, output }`                     |
+ * | `tool-call-delta`       | `tool-call-delta`         | `{ toolCallId, toolName?, argsTextDelta }`             |
  * | `step-start`            | `step-start`              | `{ stepIndex }` from step metadata                     |
  * | `step-finish`           | `step-finish`             | `{ stepIndex, finishReason, usage }` from `stepResult` |
  * | `finish`                | `finish`                  | `{ finishReason, usage }` from `output`                |
@@ -45,9 +47,8 @@
  * | `reasoning-start`,      |                           |                                                        |
  * | `reasoning-end`         |                           |                                                        |
  * | `source`, `file`,       | *(skipped)*               | Known but unsupported — future ChatEvent candidates    |
- * | `tool-call-delta`,      |                           |                                                        |
  * | `tool-call-suspended`,  |                           |                                                        |
- * | `object`, `tool-output` |                           |                                                        |
+ * | `object`                |                           |                                                        |
  * | *(all others)*          | *(skipped)*               | Logged via `LogBus.debug` with `{ chunkType, rawChunk }` |
  *
  * Stateful per stream — a new instance must be created for each `MastraHarness.stream()` call.
@@ -169,19 +170,35 @@ export class MastraEventAdapter {
             case 'reasoning-end':
                 this.logBus?.debug('Skipping informational Mastra chunk', { chunkType: chunk.type });
                 return undefined;
+            case 'tool-output':
+                return {
+                    type: 'tool-progress',
+                    toolCallId: chunk.payload.toolCallId,
+                    toolName: chunk.payload.toolName ?? 'unknown',
+                    output: chunk.payload.output,
+                };
+            case 'tool-call-delta':
+                return {
+                    type: 'tool-call-delta',
+                    toolCallId: chunk.payload.toolCallId,
+                    // Strict `!== undefined` (not truthy) so an empty-string
+                    // toolName from upstream — unlikely but possible — is
+                    // forwarded honestly instead of silently swallowed.
+                    ...(chunk.payload.toolName !== undefined ? { toolName: chunk.payload.toolName } : {}),
+                    argsTextDelta: chunk.payload.argsTextDelta,
+                };
             // Known harness chunk types not yet supported in the SDK's ChatEvent
             // model. Silently dropped to avoid leaking harness internals onto the
             // public stream. Candidates for future ChatEvent variants when the
-            // corresponding features (citations, file generation, tool arg
-            // streaming, tool suspension, structured output) are supported.
+            // corresponding features (citations, file generation, tool input
+            // lifecycle bookends, tool suspension, structured output) are
+            // supported.
             case 'source':
             case 'file':
-            case 'tool-call-delta':
             case 'tool-call-input-streaming-start':
             case 'tool-call-input-streaming-end':
             case 'tool-call-suspended':
             case 'object':
-            case 'tool-output':
                 this.logBus?.debug('Skipping unsupported Mastra chunk type', { chunkType: chunk.type });
                 return undefined;
             default:

package/dist/mastra-harness.d.ts

@@ -478,6 +478,22 @@ export declare class MastraHarness implements MastraAgentHarness {
      * after `shutdown()` has disposed the buses.
      */
     private prepareMcpStatusChange;
+    /**
+     * Issue #591: install a `progress.onUpdate(serverName, ...)` listener
+     * on the MCP client. Incoming `notifications/progress` are dispatched
+     * to the active coordinator on this agent whose `currentRunId` matches
+     * the notification's `progressToken` — `enableProgressTracking: true`
+     * makes `@mastra/mcp` inject `_meta.progressToken = context.runId` into
+     * every tool call, so the token uniquely identifies the originating
+     * turn even across concurrent threads on the same agent.
+     *
+     * `progress.onUpdate` is async (it lazily connects the underlying
+     * internal client). We swallow rejections inside a fire-and-forget
+     * wrapper rather than blocking `createAgent`/`updateAgent` — discovery
+     * and progress tracking are independent: a server that fails to wire
+     * progress still works for tool calls, just without progress events.
+     */
+    private registerMcpProgressListener;
     /**
      * Runs MCP discovery for one server: emits the
      * `mcp-server-discovery-started` / `…-completed` / `…-failed` telemetry

package/dist/mastra-harness.js

@@ -473,6 +473,9 @@ export class MastraHarness {
                 };
                 mcpServerStates.set(serverName, entry);
                 entry.ready = this.runMcpDiscovery(agentId, serverName, client, mcpServerStates, 0, options?.abortSignal);
+                // Issue #591: bridge MCP `notifications/progress` onto the
+                // coordinator's per-turn sink as `tool-progress` ChatEvents.
+                this.registerMcpProgressListener(agentId, serverName, client);
             }
         }
         // Issue #529 step 2c: the bridge `execute` handler resolves the
@@ -893,6 +896,8 @@ export class MastraHarness {
                     };
                     state.mcpServers.set(name, entry);
                     entry.ready = this.runMcpDiscovery(agentId, name, client, state.mcpServers, 0, options?.abortSignal);
+                    // Issue #591: same MCP-progress wiring as createAgent path.
+                    this.registerMcpProgressListener(agentId, name, client);
                 }
             }
         }
@@ -1528,6 +1533,52 @@ export class MastraHarness {
             }
         };
     }
+    /**
+     * Issue #591: install a `progress.onUpdate(serverName, ...)` listener
+     * on the MCP client. Incoming `notifications/progress` are dispatched
+     * to the active coordinator on this agent whose `currentRunId` matches
+     * the notification's `progressToken` — `enableProgressTracking: true`
+     * makes `@mastra/mcp` inject `_meta.progressToken = context.runId` into
+     * every tool call, so the token uniquely identifies the originating
+     * turn even across concurrent threads on the same agent.
+     *
+     * `progress.onUpdate` is async (it lazily connects the underlying
+     * internal client). We swallow rejections inside a fire-and-forget
+     * wrapper rather than blocking `createAgent`/`updateAgent` — discovery
+     * and progress tracking are independent: a server that fails to wire
+     * progress still works for tool calls, just without progress events.
+     */
+    registerMcpProgressListener(agentId, serverName, client) {
+        client.progress
+            .onUpdate(serverName, (params) => {
+            const agentState = this.activeAgents.get(agentId);
+            if (!agentState)
+                return;
+            // Walk per-thread coordinators to find the one whose current
+            // run produced this progressToken. Mastra's
+            // `enableProgressTracking` injects `progressToken =
+            // context.runId`, so `progressToken === coordinator.runId`
+            // is an exact, single-match filter.
+            const targetToken = String(params.progressToken);
+            for (const coordinator of agentState.coordinators.values()) {
+                if (coordinator.getCurrentRunId() === targetToken) {
+                    coordinator.emitMcpProgress({
+                        progress: params.progress,
+                        ...(params.total !== undefined && { total: params.total }),
+                        ...(params.message !== undefined && { message: params.message }),
+                    });
+                    return;
+                }
+            }
+        })
+            .catch((err) => {
+            this.buses.getLogBus()?.warn('Failed to register MCP progress listener', {
+                agentId,
+                serverName,
+                error: getErrorMessage(err),
+            });
+        });
+    }
     /**
      * Runs MCP discovery for one server: emits the
      * `mcp-server-discovery-started` / `…-completed` / `…-failed` telemetry

package/dist/mcp-config-mapper.js

@@ -56,6 +56,13 @@ export function mapToMastraMCPServers(config, orgJwt) {
                 ...(serverConfig.args !== undefined && { args: serverConfig.args }),
                 ...(serverConfig.env !== undefined && { env: serverConfig.env }),
                 ...(serverConfig.timeout !== undefined && { timeout: serverConfig.timeout }),
+                // Issue #591: opt every server in to MCP progress notifications
+                // so the upstream server knows it can send `notifications/progress`
+                // (the harness bridges those to `tool-progress` ChatEvents via
+                // `mcpClient.progress.onUpdate(...)`). Default in `@mastra/mcp` is
+                // off, so without this the spec-compliant progressToken is never
+                // injected into `_meta` and servers send no progress.
+                enableProgressTracking: true,
             };
             result[name] = def;
         }
@@ -77,6 +84,8 @@ export function mapToMastraMCPServers(config, orgJwt) {
                         ...serverConfig.reconnectionOptions,
                     },
                 }),
+                // Issue #591: same rationale as stdio.
+                enableProgressTracking: true,
             };
             result[name] = def;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -38,11 +38,11 @@
     "@salesforce/llm-gateway-sdk": "0.14.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.19.0"
+    "@salesforce/sfdx-agent-sdk": "0.20.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.19.0",
+    "@salesforce/sfdx-agent-sdk": "0.20.0",
     "@types/node": "^22.19.20",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.19",