@salesforce/sfdx-agent-harness-mastra 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.64.0] - 2026-09-02
+
+### Features
+- **harness-mastra**: synthesize a terminal error when a Mastra stream closes without a finish @W-24026817@ ([#784](https://github.com/forcedotcom/agentic-dx/pull/784))
+
+## [0.63.0] - 2026-09-02
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: reject concurrent turns with a typed SESSION_BUSY error @W-24044572@ ([#783](https://github.com/forcedotcom/agentic-dx/pull/783))
+
 ## [0.62.0] - 2026-09-02
 
 ### Fixes

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

@@ -261,6 +261,18 @@ export declare class MastraApprovalCoordinator {
     private timedOut;
     constructor(opts: MastraApprovalCoordinatorOptions);
     initialSink(): GenSink<ChatEvent>;
+    /**
+     * True once this turn has reached a terminal event — a natural `finish`
+     * pushed by the pump, or the synthetic `error` + `finish('error')` pair a
+     * `teardown` (abort / dispose / timeout / pump-error) emits. Both end the
+     * single per-turn sink, so `initial.isEnded()` is the authoritative "this
+     * turn is over" signal. A coordinator still pumping — including one PARKED on
+     * a `tool-approval-request` or a consumer-tool `submitToolResult` — has not
+     * ended its sink and is therefore NOT settled. `MastraHarness.stream()` reads
+     * this to reject a concurrent turn with `SESSION_BUSY` (a still-active
+     * coordinator) versus safely replace a settled one.
+     */
+    isSettled(): boolean;
     /**
      * Mastra's current run id. The harness's MCP-progress dispatcher uses
      * this to filter incoming `notifications/progress` to the coordinator
@@ -395,6 +407,40 @@ export declare class MastraApprovalCoordinator {
      */
     private driveResumeReturning;
     private awaitContinuation;
+    /**
+     * Terminal-event guard (spike agent-offline-failure-modes #07, W-24026817).
+     *
+     * Called at the pump's silent-close sites — where Mastra's `fullStream`
+     * exhausted with neither a `finish`/`error` chunk nor a recognized
+     * suspension, so the turn produced no terminal event of its own. A healthy
+     * turn never lands here: a normal turn ends on a `finish` chunk, and an
+     * approval turn's FINAL resume produces the real continuation `finish` (see
+     * ARCHITECTURE.md → "Pump loop", step 5). The realistic trigger is a
+     * COORDINATOR-level terminating chunk the adapter intentionally skips —
+     * today `tool-call-suspended` (a tool using Mastra's native `suspend()`,
+     * which the event adapter maps to `undefined`) — and the guard also closes
+     * the class for any future Mastra chunk that ends the stream without a
+     * paired finish.
+     *
+     * Without this, the pump would `initial.end()` the sink silently and the
+     * SDK's `DefaultChatSession.wrapEventStream` — which synthesizes its own
+     * terminal `finish` ONLY when an error landed — would record the turn as a
+     * false-success `chat-stream-completed` with NO terminal `FinishEvent`,
+     * breaking the SDK invariant "every chat turn ends with exactly one terminal
+     * FinishEvent". Routing through the single `teardown` path pushes the typed
+     * `error('incomplete-stream')` + `finish('error')` pair the SDK invariant
+     * requires, so the turn fails loudly and recoverably instead. This is the
+     * harness-side complement to the SDK-side invariant item #10 pinned.
+     *
+     * `teardown` short-circuits its sink pushes once the sink is ended
+     * (`GenSink.push` no-ops after `end()`), and every terminal path either
+     * ended the sink already or set `aborted`/`disposed`/`timedOut` (which the
+     * callers check first), so this can never double-signal a turn that already
+     * reached a terminal — including 8a's pass-through `empty-stream` error,
+     * which arrives as an `error` chunk that ends the sink before the stream
+     * closes.
+     */
+    private guardTerminalOnSilentClose;
     /**
      * Push an event onto the sink with MCP-server enrichment applied (when
      * the toolName resolves to a known MCP catalog entry). Mirrors the

package/dist/mastra-approval-coordinator.js

@@ -184,6 +184,20 @@ export class MastraApprovalCoordinator {
     initialSink() {
         return this.initial;
     }
+    /**
+     * True once this turn has reached a terminal event — a natural `finish`
+     * pushed by the pump, or the synthetic `error` + `finish('error')` pair a
+     * `teardown` (abort / dispose / timeout / pump-error) emits. Both end the
+     * single per-turn sink, so `initial.isEnded()` is the authoritative "this
+     * turn is over" signal. A coordinator still pumping — including one PARKED on
+     * a `tool-approval-request` or a consumer-tool `submitToolResult` — has not
+     * ended its sink and is therefore NOT settled. `MastraHarness.stream()` reads
+     * this to reject a concurrent turn with `SESSION_BUSY` (a still-active
+     * coordinator) versus safely replace a settled one.
+     */
+    isSettled() {
+        return this.initial.isEnded();
+    }
     /**
      * Mastra's current run id. The harness's MCP-progress dispatcher uses
      * this to filter incoming `notifications/progress` to the coordinator
@@ -484,8 +498,8 @@ export class MastraApprovalCoordinator {
                 // 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();
+                    // Terminal-event guard — see guardTerminalOnSilentClose.
+                    this.guardTerminalOnSilentClose();
                     return;
                 }
                 let nextId = pickIdWithDecision(this.pendingSuspendIds, this.decisions);
@@ -658,9 +672,9 @@ export class MastraApprovalCoordinator {
         if (sawSuspension || this.pendingSuspendIds.size > 0) {
             return 'suspended';
         }
-        if (!sawTerminal && !this.initial.isEnded()) {
-            this.pendingMcpToolCallStarts.clear();
-            this.initial.end();
+        if (!sawTerminal) {
+            // Terminal-event guard — see guardTerminalOnSilentClose.
+            this.guardTerminalOnSilentClose();
         }
         return 'terminal';
     }
@@ -712,6 +726,44 @@ export class MastraApprovalCoordinator {
             this.continuationResolver = resolve;
         });
     }
+    /**
+     * Terminal-event guard (spike agent-offline-failure-modes #07, W-24026817).
+     *
+     * Called at the pump's silent-close sites — where Mastra's `fullStream`
+     * exhausted with neither a `finish`/`error` chunk nor a recognized
+     * suspension, so the turn produced no terminal event of its own. A healthy
+     * turn never lands here: a normal turn ends on a `finish` chunk, and an
+     * approval turn's FINAL resume produces the real continuation `finish` (see
+     * ARCHITECTURE.md → "Pump loop", step 5). The realistic trigger is a
+     * COORDINATOR-level terminating chunk the adapter intentionally skips —
+     * today `tool-call-suspended` (a tool using Mastra's native `suspend()`,
+     * which the event adapter maps to `undefined`) — and the guard also closes
+     * the class for any future Mastra chunk that ends the stream without a
+     * paired finish.
+     *
+     * Without this, the pump would `initial.end()` the sink silently and the
+     * SDK's `DefaultChatSession.wrapEventStream` — which synthesizes its own
+     * terminal `finish` ONLY when an error landed — would record the turn as a
+     * false-success `chat-stream-completed` with NO terminal `FinishEvent`,
+     * breaking the SDK invariant "every chat turn ends with exactly one terminal
+     * FinishEvent". Routing through the single `teardown` path pushes the typed
+     * `error('incomplete-stream')` + `finish('error')` pair the SDK invariant
+     * requires, so the turn fails loudly and recoverably instead. This is the
+     * harness-side complement to the SDK-side invariant item #10 pinned.
+     *
+     * `teardown` short-circuits its sink pushes once the sink is ended
+     * (`GenSink.push` no-ops after `end()`), and every terminal path either
+     * ended the sink already or set `aborted`/`disposed`/`timedOut` (which the
+     * callers check first), so this can never double-signal a turn that already
+     * reached a terminal — including 8a's pass-through `empty-stream` error,
+     * which arrives as an `error` chunk that ends the sink before the stream
+     * closes.
+     */
+    guardTerminalOnSilentClose() {
+        if (this.initial.isEnded())
+            return;
+        this.teardown('incomplete-stream', new Error('The model stream closed without a terminal finish or error event.'), 'incomplete-stream');
+    }
     // ───────────────────────── routing helpers ──────────────────────────────
     /**
      * Push an event onto the sink with MCP-server enrichment applied (when

package/dist/mastra-harness.js

@@ -1618,12 +1618,20 @@ export class MastraHarness {
         // round-trip per tool call.
         const { lookupPolicy, batchApprovals } = this.buildPolicyGate(agentState, options);
         const gatingActive = lookupPolicy !== undefined;
-        // Dispose any coordinator the prior turn on this thread allocated.
-        // Without this a stale coordinator from the prior turn would still
-        // route settle calls and accumulate listeners. Mode-flip safe: the
-        // new coordinator is constructed fresh below regardless of the new
-        // turn's mode.
+        // Concurrency guard (spike agent-offline-failure-modes #10, W-24044572):
+        // reject a second turn on a thread whose prior turn is still ACTIVE with a
+        // typed `SESSION_BUSY` error, instead of silently disposing the first
+        // (which surfaced to the first consumer as a spurious `DISPOSED` — a
+        // "silent lost turn"). A coordinator is active until its sink ends (natural
+        // finish or teardown), so one still pumping — including one parked on an
+        // approval / consumer-tool result — blocks a new turn. An already-settled
+        // coordinator (finished or errored) is safe to dispose-and-replace, so the
+        // idempotent settling of an already-terminal turn is preserved.
         const priorCoordinator = agentState.coordinators.get(threadId);
+        if (priorCoordinator && !priorCoordinator.isSettled()) {
+            throw new AgentSDKError(`A turn is already in progress for thread "${threadId}" on agent "${agentId}". ` +
+                'Only one turn may run at a time per thread; await the in-flight turn before starting another.', AgentSDKErrorType.SESSION_BUSY);
+        }
         if (priorCoordinator) {
             priorCoordinator.dispose();
             agentState.coordinators.delete(threadId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -42,12 +42,12 @@
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.63.0"
+    "@salesforce/sfdx-agent-sdk": "0.65.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.63.0",
+    "@salesforce/sfdx-agent-sdk": "0.65.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",