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

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). */
@@ -181,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).
@@ -238,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). */
@@ -117,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).
@@ -229,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:
+     *
+     *  - **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 `reason` parameter only changes the sink's terminal shape:
-     * `'dispose'` pushes error-only (matches Claude's dispose contract);
-     * everything else pushes error+finish.
+     *  - **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())
@@ -264,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();
     }
@@ -287,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);
@@ -344,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;
@@ -355,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 ────────────────────────────────────
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.19.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.20.0"
+    "@salesforce/sfdx-agent-sdk": "0.21.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.20.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",