@salesforce/sfdx-agent-harness-mastra 0.53.0 → 0.54.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.54.0] - 2026-08-25
+
+### Features
+- **harness-mastra**: store session context in a harness-owned per-thread store @W-23632686@ ([#765](https://github.com/forcedotcom/agentic-dx/pull/765))
+
 ## [0.53.0] - 2026-08-25
 
 ### Chores

package/dist/mastra-harness.d.ts

@@ -12,6 +12,19 @@ import type { LanguageModelV3 } from '@ai-sdk/provider';
 import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
+/**
+ * Render a session-context object into the system text injected via `stream()`'s
+ * `system:` option — Mastra folds it into a `"user-provided"` system block,
+ * disjoint from `instructions` and the model's Working Memory `"memory"` block.
+ * Canonicalizes through the store's `sortJsonValue` so equal contexts render
+ * identically; `{}` renders to `''` so `stream()` omits the option entirely.
+ *
+ * The canonical JSON is emitted with `<`/`>` unicode-escaped (`\u003c` /
+ * `\u003e`). This lands in a system message, so a consumer value can't forge the
+ * `</session_context>` boundary — escaping the rendered form only, never the
+ * stored object's round-trip fidelity.
+ */
+export declare function renderSessionContextSystemText(context: SessionContext): string;
 /**
  * Per-server MCP state. Each enabled server gets its own MCPClient and
  * independent discovery promise so readiness is tracked individually.
@@ -250,21 +263,12 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly mastra;
     private readonly buses;
     /**
-     * Harness-owned disk persistence for the per-thread session-context channel.
-     * A dedicated JSON sidecar disjoint from the LibSQL-backed message store —
-     * a `setSessionContext` object MUST NOT appear in `getMessages()` output.
-     * Rooted at the same `storageRootFolder` the constructor receives.
-     *
-     * INTERIM: the session-context spike prescribes Mastra persist this over
-     * Working Memory (`memory.updateWorkingMemory` / `getWorkingMemory`, JSON
-     * mode — its native, already-enabled channel), not a sidecar. The sidecar
-     * ships here so the shared `runSessionContextConformance` persistence gate is
-     * green on all three harnesses in this milestone; W-23632686 replaces this
-     * store with Working Memory (Claude/OpenAI keep their sidecars). The
-     * consumer-visible contract — whole-object set, `{}`-on-miss, absent from
-     * `getMessages` — is identical across both, so the swap is internal.
+     * Harness-owned store backing `setSessionContext` / `getSessionContext` —
+     * disjoint from Mastra's Working Memory (`this.memory`), so it shares no
+     * value with the model's native `updateWorkingMemory` writes and the two
+     * can't race. See the session-context Critical Invariant in ARCHITECTURE.md.
      */
-    private readonly sessionContext;
+    private readonly sessionContextStore;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -395,6 +399,9 @@ export declare class MastraHarness implements MastraAgentHarness {
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST clone the source thread's messages into a new thread.
+     * - MUST copy the source thread's stored session context onto the clone —
+     *   Mastra's native clone copies the thread row but not the harness-owned
+     *   store, so without this the clone would silently start `{}`.
      */
     cloneThread(agentId: string, sourceThreadId: string): Promise<string>;
     /**
@@ -552,20 +559,52 @@ export declare class MastraHarness implements MastraAgentHarness {
     /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
     addContext(agentId: string, threadId: string, messages: Message[]): Promise<void>;
     /**
-     * Replace this thread's session-context object in full. Whole-object set
-     * (not a merge); persisted verbatim to the harness-owned sidecar, disjoint
-     * from the message transcript — the set object never appears in
-     * `getMessages()`. Throws `AGENT_NOT_FOUND` for an unknown agent before any
-     * store access.
+     * Replace this thread's consumer session-context object in full (whole-object
+     * set, not a merge), persisted to the harness-owned store — disjoint from
+     * Mastra's Working Memory, so it never races the model's native
+     * `updateWorkingMemory` writes and never surfaces in `getMessages()`.
+     * `getAgentStateOrThrow` first (`AGENT_NOT_FOUND`); then create-first via
+     * {@link assertThreadExists} (the store itself has no thread concept), which
+     * throws `THREAD_NOT_FOUND` for an uncreated thread. Size/depth guards live in
+     * `SessionContextStore.write`.
      */
     setSessionContext(agentId: string, threadId: string, content: SessionContext): Promise<void>;
     /**
-     * This thread's persisted session-context object, or `{}` when nothing has
-     * been set (or the sidecar is unparseable). Never `null`/`undefined`, never
-     * throws on a miss. Throws `AGENT_NOT_FOUND` for an unknown agent before any
-     * store access.
+     * This thread's consumer session-context object read back from the
+     * harness-owned session context store, or `{}` when nothing has been set.
+     * Never `null`/`undefined`, never throws on a miss (corrupt files are
+     * soft-skipped to `{}` and logged inside the store). `getAgentStateOrThrow`
+     * runs first so an unregistered agent surfaces `AGENT_NOT_FOUND` before any
+     * store touch.
      */
     getSessionContext(agentId: string, threadId: string): Promise<SessionContext>;
+    /**
+     * Create-first guard for `setSessionContext`: throws typed `THREAD_NOT_FOUND`
+     * when `threadId` was never created *for this agent* (Mastra's `Memory` is the
+     * thread registry). We must enforce the `resourceId` scope ourselves — Mastra's
+     * `getThreadById({ threadId, resourceId })` wrapper (`@mastra/core` 1.55) drops
+     * the `resourceId` arg, so on a shared `Memory` agent A's thread would satisfy
+     * a raw check for agent B. The returned `StorageThreadType` carries
+     * `resourceId`, so we assert it matches (consistent with `getThreadIds`'
+     * scoping). Only reachable when a caller reuses an id across agents; the SDK's
+     * `ChatSession` path always mints UUIDs.
+     */
+    private assertThreadExists;
+    /**
+     * The system text this thread's stored session context would inject on the
+     * next turn — renders via the SAME {@link renderSessionContextSystemText}
+     * `stream()` calls, so this seam observes exactly what a turn would inject.
+     * Not on the `AgentHarness` contract: its only caller is this harness's
+     * conformance seam (`test/conformance` supplies `renderSystemContext`).
+     */
+    renderSessionContextSystemContext(agentId: string, threadId: string): Promise<string>;
+    /**
+     * Copy a thread's stored session context onto another thread — used by
+     * `compactThread` (onto the compacted thread before the source retires) and
+     * `cloneThread` (Mastra's native clone doesn't know about this store). Skips
+     * the write when the source is `{}`, since a missing file already reads `{}`.
+     */
+    private carrySessionContextForward;
     /**
      * Issue a single non-agentic model call (`maxSteps: 1`) for one-shot
      * summarization. Used internally by `compactThread()`; not part of the

package/dist/mastra-harness.js

@@ -15,10 +15,10 @@ import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, r
 import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, mergeToolResultsIntoAssistant, splitToolResultsIntoToolMessages, } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import { MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
-import { SessionContextStore } from './session-context-store.js';
 import { SKILL_SEARCH_META_TOOL_NAMES, TOOL_SEARCH_META_TOOL_NAMES } from './skill-bridge.js';
 import { mapMastraToMessage, mapMessageToMastra, partToTranscriptText } from './mastra-message-mapper.js';
 import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/schema-compat';
+import { SessionContextStore, sortJsonValue } from './session-context-store.js';
 import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
 import { hasEnabledServers, mapToMastraMCPServers } from './mcp-config-mapper.js';
 import { buildMcpErrorDetail, sanitizeMcpErrorMessage, synthesizeHttpTransportError } from './mcp-error-classifier.js';
@@ -64,6 +64,26 @@ function stripMastraWorkspacePrefix(name) {
 function isDisposedError(err) {
     return err instanceof AgentSDKError && err.type === AgentSDKErrorType.DISPOSED;
 }
+/** Opening/closing tags wrapping the rendered session-context block so the model can recognize it as standing context, distinct from its own Working Memory. */
+const SESSION_CONTEXT_TAG = 'session_context';
+/**
+ * Render a session-context object into the system text injected via `stream()`'s
+ * `system:` option — Mastra folds it into a `"user-provided"` system block,
+ * disjoint from `instructions` and the model's Working Memory `"memory"` block.
+ * Canonicalizes through the store's `sortJsonValue` so equal contexts render
+ * identically; `{}` renders to `''` so `stream()` omits the option entirely.
+ *
+ * The canonical JSON is emitted with `<`/`>` unicode-escaped (`\u003c` /
+ * `\u003e`). This lands in a system message, so a consumer value can't forge the
+ * `</session_context>` boundary — escaping the rendered form only, never the
+ * stored object's round-trip fidelity.
+ */
+export function renderSessionContextSystemText(context) {
+    if (Object.keys(context).length === 0)
+        return '';
+    const canonical = JSON.stringify(sortJsonValue(context, 0)).replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+    return `<${SESSION_CONTEXT_TAG}>\n${canonical}\n</${SESSION_CONTEXT_TAG}>`;
+}
 /**
  * Mastra-backed implementation of {@link AgentHarness}.
  *
@@ -368,21 +388,12 @@ export class MastraHarness {
     mastra;
     buses = new HarnessBusOwner();
     /**
-     * Harness-owned disk persistence for the per-thread session-context channel.
-     * A dedicated JSON sidecar disjoint from the LibSQL-backed message store —
-     * a `setSessionContext` object MUST NOT appear in `getMessages()` output.
-     * Rooted at the same `storageRootFolder` the constructor receives.
-     *
-     * INTERIM: the session-context spike prescribes Mastra persist this over
-     * Working Memory (`memory.updateWorkingMemory` / `getWorkingMemory`, JSON
-     * mode — its native, already-enabled channel), not a sidecar. The sidecar
-     * ships here so the shared `runSessionContextConformance` persistence gate is
-     * green on all three harnesses in this milestone; W-23632686 replaces this
-     * store with Working Memory (Claude/OpenAI keep their sidecars). The
-     * consumer-visible contract — whole-object set, `{}`-on-miss, absent from
-     * `getMessages` — is identical across both, so the swap is internal.
+     * Harness-owned store backing `setSessionContext` / `getSessionContext` —
+     * disjoint from Mastra's Working Memory (`this.memory`), so it shares no
+     * value with the model's native `updateWorkingMemory` writes and the two
+     * can't race. See the session-context Critical Invariant in ARCHITECTURE.md.
      */
-    sessionContext;
+    sessionContextStore;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -435,7 +446,16 @@ export class MastraHarness {
                 semanticRecall: false,
                 workingMemory: {
                     enabled: true,
+                    // Thread scope keeps each conversation's Working Memory
+                    // isolated (Mastra's default is resource scope, which would
+                    // share one slot across every thread on the agent).
                     scope: 'thread',
+                    // `agentManaged: true` (Mastra's default) keeps the native
+                    // `updateWorkingMemory` tool — the model's own scratchpad, and
+                    // this slot alone. Consumer session context lives in the
+                    // separate `this.sessionContextStore`, so the harness has
+                    // nothing to partition out of here.
+                    agentManaged: true,
                 },
             },
         });
@@ -443,7 +463,7 @@ export class MastraHarness {
             storage: this.storage,
             memory: { shared: this.memory },
         });
