@salesforce/sfdx-agent-harness-mastra 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.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
+- **harness-mastra**: drop inline WAL-pragma workaround now that LibSQLStore.close() ships stable ([#576](https://github.com/forcedotcom/agentic-dx/pull/576))
+
+### Chores
+- **deps**: bump dependencies across packages @W-22695116@ ([#577](https://github.com/forcedotcom/agentic-dx/pull/577))
+- **deps**: bump the mastra group across 1 directory with 5 updates ([#569](https://github.com/forcedotcom/agentic-dx/pull/569))
+- **deps**: bump @libsql/client from 0.15.15 to 0.17.3 ([#570](https://github.com/forcedotcom/agentic-dx/pull/570))
+- **deps-dev**: bump @types/node from 22.19.19 to 22.19.20 in the dev-dependencies group ([#568](https://github.com/forcedotcom/agentic-dx/pull/568))
+
 ## [0.16.0] - 2026-06-09
 
 ### Features

package/README.md

@@ -26,10 +26,10 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ### Removing the storage directory on Windows
 
-`manager.shutdown()` closes the libsql client (forcedotcom/agentic-dx#429), but the underlying SQLite/WAL handle release
-on Windows is asynchronous at the OS level. After `shutdown()` returns, Windows can take anywhere from ~60 ms to several
-seconds to actually release the file lock — so a naïve `fs.rm(storageRoot)` immediately afterward will fail with
-`EBUSY`. Pass `maxRetries` and `retryDelay` so Node retries until the OS lets go:
+`manager.shutdown()` checkpoints the WAL and closes the libsql client (forcedotcom/agentic-dx#429,
+mastra-ai/mastra#17285), but the underlying SQLite handle release on Windows is asynchronous at the OS level. After
+`shutdown()` returns, Windows can briefly hold the file lock — so a naïve `fs.rm(storageRoot)` immediately afterward can
+fail with `EBUSY`. Pass `maxRetries` and `retryDelay` so Node retries until the OS lets go:
 
 ```ts
 import { rm } from 'node:fs/promises';
@@ -38,9 +38,7 @@ await manager.shutdown();
 await rm(storageRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
 ```
 
-Linux and macOS release the handle eagerly; the retry options are no-ops on those platforms. Tracking upstream at
-[mastra-ai/mastra#17285](https://github.com/mastra-ai/mastra/issues/17285) — when `LibSQLStore` exposes a public
-`close()` that includes a WAL checkpoint, this delay should shrink or disappear.
+Linux and macOS release the handle eagerly; the retry options are no-ops on those platforms.
 
 ## Public API
 

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

@@ -143,12 +143,11 @@ 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.
+     * 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;
     /**

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,11 @@ 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.
+     * 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();
     /**
@@ -210,7 +216,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 +239,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 +331,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 +431,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 +455,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 +479,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 +525,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';
         }
     }

package/dist/mastra-harness.d.ts

@@ -207,18 +207,10 @@ export declare class MastraHarness implements MastraAgentHarness {
      * would mix process state.
      */
     protected readonly activeAgents: Map<string, MastraAgentState>;
-    private readonly libsqlClient;
     private readonly storage;
     private readonly memory;
     private readonly mastra;
     private readonly buses;
-    /**
-     * Tracks the in-flight storage init so {@link shutdown} can settle it
-     * before closing the libsql client. Without this, Mastra's lazy storage
-     * init can fire after `client.close()` and surface as an unhandled
-     * `CLIENT_CLOSED` rejection (#429 follow-up).
-     */
-    private readonly storageReady;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -233,10 +225,10 @@ export declare class MastraHarness implements MastraAgentHarness {
      * @requirements
      * - MUST disconnect the mcpClient for every active agent before clearing state.
      * - MUST clear the `activeAgents` map.
-     * - MUST shut down the global `this.mastra` orchestrator.
-     * - MUST close the libsql client so the underlying SQLite handle is released
-     *   (Windows blocks fs.rm of the storage dir while the WAL/shm files are open;
-     *   see forcedotcom/agentic-dx#429).
+     * - MUST shut down the global `this.mastra` orchestrator. Mastra.shutdown() awaits
+     *   `storage.close()`, which checkpoints the WAL and unlinks the -wal/-shm sidecars
+     *   so a subsequent `fs.rm` of the storage dir succeeds on Windows
+     *   (forcedotcom/agentic-dx#429, mastra-ai/mastra#17285).
      */
     shutdown(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;

package/dist/mastra-harness.js

@@ -10,7 +10,6 @@ import { Memory } from '@mastra/memory';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, RequestContext } from '@mastra/core/request-context';
 import { LibSQLStore } from '@mastra/libsql';
-import { createClient } from '@libsql/client';
 import { MCPClient } from '@mastra/mcp';
 import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, resolveToolApprovalMode, } from '@salesforce/sfdx-agent-sdk';
 import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, } from '@salesforce/sfdx-agent-sdk/harness';
@@ -340,18 +339,10 @@ export class MastraHarness {
      * would mix process state.
      */
     activeAgents = new Map();
-    libsqlClient;
     storage;
     memory;
     mastra;
     buses = new HarnessBusOwner();
-    /**
-     * Tracks the in-flight storage init so {@link shutdown} can settle it
-     * before closing the libsql client. Without this, Mastra's lazy storage
-     * init can fire after `client.close()` and surface as an unhandled
-     * `CLIENT_CLOSED` rejection (#429 follow-up).
-     */
-    storageReady;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -381,24 +372,9 @@ export class MastraHarness {
         this.clock = opts.clock ?? new RealClock();
         this.idGenerator = opts.idGenerator ?? new UUIDGenerator();
         this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs ?? 600_000;
-        // Construct the libsql Client ourselves and inject it into LibSQLStore
-        // via the `{ client }` constructor form. We keep our own reference so
-        // shutdown() can call client.close() — Mastra's shutdown() does not
-        // close the storage, and LibSQLStore declares `client` as private, so
-        // we cannot reach in. Without an explicit close, the SQLite WAL/shm
-        // handles stay open on Windows and block fs.rm of the storage dir
-        // (forcedotcom/agentic-dx#429).
-        //
-        // Upstream tracking: https://github.com/mastra-ai/mastra/issues/17285
-        // — when LibSQLStore exposes a public close(), revert to the simpler
-        // `new LibSQLStore({ id, url })` form and call store.close() in
-        // shutdown().
-        this.libsqlClient = createClient({
-            url: `file:${this.storageRootFolder}/mastra.db`,
-        });
         this.storage = new LibSQLStore({
             id: 'mastra-storage',
-            client: this.libsqlClient,
+            url: `file:${this.storageRootFolder}/mastra.db`,
         });
         this.memory = new Memory({
             storage: this.storage,
@@ -415,24 +391,15 @@ export class MastraHarness {
             storage: this.storage,
             memory: { shared: this.memory },
         });
-        // Eagerly run storage init so Mastra's augment-with-init proxy caches
-        // the result. Without this, any lazy storage call deferred until after
-        // shutdown() (e.g. background tool/agent registration paths in Mastra)
-        // races our libsqlClient.close() and surfaces as an unhandled
-        // CLIENT_CLOSED rejection. We retain the promise so shutdown() can
-        // settle it before closing the client (a swallowed rejection here is
-        // fine — Mastra retains its own init proxy and surfaces real init
-        // errors at the next storage call site).
-        this.storageReady = this.storage.init().catch(() => undefined);
     }
     /**
      * @requirements
      * - MUST disconnect the mcpClient for every active agent before clearing state.
      * - MUST clear the `activeAgents` map.
-     * - MUST shut down the global `this.mastra` orchestrator.
-     * - MUST close the libsql client so the underlying SQLite handle is released
-     *   (Windows blocks fs.rm of the storage dir while the WAL/shm files are open;
-     *   see forcedotcom/agentic-dx#429).
+     * - MUST shut down the global `this.mastra` orchestrator. Mastra.shutdown() awaits
+     *   `storage.close()`, which checkpoints the WAL and unlinks the -wal/-shm sidecars
+     *   so a subsequent `fs.rm` of the storage dir succeeds on Windows
+     *   (forcedotcom/agentic-dx#429, mastra-ai/mastra#17285).
      */
     async shutdown() {
         await Promise.all([...this.activeAgents.values()].map(async (state) => {
@@ -448,29 +415,6 @@ export class MastraHarness {
         }));
         this.activeAgents.clear();
         await this.mastra?.shutdown();
-        // Settle the constructor's eager init before closing — see the
-        // `storageReady` field comment for the why.
-        await this.storageReady;
-        // Fold the WAL into the main DB and switch journal_mode=DELETE
-        // so SQLite unlinks the -wal/-shm sidecars on close. Without this,
-        // Windows holds the sidecars open well past `client.close()` and
-        // racing `fs.rm` calls (e.g. vitest's per-test cleanup) crash the
-        // worker. Mirrors the fix Mastra shipped on `LibSQLStore.close()`
-        // in `@mastra/libsql@1.12.0-alpha.0`. Replace this block with a
-        // call to `storage.close()` once that release ships stable — see
-        // https://github.com/forcedotcom/agentic-dx/issues/475.
-        try {
-            await this.libsqlClient.execute('PRAGMA wal_checkpoint(TRUNCATE);');
-            await this.libsqlClient.execute('PRAGMA journal_mode=DELETE;');
-        }
-        catch (err) {
-            // Best-effort: still close even if checkpoint fails (e.g. the
-            // client was already closed by a prior shutdown path).
-            this.buses.getLogBus()?.warn('libsql WAL checkpoint failed before close', {
-                error: getErrorMessage(err),
-            });
-        }
-        this.libsqlClient.close();
         this.buses.dispose();
     }
     onTelemetry(callback) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -29,37 +29,36 @@
   ],
   "dependencies": {
     "@ai-sdk/provider": "^3.0.10",
-    "@libsql/client": "^0.15.15",
-    "@mastra/core": "^1.37.1",
-    "@mastra/libsql": "^1.11.1",
-    "@mastra/mcp": "^1.8.1",
-    "@mastra/memory": "^1.20.0",
-    "@mastra/schema-compat": "^1.2.10",
-    "@salesforce/agentic-common": "0.9.0",
-    "@salesforce/llm-gateway-sdk": "0.13.0"
+    "@mastra/core": "^1.41.0",
+    "@mastra/libsql": "^1.12.1",
+    "@mastra/mcp": "^1.9.1",
+    "@mastra/memory": "^1.20.2",
+    "@mastra/schema-compat": "^1.2.11",
+    "@salesforce/agentic-common": "0.10.0",
+    "@salesforce/llm-gateway-sdk": "0.14.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.17.0"
+    "@salesforce/sfdx-agent-sdk": "0.19.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.17.0",
-    "@types/node": "^22.19.19",
+    "@salesforce/sfdx-agent-sdk": "0.19.0",
+    "@types/node": "^22.19.20",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.19",
     "eslint": "^10.4.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-n": "^18.0.1",
+    "eslint-plugin-n": "^18.1.0",
     "globals": "^17.6.0",
     "lint-staged": "^17.0.7",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "rimraf": "^6.1.3",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.60.1",
-    "vitest": "^4.1.7"
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=22.19.0"