@salesforce/sfdx-agent-harness-mastra 0.56.0 → 0.58.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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.58.0] - 2026-08-28
+
+_No changes — released alongside dependent packages._
+
+## [0.57.0] - 2026-08-28
+
+### Fixes
+- **harness-mastra,agent-sdk**: resilient thread enumeration + exception-safe destroyChatSession @W-24014120@ ([#774](https://github.com/forcedotcom/agentic-dx/pull/774))
+
 ## [0.56.0] - 2026-08-27
 
 _No changes — released alongside dependent packages._

package/dist/mastra-harness.d.ts

@@ -393,8 +393,35 @@ export declare class MastraHarness implements MastraAgentHarness {
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST query threads scoped to this agent and return their IDs.
+     * - MUST enumerate resiliently: a single thread whose persisted `metadata` is
+     *   corrupt MUST NOT suppress the agent's other thread IDs.
+     *
+     * Resilience rationale (spike agent-offline-failure-modes #11, W-24014120):
+     * `memory.listThreads` builds its SELECT as `json(metadata)` over every row, so one
+     * malformed-JSON row makes SQLite throw `SQLITE_ERROR: malformed JSON`; Mastra's
+     * catch swallows that and returns an EMPTY list — silently un-restoring every thread
+     * on the agent (the "one bad thread bricks the whole agent" symptom). We instead
+     * enumerate with a column-only `SELECT id` (both `id` and `resourceId` are plain
+     * TEXT, never parsed), which a corrupt `metadata` on another row cannot break. The
+     * raw query couples to Mastra's `mastra_threads` schema, so it is fallback-guarded —
+     * but ONLY for the failures the fallback is meant to survive:
+     *   - the libsql client isn't reachable (a future Mastra internals change), or
+     *   - the raw query hits a schema-shape drift (`no such table` / `no such column`).
+     * Both degrade to the high-level `listThreads` API with a warning. Any OTHER failure
+     * (I/O error, corrupt/locked DB — a genuine whole-store fault) is rethrown unchanged,
+     * so the SDK's boot-restore full-failure invariant fires rather than papering over an
+     * unreadable store as healthy-but-empty (see `isRecoverableThreadEnumerationError`).
      */
     getThreadIds(agentId: string): Promise<string[]>;
+    /**
+     * Degraded thread enumeration via Mastra's high-level `listThreads` API, used when the
+     * resilient raw `SELECT id` path is unavailable for a recoverable reason (client absent
+     * or schema-shape drift). Logs a warning so the degradation is observable. NOTE: unlike
+     * the raw path, `listThreads` is itself vulnerable to a corrupt `metadata` row (the very
+     * defect `getThreadIds` exists to route around) — this is a best-effort fallback for the
+     * Mastra-rename scenario, not a second line of defense against metadata corruption.
+     */
+    private listThreadIdsFallback;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.

package/dist/mastra-harness.js

@@ -131,6 +131,27 @@ export function renderSessionContextSystemText(context) {
  * API surface (src/index.ts).
  */
 const LAST_MESSAGES_WINDOW = 40;
+/**
+ * Mastra's thread table (`@mastra/core`'s `TABLE_THREADS`). `getThreadIds` enumerates
+ * it with a column-only `SELECT id` to stay immune to a single corrupt `metadata` row
+ * (see the resilient-enumeration path in `getThreadIds`). Coupling to this name is the
+ * price of that immunity; the raw query is fallback-guarded so a future Mastra rename
+ * degrades to the high-level API rather than crashing enumeration.
+ */
+const MASTRA_THREADS_TABLE = 'mastra_threads';
+/**
+ * Decides whether a raw `getThreadIds` enumeration failure is a *recoverable* schema-shape
+ * drift (our column-only `SELECT id FROM mastra_threads` references a table/column a future
+ * Mastra renamed — libsql reports `no such table` / `no such column`), in which case the
+ * harness degrades to the high-level `listThreads` API. Every other failure (I/O error,
+ * corrupt or locked DB — a genuine whole-store fault) is deliberately NOT recoverable: it
+ * MUST propagate so the SDK's boot-restore full-failure invariant fires and the agent
+ * surfaces the fault rather than coming up silently empty. (spike #11, W-24014120)
+ */
+function isRecoverableThreadEnumerationError(err) {
+    const message = getErrorMessage(err).toLowerCase();
+    return message.includes('no such table') || message.includes('no such column');
+}
 /**
  * Maximum flattened-transcript length (in characters) sent to the model in a
  * single summarization call. Transcripts above this size are split into
@@ -1240,13 +1261,59 @@ export class MastraHarness {
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST query threads scoped to this agent and return their IDs.
+     * - MUST enumerate resiliently: a single thread whose persisted `metadata` is
+     *   corrupt MUST NOT suppress the agent's other thread IDs.
+     *
+     * Resilience rationale (spike agent-offline-failure-modes #11, W-24014120):
+     * `memory.listThreads` builds its SELECT as `json(metadata)` over every row, so one
+     * malformed-JSON row makes SQLite throw `SQLITE_ERROR: malformed JSON`; Mastra's
+     * catch swallows that and returns an EMPTY list — silently un-restoring every thread
+     * on the agent (the "one bad thread bricks the whole agent" symptom). We instead
+     * enumerate with a column-only `SELECT id` (both `id` and `resourceId` are plain
+     * TEXT, never parsed), which a corrupt `metadata` on another row cannot break. The
+     * raw query couples to Mastra's `mastra_threads` schema, so it is fallback-guarded —
+     * but ONLY for the failures the fallback is meant to survive:
+     *   - the libsql client isn't reachable (a future Mastra internals change), or
+     *   - the raw query hits a schema-shape drift (`no such table` / `no such column`).
+     * Both degrade to the high-level `listThreads` API with a warning. Any OTHER failure
+     * (I/O error, corrupt/locked DB — a genuine whole-store fault) is rethrown unchanged,
+     * so the SDK's boot-restore full-failure invariant fires rather than papering over an
+     * unreadable store as healthy-but-empty (see `isRecoverableThreadEnumerationError`).
      */
     async getThreadIds(agentId) {
         const memory = await this.getMemoryOrThrow(agentId);
-        const { threads } = await memory.listThreads({
-            filter: { resourceId: this.agentResourceId(agentId) },
-            perPage: false,
-        });
+        const resourceId = this.agentResourceId(agentId);
+        const client = this.storage.client;
+        if (typeof client?.execute !== 'function') {
+            return this.listThreadIdsFallback(agentId, memory, resourceId, 'LibSQLStore client is not accessible');
+        }
+        try {
+            const { rows } = await client.execute({
+                sql: `SELECT id FROM ${MASTRA_THREADS_TABLE} WHERE resourceId = ?`,
+                args: [resourceId],
+            });
+            return rows.map((row) => String(row['id']));
+        }
+        catch (err) {
+            if (!isRecoverableThreadEnumerationError(err)) {
+                throw err;
+            }
+            return this.listThreadIdsFallback(agentId, memory, resourceId, getErrorMessage(err));
+        }
+    }
+    /**
+     * Degraded thread enumeration via Mastra's high-level `listThreads` API, used when the
+     * resilient raw `SELECT id` path is unavailable for a recoverable reason (client absent
+     * or schema-shape drift). Logs a warning so the degradation is observable. NOTE: unlike
+     * the raw path, `listThreads` is itself vulnerable to a corrupt `metadata` row (the very
+     * defect `getThreadIds` exists to route around) — this is a best-effort fallback for the
+     * Mastra-rename scenario, not a second line of defense against metadata corruption.
+     */
+    async listThreadIdsFallback(agentId, memory, resourceId, reason) {
+        this.buses
+            .getLogBus()
+            ?.warn('getThreadIds: raw enumeration unavailable; falling back to listThreads', { agentId, reason });
+        const { threads } = await memory.listThreads({ filter: { resourceId }, perPage: false });
         return threads.map((t) => t.id);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -37,17 +37,17 @@
     "@mastra/mcp": "^1.15.0",
     "@mastra/memory": "^1.24.0",
     "@mastra/schema-compat": "^1.3.4",
-    "@salesforce/agentic-common": "0.17.0",
+    "@salesforce/agentic-common": "0.18.0",
     "@smithy/eventstream-codec": "^2.2.0",
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.57.0"
+    "@salesforce/sfdx-agent-sdk": "0.59.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.57.0",
+    "@salesforce/sfdx-agent-sdk": "0.59.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",