-        this.sessionContext = new SessionContextStore(this.storageRootFolder, this.buses.getLogBus());
+        this.sessionContextStore = new SessionContextStore(this.storageRootFolder, this.buses.getLogBus());
     }
     /**
      * @requirements
@@ -739,10 +759,9 @@ export class MastraHarness {
         }));
         state.skillSearchProcessor?.dispose();
         await state.mastraWorkspace?.destroy();
-        // Remove every session-context sidecar for this agent so teardown leaves
-        // no orphaned context behind (per-thread destroyThread isn't called for
-        // each thread on agent destruction).
-        await this.sessionContext.deleteAgent(agentId);
+        // The store is separate from Mastra's thread rows, so it needs its own
+        // teardown — remove every thread's stored context for this agent.
+        await this.sessionContextStore.deleteAgent(agentId);
         this.mastra.removeAgent(agentId);
         this.modelConnectivityByAgent.delete(agentId);
         return this.activeAgents.delete(agentId);
@@ -1213,10 +1232,9 @@ export class MastraHarness {
         }
         const memory = await this.getMemoryOrThrow(agentId);
         await memory.deleteThread(threadId);
-        // Drop the session-context sidecar too, so a destroyed thread leaves no
-        // orphaned context that a same-id recreate would resurrect. Runs on the
-        // store's own serialize queue; ENOENT-tolerant for a never-set thread.
-        await this.sessionContext.delete(agentId, threadId);
+        // The store is separate from Mastra's thread row, so delete it too or a
+        // same-id recreate would resurrect the destroyed thread's context.
+        await this.sessionContextStore.delete(agentId, threadId);
     }
     /**
      * @requirements
@@ -1235,10 +1253,23 @@ export class MastraHarness {
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST clone the source thread's messages into a new thread.
+     * - MUST copy the source thread's stored session context onto the clone —
+     *   Mastra's native clone copies the thread row but not the harness-owned
+     *   store, so without this the clone would silently start `{}`.
      */
     async cloneThread(agentId, sourceThreadId) {
         const memory = await this.getMemoryOrThrow(agentId);
         const { thread } = await memory.cloneThread({ sourceThreadId });
+        // Native clone already persisted the new thread; if the store copy then
+        // fails (a genuine FS error), delete the orphan before rethrowing so a
+        // failed clone leaves no thread the caller never got an id for.
+        try {
+            await this.carrySessionContextForward(agentId, sourceThreadId, thread.id);
+        }
+        catch (err) {
+            await this.destroyThreadBestEffort(agentId, thread.id);
+            throw err;
+        }
         return thread.id;
     }
     /**
@@ -1268,6 +1299,21 @@ export class MastraHarness {
         const messages = await this.getMessages(agentId, threadId);
         if (messages.length === 0) {
             const newThreadId = await this.createThread(agentId);
+            // An empty transcript can still carry session context (it's set
+            // independently of messages), so carry it forward here too — before
+            // the source is retired, and fail-closed (source left intact on a
+            // copy failure) to match the main path's COMPACTION_FAILED contract.
+            try {
+                await this.carrySessionContextForward(agentId, threadId, newThreadId);
+            }
+            catch (err) {
+                // The new thread was already created; a carry-forward failure
+                // orphans it (never returned, never retired). Delete it before
+                // surfacing COMPACTION_FAILED so a failed compaction leaves no
+                // trace beyond the still-intact source thread.
+                await this.destroyThreadBestEffort(agentId, newThreadId);
+                throw new AgentSDKError(`Failed to compact thread "${threadId}" for agent "${agentId}": ${getErrorMessage(err)}`, AgentSDKErrorType.COMPACTION_FAILED, { cause: err });
+            }
             // Empty source still gets compacted away — leaving it attached
             // would be a leak. Mirrors the non-empty path's destroyThread
             // call below; both paths exit with the source detached.
@@ -1280,6 +1326,9 @@ export class MastraHarness {
             return `${m.role}: ${text}`;
         })
             .join('\n');
+        // `undefined` until `createThread` succeeds, so the catch can tell a
+        // pre-create failure (nothing to clean up) from a post-create failure
+        // (the new thread is orphaned and must be deleted).
         let newThreadId;
         try {
             const summaryText = transcript.length <= MAX_TRANSCRIPT_CHARS
@@ -1302,8 +1351,19 @@ export class MastraHarness {
                     createdAt: assistantTs,
                 },
             ]);
+            // Carry the source thread's session context onto the compacted thread
+            // before the source is retired. Inside the try so a copy failure is
+            // fail-closed (surfaces as COMPACTION_FAILED, source left intact).
+            await this.carrySessionContextForward(agentId, threadId, newThreadId);
         }
         catch (err) {
+            // If the failure came after `createThread`, the new thread is
+            // orphaned (never returned to the caller, source not yet retired).
+            // Delete it so a failed compaction leaves no trace beyond the
+            // still-intact source thread.
+            if (newThreadId !== undefined) {
+                await this.destroyThreadBestEffort(agentId, newThreadId);
+            }
             throw new AgentSDKError(`Failed to compact thread "${threadId}" for agent "${agentId}": ${getErrorMessage(err)}`, AgentSDKErrorType.COMPACTION_FAILED, { cause: err });
         }
         // Source-thread cleanup is best-effort. The user's data is already
@@ -1520,6 +1580,12 @@ export class MastraHarness {
                 systemPrompt: agentState.composedInstructions,
             });
         }
+        // Deliver the consumer session context for this turn via the `system:`
+        // option below (see `renderSessionContextSystemText`). `read` softens
+        // never-set/corrupt to `{}` but rejects a genuine FS fault (EACCES/EIO),
+        // failing the turn rather than silently dropping context for it.
+        const sessionContext = await this.sessionContextStore.read(agentId, threadId);
+        const systemContext = renderSessionContextSystemText(sessionContext);
         const output = await agentState.agent.stream(streamInput, {
             memory: {
                 thread: threadId,
@@ -1528,6 +1594,7 @@ export class MastraHarness {
             requestContext: this.buildRequestContext(agentId, threadId),
             maxSteps: options?.maxSteps ?? DEFAULT_MAX_STEPS,
             abortSignal: options?.abortSignal,
+            ...(systemContext.length > 0 ? { system: systemContext } : {}),
             // Pass `requireToolApproval: true` to Mastra iff the gate is active
             // so Mastra suspends every non-consumer tool with a
             // `tool-call-approval` chunk and the coordinator can consult the
@@ -1731,27 +1798,78 @@ export class MastraHarness {
         await this.addMessages(agentId, threadId, messages);
     }
     /**
-     * Replace this thread's session-context object in full. Whole-object set
-     * (not a merge); persisted verbatim to the harness-owned sidecar, disjoint
-     * from the message transcript — the set object never appears in
-     * `getMessages()`. Throws `AGENT_NOT_FOUND` for an unknown agent before any
-     * store access.
+     * Replace this thread's consumer session-context object in full (whole-object
+     * set, not a merge), persisted to the harness-owned store — disjoint from
+     * Mastra's Working Memory, so it never races the model's native
+     * `updateWorkingMemory` writes and never surfaces in `getMessages()`.
+     * `getAgentStateOrThrow` first (`AGENT_NOT_FOUND`); then create-first via
+     * {@link assertThreadExists} (the store itself has no thread concept), which
+     * throws `THREAD_NOT_FOUND` for an uncreated thread. Size/depth guards live in
+     * `SessionContextStore.write`.
      */
     async setSessionContext(agentId, threadId, content) {
         this.getAgentStateOrThrow(agentId);
-        await this.sessionContext.write(agentId, threadId, content);
+        // Run the create-first check as a write precondition INSIDE the store's
+        // serialize queue so check + write are one critical section against a
+        // concurrent `destroyThread` → `store.delete`; a bare check-then-write
+        // would let the delete land between them and recreate an orphan file.
+        await this.sessionContextStore.write(agentId, threadId, content, () => this.assertThreadExists(agentId, threadId));
     }
     /**
-     * This thread's persisted session-context object, or `{}` when nothing has
-     * been set (or the sidecar is unparseable). Never `null`/`undefined`, never
-     * throws on a miss. Throws `AGENT_NOT_FOUND` for an unknown agent before any
-     * store access.
+     * This thread's consumer session-context object read back from the
+     * harness-owned session context store, or `{}` when nothing has been set.
+     * Never `null`/`undefined`, never throws on a miss (corrupt files are
+     * soft-skipped to `{}` and logged inside the store). `getAgentStateOrThrow`
+     * runs first so an unregistered agent surfaces `AGENT_NOT_FOUND` before any
+     * store touch.
      */
     async getSessionContext(agentId, threadId) {
         this.getAgentStateOrThrow(agentId);
-        return this.sessionContext.read(agentId, threadId);
+        return this.sessionContextStore.read(agentId, threadId);
+    }
+    /**
+     * Create-first guard for `setSessionContext`: throws typed `THREAD_NOT_FOUND`
+     * when `threadId` was never created *for this agent* (Mastra's `Memory` is the
+     * thread registry). We must enforce the `resourceId` scope ourselves — Mastra's
+     * `getThreadById({ threadId, resourceId })` wrapper (`@mastra/core` 1.55) drops
+     * the `resourceId` arg, so on a shared `Memory` agent A's thread would satisfy
+     * a raw check for agent B. The returned `StorageThreadType` carries
+     * `resourceId`, so we assert it matches (consistent with `getThreadIds`'
+     * scoping). Only reachable when a caller reuses an id across agents; the SDK's
+     * `ChatSession` path always mints UUIDs.
+     */
+    async assertThreadExists(agentId, threadId) {
+        const memory = await this.getMemoryOrThrow(agentId);
+        const thread = await memory.getThreadById({ threadId, resourceId: this.agentResourceId(agentId) });
+        if (thread === null || thread.resourceId !== this.agentResourceId(agentId)) {
+            throw new AgentSDKError(`Cannot set session context on thread "${threadId}": the thread was never created for this agent (create-first contract).`, AgentSDKErrorType.THREAD_NOT_FOUND);
+        }
     }
     // ── Private Helpers ──────────────────────────────────────────────
