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

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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
+- **harness-mastra**: drive one resume per pending approval for parallel batches ([#587](https://github.com/forcedotcom/agentic-dx/pull/587))
+
 ## [0.17.0] - 2026-06-09
 
 ### Fixes

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

@@ -143,12 +143,34 @@ export declare class MastraApprovalCoordinator {
      */
     private currentRunId;
     /**
-     * The toolCallId Mastra is currently suspended on (after the natural
-     * `tool-call-approval` chunk). `null` when no suspension. The
-     * coordinator's pump loop reads this when the current `fullStream`
-     * closes to decide whether to drive a resume.
+     * `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
+     * pending id with `{ toolCallId }` to disambiguate (#586).
      */
-    private currentSuspendId;
+    private readonly pendingSuspendIds;
     /** Consumer-tool: bound parkers, keyed by `toolCallId`. `submitToolResult` resolves these. */
     private readonly pendingByToolCallId;
     /**
@@ -176,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

@@ -5,6 +5,13 @@
 import { AgentSDKError, AgentSDKErrorType, } from '@salesforce/sfdx-agent-sdk';
 import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraEventAdapter } from './mastra-event-adapter.js';
+function pickIdWithDecision(pendingIds, decisions) {
+    for (const id of pendingIds) {
+        if (decisions.has(id))
+            return id;
+    }
+    return undefined;
+}
 /**
  * Per-`(agentId, threadId)` coordinator that subsumes the pre-#529
  * `MastraStreamBroker` + `activeRuns` pair into one object owning a single
@@ -72,12 +79,34 @@ export class MastraApprovalCoordinator {
      */
     currentRunId = '';
     /**
-     * The toolCallId Mastra is currently suspended on (after the natural
-     * `tool-call-approval` chunk). `null` when no suspension. The
-     * coordinator's pump loop reads this when the current `fullStream`
-     * closes to decide whether to drive a resume.
+     * `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
+     * pending id with `{ toolCallId }` to disambiguate (#586).
      */
-    currentSuspendId = null;
+    pendingSuspendIds = new Set();
     /** Consumer-tool: bound parkers, keyed by `toolCallId`. `submitToolResult` resolves these. */
     pendingByToolCallId = new Map();
     /**
@@ -117,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);
@@ -210,7 +276,7 @@ export class MastraApprovalCoordinator {
             this.initial.push({ type: 'finish', finishReason: 'error' });
             this.initial.end();
         }
-        this.currentSuspendId = null;
+        this.pendingSuspendIds.clear();
         this.runTeardownCallbacks();
     }
     // ───────────────────────── settle methods ───────────────────────────────
@@ -233,14 +299,9 @@ export class MastraApprovalCoordinator {
         this.consumerSettled.add(toolCallId);
         this.cancelTimer(toolCallId);
         this.decisions.set(toolCallId, decision);
-        // The pump loop is the single owner of `agent.approveToolCall(...)`
-        // / `declineToolCall(...)` invocation. recordDecision buffers the
-        // decision; the pump's outer loop reads `decisions.get(suspendId)`
-        // when it sees the matching suspension and drives the resume. If
-        // the pump is currently parked on `awaitContinuation` (saw the
-        // suspension first, decision arrived second), wake it so it
-        // re-checks `decisions`.
-        if (this.continuationResolver && this.currentSuspendId === toolCallId) {
+        // Wake the pump if it's parked on `awaitContinuation` waiting for
+        // a decision on a pending id.
+        if (this.continuationResolver && this.pendingSuspendIds.has(toolCallId)) {
             const resolve = this.continuationResolver;
             this.continuationResolver = undefined;
             resolve('continued');
@@ -330,33 +391,29 @@ export class MastraApprovalCoordinator {
                 }
                 if (this.aborted || this.disposed || this.timedOut)
                     return;
-                // outcome === 'suspended': Mastra suspended after a
-                // `tool-call-approval` chunk. `currentSuspendId` carries
-                // the id Mastra is suspended on. Either the consumer
-                // already settled (decision buffered) and we drive the
-                // resume now, or we park until a settle arrives.
-                const suspendId = this.currentSuspendId;
-                if (suspendId === null) {
-                    // Defensive: stream ended without a suspension. Treat
-                    // as terminal.
+                // outcome === 'suspended': drive one resume per outer
+                // iteration. For parallel batches, all but the last resume
+                // returns a stream that closes silently while still
+                // suspended — the pump re-enters here to drive the next id.
+                if (this.pendingSuspendIds.size === 0) {
                     if (!this.initial.isEnded())
                         this.initial.end();
                     return;
                 }
-                let buffered = this.decisions.get(suspendId);
-                if (buffered === undefined) {
-                    // Park for a decision (or teardown).
+                let nextId = pickIdWithDecision(this.pendingSuspendIds, this.decisions);
+                if (nextId === undefined) {
                     const cont = await this.awaitContinuation();
                     if (cont === 'done')
                         return;
-                    // Re-read `decisions` post-wake; recordDecision sets it
-                    // before signaling, so we must see it here.
-                    buffered = this.decisions.get(suspendId);
-                    if (buffered === undefined)
+                    nextId = pickIdWithDecision(this.pendingSuspendIds, this.decisions);
+                    if (nextId === undefined)
                         return;
                 }
-                this.currentSuspendId = null;
-                const next = await this.driveResumeReturning(suspendId, buffered);
+                const decision = this.decisions.get(nextId);
+                if (decision === undefined)
+                    return;
+                this.pendingSuspendIds.delete(nextId);
+                const next = await this.driveResumeReturning(nextId, decision);
                 if (next === 'done')
                     return;
                 currentStream = next;
@@ -434,22 +491,21 @@ export class MastraApprovalCoordinator {
                     continue;
                 }
                 if (event.type === 'tool-approval-request') {
-                    // Mastra's natural `tool-call-approval` chunk → ChatEvent.
-                    // Mastra has suspended on this toolCallId. Decide whether
-                    // to surface a `tool-approval-request` to the consumer or
-                    // auto-approve silently.
+                    // Parallel batches emit one chunk per suspension before
+                    // the stream closes; accumulate every id and let the
+                    // read loop continue to the natural close.
                     const tc = event.toolCall;
                     this.toolCallArgs.set(tc.toolCallId, tc.args);
-                    this.currentSuspendId = tc.toolCallId;
+                    this.pendingSuspendIds.add(tc.toolCallId);
                     sawSuspension = true;
                     if (this.consumerToolNames.has(tc.toolName)) {
                         // Consumer tools bypass the gate per the
                         // StreamOptions.requireToolApproval JSDoc. Auto-
                         // approve silently — no ChatEvent surfaces, and the
-                        // outer pump loop drives `agent.approveToolCall`
-                        // when it picks up the buffered decision. After
-                        // Mastra resumes, the bridge `execute` parker runs
-                        // and `submitToolResult` settles it — same shape as
+                        // pump loop drives `agent.approveToolCall` when it
+                        // picks up the buffered decision. After Mastra
+                        // resumes, the bridge `execute` parker runs and
+                        // `submitToolResult` settles it — same shape as
                         // non-approval-mode consumer-tool flow.
                         this.settledByCoordinator.add(tc.toolCallId);
                         this.decisions.set(tc.toolCallId, { kind: 'approve' });
@@ -459,14 +515,7 @@ export class MastraApprovalCoordinator {
                         // pre-emit in tool-call routing).
                         this.emitApprovalRequest(tc.toolCallId, tc.toolName, tc.args);
                     }
-                    // Drain the rest of the stream so Mastra's workflow
-                    // snapshot persists before we attempt a resume.
-                    while (true) {
-                        const { done: d } = await reader.read();
-                        if (d)
-                            break;
-                    }
-                    return 'suspended';
+                    continue;
                 }
                 this.routeEnriched(event);
             }
@@ -490,17 +539,13 @@ export class MastraApprovalCoordinator {
                 /* best-effort: lock may already be released after a thrown read */
             }
         }
-        // Stream closed naturally without a `finish` chunk and without a
-        // suspension. This happens when:
-        //  (a) abort/dispose/timeout fired and Mastra closed the stream
-        //      silently (no chunk emitted).
-        //  (b) consumer-tool flow: the tool's parker resolved, Mastra
-        //      continued the same fullStream, and the next assistant turn
-        //      ran to terminal `finish` — but in that case `finish` would
-        //      have arrived in the loop above. So (b) shouldn't reach here.
-        // Treat as terminal: sink is either ended already (teardown) or
-        // we must end it now.
-        if (!sawTerminal && !sawSuspension && !this.initial.isEnded()) {
+        // Stream closed without `finish`/`error`. If any suspension is
+        // pending (just observed, or carried over from a prior non-final
+        // resume that closed silently), defer to the pump loop's drive.
+        if (sawSuspension || this.pendingSuspendIds.size > 0) {
+            return 'suspended';
+        }
+        if (!sawTerminal && !this.initial.isEnded()) {
             this.initial.end();
         }
         return 'terminal';
@@ -540,10 +585,10 @@ export class MastraApprovalCoordinator {
             return output.fullStream;
         }
         catch (err) {
+            // Route through teardown so siblings in `pendingSuspendIds`
+            // settle as auto-resolved rather than silently orphaning.
             const error = err instanceof Error ? err : new Error(String(err));
-            this.initial.push({ type: 'error', error });
-            this.initial.push({ type: 'finish', finishReason: 'error' });
-            this.initial.end();
+            this.teardown('pump-error', error, 'pump-error');
             return 'done';
         }
     }
@@ -563,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.17.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.18.0"
+    "@salesforce/sfdx-agent-sdk": "0.20.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.18.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",