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

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.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-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.17.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.18.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.17.0",
-    "@types/node": "^22.19.19",
+    "@salesforce/sfdx-agent-sdk": "0.18.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"