+    /**
+     * The system text this thread's stored session context would inject on the
+     * next turn — renders via the SAME {@link renderSessionContextSystemText}
+     * `stream()` calls, so this seam observes exactly what a turn would inject.
+     * Not on the `AgentHarness` contract: its only caller is this harness's
+     * conformance seam (`test/conformance` supplies `renderSystemContext`).
+     */
+    async renderSessionContextSystemContext(agentId, threadId) {
+        this.getAgentStateOrThrow(agentId);
+        const context = await this.sessionContextStore.read(agentId, threadId);
+        return renderSessionContextSystemText(context);
+    }
+    /**
+     * Copy a thread's stored session context onto another thread — used by
+     * `compactThread` (onto the compacted thread before the source retires) and
+     * `cloneThread` (Mastra's native clone doesn't know about this store). Skips
+     * the write when the source is `{}`, since a missing file already reads `{}`.
+     */
+    async carrySessionContextForward(agentId, sourceThreadId, targetThreadId) {
+        const content = await this.sessionContextStore.read(agentId, sourceThreadId);
+        if (Object.keys(content).length === 0)
+            return;
+        await this.sessionContextStore.write(agentId, targetThreadId, content);
+    }
     /**
      * Issue a single non-agentic model call (`maxSteps: 1`) for one-shot
      * summarization. Used internally by `compactThread()`; not part of the

package/dist/mastra-message-mapper.d.ts

@@ -36,8 +36,10 @@ export declare function mapMastraToMessage(msg: MastraDBMessage, logBus?: LogBus
 export declare function mapMastraPartToMessagePart(part: MastraMessagePart, logBus?: LogBus): MessagePart[];
 /**
  * Converts an SDK {@link Message} into the Mastra persisted message format.
- * The `role` field is normalised: `'tool'` role (which has no Mastra equivalent)
- * is coerced to `'assistant'`.
+ * A bare `role: 'tool'` message is PRESERVED as `'tool'` (Mastra's
+ * `MastraDBMessage` role union includes `'tool'`), so a hand-authored tool
+ * message written via `addContext` reads back as `'tool'` rather than being
+ * rewritten to `'assistant'` — the cross-harness bare-`tool` fidelity contract.
  */
 export declare function mapMessageToMastra(msg: Message, threadId: string, resourceId: string): MastraDBMessage;
 /**

package/dist/mastra-message-mapper.js

@@ -226,8 +226,10 @@ export function mapMastraPartToMessagePart(part, logBus) {
 }
 /**
  * Converts an SDK {@link Message} into the Mastra persisted message format.
- * The `role` field is normalised: `'tool'` role (which has no Mastra equivalent)
- * is coerced to `'assistant'`.
+ * A bare `role: 'tool'` message is PRESERVED as `'tool'` (Mastra's
+ * `MastraDBMessage` role union includes `'tool'`), so a hand-authored tool
+ * message written via `addContext` reads back as `'tool'` rather than being
+ * rewritten to `'assistant'` — the cross-harness bare-`tool` fidelity contract.
  */
 export function mapMessageToMastra(msg, threadId, resourceId) {
     const parts = [];
@@ -254,7 +256,6 @@ export function mapMessageToMastra(msg, threadId, resourceId) {
             parts.push(mapMessagePartToMastra(part));
         }
     }
