@salesforce/sfdx-agent-harness-mastra 0.18.0 → 0.20.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.20.0] - 2026-06-15
+
+### Fixes
+- **harness-claude,harness-mastra,agent-sdk**: idempotent settle + quiet dispose (#589) ([#598](https://github.com/forcedotcom/agentic-dx/pull/598))
+
+## [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/README.md

@@ -203,9 +203,12 @@ active `eventStream`:
 { type: 'finish', finishReason: 'error' }
 ```
 
-Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool throw because the
-coordinator has already auto-resolved them. The granularity is per `toolCallId` — each emitted approval arms its own
-timer; the first one to fire tears down the whole turn (since Mastra can't continue the suspended run after timeout
+Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool are silent no-ops
+(issue #589 idempotent settle) — the coordinator already auto-resolved them, so the consumer's intended outcome is
+already true and there's nothing to fail. Only a `toolCallId` the coordinator never saw at all (typo, wrong session,
+called before `tool-approval-request` ever fired) throws, and that throw is an `AgentSDKError` whose
+`type === AgentSDKErrorType.TOOL_CALL_NOT_FOUND`. The granularity is per `toolCallId` — each emitted approval arms its
+own timer; the first one to fire tears down the whole turn (since Mastra can't continue the suspended run after timeout
 anyway). To observe the timeout, keep iterating the `eventStream` past the `tool-approval-request` event so the
 synthetic terminal pair lands in your loop:
 

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

@@ -128,8 +128,11 @@ export declare class MastraApprovalCoordinator {
     private readonly consumerSettled;
     /**
      * ToolCallIds the coordinator auto-resolved (timeout / abort / dispose
-     * / consumer-tool auto-approve). A subsequent settle for these ids
-     * rejects with "already auto-resolved by the coordinator".
+     * / pump-error / consumer-tool auto-approve). A subsequent settle for
+     * these ids is a silent no-op via the idempotent-settle contract
+     * (issue #589) — the lost race is unactionable from the consumer's
+     * side, and the methods are void-typed so there's no return value to
+     * communicate the no-op.
      */
     private readonly settledByCoordinator;
     /** Per-toolCallId approval-timeout timers (armed when an approval is emitted). */
@@ -142,6 +145,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
@@ -158,6 +184,15 @@ export declare class MastraApprovalCoordinator {
      * parker invocation for the same id.
      */
     private readonly preSubmittedByToolCallId;
+    /**
+     * ToolCallIds the consumer has settled via {@link submitToolResult},
+     * or that the coordinator drained at teardown time. Used as the
+     * idempotent-settle ledger for the consumer-tool path (parallel to
+     * `consumerSettled` + `settledByCoordinator` on the approve/decline
+     * path). A subsequent `submitToolResult` for these ids is a silent
+     * no-op rather than throwing `TOOL_CALL_NOT_FOUND` (issue #589).
+     */
+    private readonly consumerToolSettled;
     /**
      * Callbacks invoked exactly once during teardown (`abort` or `dispose`,
      * whichever fires first, or natural pump exit).
@@ -175,6 +210,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;
     /**
@@ -188,13 +250,39 @@ export declare class MastraApprovalCoordinator {
     /**
      * Single teardown path for abort / dispose / approval-timeout / pump-
      * error. Drains timers, rejects pending consumer-tool parkers, marks
-     * every emitted approval as coordinator-settled, releases Mastra's
-     * suspended run, pushes the synthetic terminal pair on the sink, and
-     * fires teardown callbacks.
+     * every emitted approval and consumer-tool toolCallId as
+     * coordinator-settled, releases Mastra's suspended run, pushes the
+     * typed `error` + `finish('error')` pair on the sink, and fires
+     * teardown callbacks.
+     *
+     * Every teardown reason — including `'dispose'` — pushes both events
+     * (issue #589). Two reasons:
+     *
+     *  - **Consumers route on `error.code`, not on the *presence* of an
+     *    error event.** AFV's `chat-stream-service.ts` maps
+     *    `error.code === AgentSDKErrorType.DISPOSED` → its internal
+     *    `AGENT_CANCELLED` and reaps the turn as cancelled (rather than
+     *    completed or failed). Suppressing the dispose error event would
+     *    delete that signal and a turn that was actually torn down would
+     *    record as successful in their telemetry pipeline. The original
+     *    bug (issue #589 failure 2) was *untyped* error noise —
+     *    `error.code` is already typed as `AgentSDKErrorType.DISPOSED`,
+     *    which gives consumers a clean discriminator without
+     *    string-matching.
+     *
+     *  - **The SDK invariant requires every chat turn to end with one
+     *    terminal `FinishEvent`.** `DefaultChatSession.wrapEventStream`
+     *    only synthesizes a synthetic `finish` when an error landed on
+     *    the stream; if dispose ended the sink without an error, the
+     *    turn would end with neither a natural finish nor a synthetic
+     *    one — breaking the SDK contract pinned in
+     *    `packages/sfdx-agent-sdk/ARCHITECTURE.md` →
+     *    "Critical Invariants" → "Every chat turn ends with exactly one
+     *    terminal FinishEvent".
      *
-     * The `reason` parameter only changes the sink's terminal shape:
-     * `'dispose'` pushes error-only (matches Claude's dispose contract);
-     * everything else pushes error+finish.
+     * Mirrors the Claude coordinator's `teardown` so the abort / dispose
+     * / timeout / pump-error paths can't drift out of step on either
+     * harness — issue #589 lands the same shape on both.
      */
     private teardown;
     approve(toolCallId: string): void;

package/dist/mastra-approval-coordinator.js

@@ -64,8 +64,11 @@ export class MastraApprovalCoordinator {
     consumerSettled = new Set();
     /**
      * ToolCallIds the coordinator auto-resolved (timeout / abort / dispose
-     * / consumer-tool auto-approve). A subsequent settle for these ids
-     * rejects with "already auto-resolved by the coordinator".
+     * / pump-error / consumer-tool auto-approve). A subsequent settle for
+     * these ids is a silent no-op via the idempotent-settle contract
+     * (issue #589) — the lost race is unactionable from the consumer's
+     * side, and the methods are void-typed so there's no return value to
+     * communicate the no-op.
      */
     settledByCoordinator = new Set();
     /** Per-toolCallId approval-timeout timers (armed when an approval is emitted). */
@@ -78,6 +81,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
@@ -94,6 +120,15 @@ export class MastraApprovalCoordinator {
      * parker invocation for the same id.
      */
     preSubmittedByToolCallId = new Map();
+    /**
+     * ToolCallIds the consumer has settled via {@link submitToolResult},
+     * or that the coordinator drained at teardown time. Used as the
+     * idempotent-settle ledger for the consumer-tool path (parallel to
+     * `consumerSettled` + `settledByCoordinator` on the approve/decline
+     * path). A subsequent `submitToolResult` for these ids is a silent
+     * no-op rather than throwing `TOOL_CALL_NOT_FOUND` (issue #589).
+     */
+    consumerToolSettled = new Set();
     /**
      * Callbacks invoked exactly once during teardown (`abort` or `dispose`,
      * whichever fires first, or natural pump exit).
@@ -123,6 +158,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);
@@ -169,18 +241,52 @@ export class MastraApprovalCoordinator {
     /**
      * Single teardown path for abort / dispose / approval-timeout / pump-
      * error. Drains timers, rejects pending consumer-tool parkers, marks
-     * every emitted approval as coordinator-settled, releases Mastra's
-     * suspended run, pushes the synthetic terminal pair on the sink, and
-     * fires teardown callbacks.
+     * every emitted approval and consumer-tool toolCallId as
+     * coordinator-settled, releases Mastra's suspended run, pushes the
+     * typed `error` + `finish('error')` pair on the sink, and fires
+     * teardown callbacks.
+     *
+     * Every teardown reason — including `'dispose'` — pushes both events
+     * (issue #589). Two reasons:
      *
-     * The `reason` parameter only changes the sink's terminal shape:
-     * `'dispose'` pushes error-only (matches Claude's dispose contract);
-     * everything else pushes error+finish.
+     *  - **Consumers route on `error.code`, not on the *presence* of an
+     *    error event.** AFV's `chat-stream-service.ts` maps
+     *    `error.code === AgentSDKErrorType.DISPOSED` → its internal
+     *    `AGENT_CANCELLED` and reaps the turn as cancelled (rather than
+     *    completed or failed). Suppressing the dispose error event would
+     *    delete that signal and a turn that was actually torn down would
+     *    record as successful in their telemetry pipeline. The original
+     *    bug (issue #589 failure 2) was *untyped* error noise —
+     *    `error.code` is already typed as `AgentSDKErrorType.DISPOSED`,
+     *    which gives consumers a clean discriminator without
+     *    string-matching.
+     *
+     *  - **The SDK invariant requires every chat turn to end with one
+     *    terminal `FinishEvent`.** `DefaultChatSession.wrapEventStream`
+     *    only synthesizes a synthetic `finish` when an error landed on
+     *    the stream; if dispose ended the sink without an error, the
+     *    turn would end with neither a natural finish nor a synthetic
+     *    one — breaking the SDK contract pinned in
+     *    `packages/sfdx-agent-sdk/ARCHITECTURE.md` →
+     *    "Critical Invariants" → "Every chat turn ends with exactly one
+     *    terminal FinishEvent".
+     *
+     * Mirrors the Claude coordinator's `teardown` so the abort / dispose
+     * / timeout / pump-error paths can't drift out of step on either
+     * harness — issue #589 lands the same shape on both.
      */
     teardown(reason, error, code) {
         this.cancelAllTimers();
         for (const id of this.emittedApprovals)
             this.settledByCoordinator.add(id);
+        // Issue #589: drain in-flight consumer-tool ids into the
+        // idempotent-settle ledger so a late `submitToolResult` after
+        // teardown is a silent no-op rather than throwing
+        // `TOOL_CALL_NOT_FOUND`. Mirrors the approve/decline drain above.
+        for (const id of this.pendingByToolCallId.keys())
+            this.consumerToolSettled.add(id);
+        for (const id of this.toolCallArgs.keys())
+            this.consumerToolSettled.add(id);
         // Reject every parked consumer-tool call so the bridge handler
         // unblocks with an error rather than waiting forever.
         for (const entry of this.pendingByToolCallId.values())
@@ -204,18 +310,9 @@ export class MastraApprovalCoordinator {
         const resolve = this.continuationResolver;
         this.continuationResolver = undefined;
         resolve?.('done');
-        if (reason === 'dispose') {
-            // Match Claude's dispose shape: error event only, no `finish`.
-            // Disposal is a consumer-triggered teardown, not a normal turn
-            // end, so a `finish` event would be misleading.
-            this.initial.push({ type: 'error', error, code });
-            this.initial.end();
-        }
-        else {
-            this.initial.push({ type: 'error', error, code });
-            this.initial.push({ type: 'finish', finishReason: 'error' });
-            this.initial.end();
-        }
+        this.initial.push({ type: 'error', error, code });
+        this.initial.push({ type: 'finish', finishReason: 'error' });
+        this.initial.end();
         this.pendingSuspendIds.clear();
         this.runTeardownCallbacks();
     }
@@ -227,14 +324,21 @@ export class MastraApprovalCoordinator {
         this.recordDecision('decline', toolCallId, { kind: 'decline' });
     }
     recordDecision(method, toolCallId, decision) {
-        if (this.settledByCoordinator.has(toolCallId)) {
-            throw new Error(`MastraApprovalCoordinator.${method}(): tool call "${toolCallId}" was already auto-resolved by the coordinator`);
-        }
-        if (this.consumerSettled.has(toolCallId)) {
-            throw new Error(`MastraApprovalCoordinator.${method}(): tool call "${toolCallId}" was already settled`);
+        // Issue #589: idempotent settle. A tool call the coordinator
+        // already auto-resolved (timeout / abort / dispose / pump-error)
+        // or the consumer already settled is a lost-race no-op rather
+        // than a throw — settle methods are void-typed, so the consumer
+        // never branches on a return value, and the outcome they wanted
+        // (id is settled) is already true.
+        if (this.settledByCoordinator.has(toolCallId) || this.consumerSettled.has(toolCallId)) {
+            return;
         }
         if (!this.emittedApprovals.has(toolCallId)) {
-            throw new Error(`MastraApprovalCoordinator.${method}(): no pending approval for tool call "${toolCallId}"`);
+            // Genuine misuse — the coordinator never saw this id (typo,
+            // wrong session, or settle called before approval-request /
+            // tool-call ever fired). Typed so consumers can branch on
+            // err.type instead of string-matching the message.
+            throw new AgentSDKError(`MastraApprovalCoordinator.${method}(): no pending approval for tool call "${toolCallId}"`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
         }
         this.consumerSettled.add(toolCallId);
         this.cancelTimer(toolCallId);
@@ -284,8 +388,18 @@ export class MastraApprovalCoordinator {
      * resolves (probe-validated, see #529 step 2c).
      */
     submitToolResult(toolCallId, result, isError) {
+        // Issue #589: idempotent settle. A submitToolResult for an id the
+        // consumer already settled, or that the coordinator drained at
+        // teardown time, is a silent no-op — the lost-race shape is
+        // unactionable from the consumer's side, and the method is
+        // void-typed. Mirrors the approve/decline path's
+        // `consumerSettled` + `settledByCoordinator` ledger.
+        if (this.consumerToolSettled.has(toolCallId)) {
+            return;
+        }
         const entry = this.pendingByToolCallId.get(toolCallId);
         if (entry) {
+            this.consumerToolSettled.add(toolCallId);
             this.pendingByToolCallId.delete(toolCallId);
             entry.resolve({ result, isError });
             return;
@@ -295,10 +409,14 @@ export class MastraApprovalCoordinator {
         // We allow this whenever the coordinator has seen a `tool-call`
         // event under that id (reachable in `toolCallArgs`); else throw.
         if (this.toolCallArgs.has(toolCallId)) {
+            this.consumerToolSettled.add(toolCallId);
             this.preSubmittedByToolCallId.set(toolCallId, { result, isError });
             return;
         }
-        throw new Error(`MastraApprovalCoordinator.submitToolResult(): no pending tool call for id "${toolCallId}"`);
+        // Issue #589: typed error — the coordinator never saw this id, so
+        // this is genuine misuse rather than the lost-race shape the
+        // idempotent-settle path collapses to a no-op.
+        throw new AgentSDKError(`MastraApprovalCoordinator.submitToolResult(): no pending tool call for id "${toolCallId}"`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
     }
     // ───────────────────────── pump loop ────────────────────────────────────
     /**
@@ -548,6 +666,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.20.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.21.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.19.0",
+    "@salesforce/sfdx-agent-sdk": "0.21.0",
     "@types/node": "^22.19.20",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.19",