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

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

@@ -407,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

@@ -498,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);
@@ -672,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';
     }
@@ -726,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.63.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.64.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.64.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",