-    const role = msg.role === 'tool' ? 'assistant' : msg.role;
     if (!msg.createdAt) {
         // Internal contract: callers (the harness's `addContext` and
         // `compactThread`) backfill `createdAt` before reaching this
@@ -267,7 +268,13 @@ export function mapMessageToMastra(msg, threadId, resourceId) {
     }
     return {
         id: msg.id,
-        role,
+        // Preserve `'tool'` rather than coercing it to `'assistant'`. Mastra's
+        // `MastraDBMessage.role` static type is `'user'|'assistant'|'system'|'signal'`
+        // (it omits `'tool'`), but LibSQL persists the role verbatim and the read
+        // path (`mapMastraToMessage`) maps `'tool'` straight back, so a bare tool
+        // message round-trips as `'tool'`. The narrow cast records that the runtime
+        // role space is wider than this Mastra version's write-side type.
+        role: msg.role,
         createdAt: msg.createdAt,
         threadId,
         resourceId,

package/dist/session-context-store.d.ts

@@ -1,39 +1,24 @@
 import { type LogBus } from '@salesforce/agentic-common';
-import type { SessionContext } from '@salesforce/sfdx-agent-sdk';
+import { type JsonValue, type SessionContext } from '@salesforce/sfdx-agent-sdk';
 /**
- * Harness-owned disk persistence for per-thread session context. One JSON file
- * per `(agentId, threadId)` under `${storageRootFolder}/session-context/`:
- *
- *     ${storageRootFolder}/session-context/
- *       <agentId>/
- *         <threadId>.json        ← a single {@link SessionContext} object
- *
- * A dedicated sidecar channel, disjoint from the message transcript (the
- * LibSQL-backed `Memory` store) — the session-context contract requires this
- * object NOT appear in `getMessages` output. The store persists the object
- * verbatim (the full `JsonValue` union) so a nested / array / null-bearing
- * context round-trips unchanged.
- *
- * **Whole-file rewrite via `.tmp` + `rename`.** Each `write` is a whole-object
- * replacement (`setSessionContext` is a whole-object set, not a merge) written
- * to a `.tmp` sibling then `rename`d over the target — atomic on POSIX; the
- * per-`(agentId, threadId)` in-flight queue handles the Windows
- * concurrent-rename EPERM and serializes concurrent read/write cycles on the
- * same thread. Mirrors the SDK `AgentIdentityStore` atomic-write shape.
- *
- * **`{}`-on-miss, never null, never throw on a miss.** `read` returns `{}` when
- * nothing was ever set (`ENOENT`) — an empty and a never-set context are
- * behaviorally identical, so callers need no null-check. A corrupt file is
- * logged (`LogBus.warn`) and treated as empty rather than failing every read
- * (the `AgentIdentityStore` soft-skip posture); the corrupt file stays on disk
- * and the next `write` overwrites it cleanly.
- *
- * A deliberate behavioral copy of the OpenAI harness's `SessionContextStore`.
- * Each harness keeps its own copy rather than importing a sibling's — harness
- * independence is enforced by no harness `package.json` declaring another
- * harness as a dependency (the same reason each harness carries its own
- * `mcp-error-classifier`). Drift is guarded by the shared
- * `runSessionContextConformance` table.
+ * Recursively key-sort a JSON value (objects only; arrays keep order) so
+ * structurally-equal contexts serialize byte-identically. Rejects objects
+ * deeper than {@link MAX_SESSION_CONTEXT_DEPTH} with a typed error instead of a
+ * raw stack-overflow `RangeError`. Exported for reuse by the per-turn `system:`
+ * renderer in `mastra-harness.ts`.
+ */
+export declare function sortJsonValue(value: JsonValue, depth: number): JsonValue;
+/**
+ * Harness-owned disk persistence for per-thread session context — one JSON file
+ * per `(agentId, threadId)` under `${storageRootFolder}/session-context/`,
+ * physically disjoint from Mastra's Working Memory and absent from `getMessages`.
+ * As the sole writer of this channel, it shares no value with the model's native
+ * `updateWorkingMemory` writes, so the two never race. Whole-object `write` via
+ * `.tmp` + `rename` (atomic on POSIX); a per-`(agentId, threadId)` in-flight
+ * queue serializes read/write cycles and covers Windows rename EPERM. `read`
+ * returns `{}` on miss or corruption (logged), never null, never throws on a
+ * miss. A behavioral copy of the Claude / OpenAI harness stores (harnesses can't
+ * depend on each other); drift-guarded by `runSessionContextConformance`.
  */
 export declare class SessionContextStore {
     private readonly storageRootFolder;
@@ -47,27 +32,19 @@ export declare class SessionContextStore {
      */
     read(agentId: string, threadId: string): Promise<SessionContext>;
     /**
-     * Replace this thread's session-context object in full. Persisted verbatim
-     * so the whole `JsonValue` union survives a round-trip.
-     */
-    write(agentId: string, threadId: string, content: SessionContext): Promise<void>;
-    /**
-     * Delete this thread's persisted session-context file. Called from thread
-     * (and agent) teardown so a destroyed thread leaves no orphaned sidecar that
-     * a same-id recreate would resurrect. ENOENT-tolerant — deleting a thread
-     * whose context was never set is a no-op, not an error. Runs on the same
-     * per-thread serialize queue as read/write so it can't race a concurrent
-     * write.
+     * Replace this thread's session-context object in full. The optional
+     * `precondition` runs inside the serialize queue just before the write, so a
+     * caller's create-first check and the write form one critical section against
+     * a concurrent `delete`; a throwing precondition writes nothing.
      */
+    write(agentId: string, threadId: string, content: SessionContext, precondition?: () => Promise<void>): Promise<void>;
+    /** Delete this thread's file (ENOENT-tolerant), on the serialize queue so it can't race a write. */
     delete(agentId: string, threadId: string): Promise<void>;
     /**
-     * Delete every persisted session-context file for an agent (its whole
-     * `session-context/<agentId>/` directory). Called from agent teardown so a
-     * destroyed agent leaves no orphaned sidecars behind — covers all threads in
-     * one op without enumerating them. ENOENT-tolerant (an agent that never set
-     * any context has no directory). Not routed through the per-thread serialize
-     * queue: agent destruction is terminal, so there is no legitimate concurrent
-     * per-thread write to order against.
+     * Delete an agent's whole `session-context/<agentId>/` directory (ENOENT-tolerant).
+     * Drains in-flight per-thread ops first — the per-thread queue can't cover an
+     * agent-wide op, so without the drain a queued write could `rename` after the
+     * `rm` and leave an orphan dir a recreate would resurrect.
      */
     deleteAgent(agentId: string): Promise<void>;
     private readContext;
@@ -76,12 +53,8 @@ export declare class SessionContextStore {
     private dirFor;
     private fileFor;
     /**
-     * Per-`(agentId, threadId)` in-flight queue. Ported from the OpenAI
-     * harness's `SessionContextStore.serialize` — serializes read-mutate-write
-     * cycles on the same thread so a concurrent `setSessionContext` and
-     * `getSessionContext` never interleave a read against a half-written file.
-     * Keyed by the SAME injective encoding as {@link fileFor}, so two ids that
-     * only differ in punctuation get distinct queues (not one shared queue).
+     * Per-`(agentId, threadId)` in-flight queue so read/write cycles on one thread
+     * never interleave. Keyed by the same injective encoding as {@link fileFor}.
      */
     private serialize;
 }

package/dist/session-context-store.js

@@ -5,42 +5,64 @@
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { getErrorMessage } from '@salesforce/agentic-common';
+import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
 const SESSION_CONTEXT_SUBDIR = 'session-context';
 const FILE_EXT = '.json';
 /**
- * Harness-owned disk persistence for per-thread session context. One JSON file
- * per `(agentId, threadId)` under `${storageRootFolder}/session-context/`:
- *
- *     ${storageRootFolder}/session-context/
- *       <agentId>/
- *         <threadId>.json        ← a single {@link SessionContext} object
- *
- * A dedicated sidecar channel, disjoint from the message transcript (the
- * LibSQL-backed `Memory` store) — the session-context contract requires this
- * object NOT appear in `getMessages` output. The store persists the object
- * verbatim (the full `JsonValue` union) so a nested / array / null-bearing
- * context round-trips unchanged.
- *
- * **Whole-file rewrite via `.tmp` + `rename`.** Each `write` is a whole-object
- * replacement (`setSessionContext` is a whole-object set, not a merge) written
- * to a `.tmp` sibling then `rename`d over the target — atomic on POSIX; the
- * per-`(agentId, threadId)` in-flight queue handles the Windows
- * concurrent-rename EPERM and serializes concurrent read/write cycles on the
- * same thread. Mirrors the SDK `AgentIdentityStore` atomic-write shape.
- *
- * **`{}`-on-miss, never null, never throw on a miss.** `read` returns `{}` when
- * nothing was ever set (`ENOENT`) — an empty and a never-set context are
- * behaviorally identical, so callers need no null-check. A corrupt file is
- * logged (`LogBus.warn`) and treated as empty rather than failing every read
- * (the `AgentIdentityStore` soft-skip posture); the corrupt file stays on disk
- * and the next `write` overwrites it cleanly.
- *
- * A deliberate behavioral copy of the OpenAI harness's `SessionContextStore`.
- * Each harness keeps its own copy rather than importing a sibling's — harness
- * independence is enforced by no harness `package.json` declaring another
- * harness as a dependency (the same reason each harness carries its own
- * `mcp-error-classifier`). Drift is guarded by the shared
- * `runSessionContextConformance` table.
+ * Max serialized size (UTF-8 bytes) of a stored context. `write` throws above
+ * this rather than letting an oversized object ride into every turn's system
+ * context. Generous — context is for identifiers/flags, not payloads.
+ */
+const MAX_SESSION_CONTEXT_BYTES = 256 * 1024;
+/** Max object nesting depth `sortJsonValue` will recurse before rejecting. */
+const MAX_SESSION_CONTEXT_DEPTH = 200;
+/**
+ * Recursively key-sort a JSON value (objects only; arrays keep order) so
+ * structurally-equal contexts serialize byte-identically. Rejects objects
+ * deeper than {@link MAX_SESSION_CONTEXT_DEPTH} with a typed error instead of a
+ * raw stack-overflow `RangeError`. Exported for reuse by the per-turn `system:`
+ * renderer in `mastra-harness.ts`.
+ */
+export function sortJsonValue(value, depth) {
+    if (depth > MAX_SESSION_CONTEXT_DEPTH) {
+        throw new AgentSDKError(`Session context exceeds the maximum nesting depth of ${MAX_SESSION_CONTEXT_DEPTH}.`, AgentSDKErrorType.INVALID_MESSAGE_CONTENT);
+    }
+    if (Array.isArray(value))
+        return value.map((v) => sortJsonValue(v, depth + 1));
+    if (value === null || typeof value !== 'object')
+        return value;
+    // Null-prototype, not `{}`: assigning a `"__proto__"` key (legal in JSON)
+    // on a plain object hits the prototype setter and silently drops the key.
+    const sorted = Object.create(null);
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortJsonValue(value[key], depth + 1);
+    }
+    return sorted;
+}
+/** Canonical (recursively key-sorted) JSON so equal contexts render identically. */
+function canonicalizeSessionContext(value) {
+    return JSON.stringify(sortJsonValue(value, 0));
+}
+/** Canonicalize + enforce the size cap; throws `INVALID_MESSAGE_CONTENT` over the limit. */
+function serializeSessionContext(value) {
+    const serialized = canonicalizeSessionContext(value);
+    const bytes = Buffer.byteLength(serialized, 'utf8');
+    if (bytes > MAX_SESSION_CONTEXT_BYTES) {
+        throw new AgentSDKError(`Session context is ${bytes} bytes, above the ${MAX_SESSION_CONTEXT_BYTES}-byte limit.`, AgentSDKErrorType.INVALID_MESSAGE_CONTENT);
+    }
+    return serialized;
+}
+/**
+ * Harness-owned disk persistence for per-thread session context — one JSON file
+ * per `(agentId, threadId)` under `${storageRootFolder}/session-context/`,
+ * physically disjoint from Mastra's Working Memory and absent from `getMessages`.
+ * As the sole writer of this channel, it shares no value with the model's native
+ * `updateWorkingMemory` writes, so the two never race. Whole-object `write` via
+ * `.tmp` + `rename` (atomic on POSIX); a per-`(agentId, threadId)` in-flight
+ * queue serializes read/write cycles and covers Windows rename EPERM. `read`
+ * returns `{}` on miss or corruption (logged), never null, never throws on a
+ * miss. A behavioral copy of the Claude / OpenAI harness stores (harnesses can't
+ * depend on each other); drift-guarded by `runSessionContextConformance`.
  */
 export class SessionContextStore {
     storageRootFolder;
@@ -59,33 +81,34 @@ export class SessionContextStore {
         return this.serialize(agentId, threadId, () => this.readContext(agentId, threadId));
     }
     /**
-     * Replace this thread's session-context object in full. Persisted verbatim
-     * so the whole `JsonValue` union survives a round-trip.
+     * Replace this thread's session-context object in full. The optional
+     * `precondition` runs inside the serialize queue just before the write, so a
+     * caller's create-first check and the write form one critical section against
+     * a concurrent `delete`; a throwing precondition writes nothing.
      */
-    async write(agentId, threadId, content) {
-        await this.serialize(agentId, threadId, () => this.writeContext(agentId, threadId, content));
+    async write(agentId, threadId, content, precondition) {
+        await this.serialize(agentId, threadId, async () => {
+            if (precondition)
+                await precondition();
+            await this.writeContext(agentId, threadId, content);
+        });
     }
-    /**
-     * Delete this thread's persisted session-context file. Called from thread
-     * (and agent) teardown so a destroyed thread leaves no orphaned sidecar that
-     * a same-id recreate would resurrect. ENOENT-tolerant — deleting a thread
-     * whose context was never set is a no-op, not an error. Runs on the same
-     * per-thread serialize queue as read/write so it can't race a concurrent
-     * write.
-     */
+    /** Delete this thread's file (ENOENT-tolerant), on the serialize queue so it can't race a write. */
     async delete(agentId, threadId) {
         await this.serialize(agentId, threadId, () => this.deleteContext(agentId, threadId));
     }
     /**
-     * Delete every persisted session-context file for an agent (its whole
-     * `session-context/<agentId>/` directory). Called from agent teardown so a
-     * destroyed agent leaves no orphaned sidecars behind — covers all threads in
-     * one op without enumerating them. ENOENT-tolerant (an agent that never set
-     * any context has no directory). Not routed through the per-thread serialize
-     * queue: agent destruction is terminal, so there is no legitimate concurrent
-     * per-thread write to order against.
+     * Delete an agent's whole `session-context/<agentId>/` directory (ENOENT-tolerant).
+     * Drains in-flight per-thread ops first — the per-thread queue can't cover an
+     * agent-wide op, so without the drain a queued write could `rename` after the
+     * `rm` and leave an orphan dir a recreate would resurrect.
      */
     async deleteAgent(agentId) {
+        const prefix = `${encodeSegment(agentId)} `;
+        const inFlight = [...this.inflight.entries()]
+            .filter(([k]) => k.startsWith(prefix))
+            .map(([, p]) => p.catch(() => undefined));
+        await Promise.all(inFlight);
         await rm(this.dirFor(agentId), { recursive: true, force: true });
     }
     // ── Internals (called only inside `serialize`) ───────────────────────────
@@ -111,10 +134,7 @@ export class SessionContextStore {
             });
             return {};
         }
-        // A bare array / scalar / null parsed cleanly but is not the on-disk
-        // SessionContext object shape — as good as corrupt, so soft-skip to `{}`
-        // and log it (like the parse-failure branch) rather than discard the file
-        // silently.
+        // Parsed cleanly but not an object shape — treat as corrupt: soft-skip + log.
         if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
             this.logBus?.warn('skipping non-object Mastra session-context file', { file });
             return {};
@@ -122,10 +142,13 @@ export class SessionContextStore {
         return parsed;
     }
     async writeContext(agentId, threadId, content) {
+        // Serialize (canonicalize + size-guard) before touching disk, so a bad
+        // object leaves no partial write behind.
+        const serialized = serializeSessionContext(content);
         const file = this.fileFor(agentId, threadId);
         await mkdir(dirname(file), { recursive: true });
         const tmp = `${file}.tmp`;
-        await writeFile(tmp, JSON.stringify(content), 'utf8');
+        await writeFile(tmp, serialized, 'utf8');
         await rename(tmp, file);
     }
     async deleteContext(agentId, threadId) {
@@ -140,12 +163,8 @@ export class SessionContextStore {
         return join(this.dirFor(agentId), `${encodeSegment(threadId)}${FILE_EXT}`);
     }
     /**
-     * Per-`(agentId, threadId)` in-flight queue. Ported from the OpenAI
-     * harness's `SessionContextStore.serialize` — serializes read-mutate-write
-     * cycles on the same thread so a concurrent `setSessionContext` and
-     * `getSessionContext` never interleave a read against a half-written file.
-     * Keyed by the SAME injective encoding as {@link fileFor}, so two ids that
-     * only differ in punctuation get distinct queues (not one shared queue).
+     * Per-`(agentId, threadId)` in-flight queue so read/write cycles on one thread
+     * never interleave. Keyed by the same injective encoding as {@link fileFor}.
      */
     serialize(agentId, threadId, fn) {
         const k = `${encodeSegment(agentId)} ${encodeSegment(threadId)}`;
@@ -160,22 +179,12 @@ export class SessionContextStore {
     }
 }
 /**
- * Encode an agent/thread id into a single safe path segment via base64url.
- *
- * Injective over well-formed strings — distinct ids map to distinct segments —
- * for two reasons a lossy `[^A-Za-z0-9._-] → _` collapse got wrong: (1) it
- * aliased distinct threads (`a/b` and `a?b` both became `a_b`), so one chat
- * could read/overwrite another's session context and share its serialize-queue
- * key; (2) it passed `.` / `..` through untouched, so a threadId of `..` escaped
- * the `session-context/` dir. base64url's alphabet is `[A-Za-z0-9_-]` — no `.`
- * and no `/` — so an encoded segment can never be `..` or contain a separator.
- *
- * **Caveat — not injective over lone (unpaired) UTF-16 surrogates.** The `utf8`
- * transcode replaces an unpaired surrogate with U+FFFD before encoding, so e.g.
- * `"\uD800"` and `"\uD801"` collide. A non-issue in practice (agent/thread ids
- * are UUIDs / gateway-issued ids, always well-formed); closing it would mean an
- * encoding change that re-orphans every existing sidecar. Documented, not
- * silently absolute. Byte-identical to the Claude / OpenAI harness copies.
+ * Encode an agent/thread id into one safe path segment via base64url. Injective
+ * (distinct ids → distinct segments) and traversal-safe: the `[A-Za-z0-9_-]`
+ * alphabet has no `.` or `/`, so a segment can never be `..` or contain a
+ * separator, and punctuation-only-distinct ids (`a/b` vs `a?b`) never alias.
+ * Caveat: lone UTF-16 surrogates transcode to U+FFFD and collide — a non-issue
+ * for UUID / gateway-issued ids.
  */
 function encodeSegment(s) {
     return Buffer.from(s, 'utf8').toString('base64url');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.53.0",
+  "version": "0.54.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.54.0"
+    "@salesforce/sfdx-agent-sdk": "0.55.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.54.0",
+    "@salesforce/sfdx-agent-sdk": "0.55.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",