@salesforce/sfdx-agent-harness-mastra 0.48.0 → 0.49.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.49.0] - 2026-08-17
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: session-context contract + conformance gate @W-23632685@ ([#747](https://github.com/forcedotcom/agentic-dx/pull/747))
+
 ## [0.48.0] - 2026-08-14
 
 _No changes — released alongside dependent packages._

package/dist/mastra-harness.d.ts

@@ -1,7 +1,7 @@
 import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { MCPClient } from '@mastra/mcp';
-import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import type { MastraLanguageModelBuilderContext } from './index.js';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
@@ -248,6 +248,22 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly memory;
     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.
+     */
+    private readonly sessionContext;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -529,7 +545,24 @@ export declare class MastraHarness implements MastraAgentHarness {
      * - MUST throw an error if the specified `agentId` is not found.
      * - MUST save context messages without triggering an LLM response.
      */
+    addMessages(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    /** @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.
+     */
+    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.
+     */
+    getSessionContext(agentId: string, threadId: string): Promise<SessionContext>;
     /**
      * 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,6 +15,7 @@ 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';
@@ -366,6 +367,22 @@ export class MastraHarness {
     memory;
     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.
+     */
+    sessionContext;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -426,6 +443,7 @@ export class MastraHarness {
             storage: this.storage,
             memory: { shared: this.memory },
         });
+        this.sessionContext = new SessionContextStore(this.storageRootFolder, this.buses.getLogBus());
     }
     /**
      * @requirements
@@ -719,6 +737,10 @@ 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);
         this.mastra.removeAgent(agentId);
         this.modelConnectivityByAgent.delete(agentId);
         return this.activeAgents.delete(agentId);
@@ -1172,6 +1194,10 @@ 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);
     }
     /**
      * @requirements
@@ -1243,7 +1269,7 @@ export class MastraHarness {
             newThreadId = await this.createThread(agentId);
             const userTs = this.clock.now();
             const assistantTs = this.clock.nextAfter(userTs);
-            await this.addContext(agentId, newThreadId, [
+            await this.addMessages(agentId, newThreadId, [
                 {
                     id: this.idGenerator.getUniqueId(),
                     role: 'user',
@@ -1598,11 +1624,16 @@ export class MastraHarness {
             perPage: false,
         });
         const logBus = this.buses.getLogBus();
-        // Drop Mastra's experimental `'signal'` role (system reminders the agent synthesizes via `createSignal()`,
-        // see `@mastra/core/dist/agent/signals.d.ts` — all `@experimental`). The SDK's `MessageRole` exposes only
-        // `'system' | 'user' | 'assistant' | 'tool'` and surfacing experimental upstream concepts would leak the
-        // harness internals up to consumers. If Mastra promotes signals to stable and we want them, the SDK
-        // contract needs to add the role first.
+        // Drop roles with no consumer-visible SDK equivalent before mapping:
+        //  - `'signal'` — Mastra's experimental self-synthesized system reminders
+        //    (`createSignal()`, see `@mastra/core/dist/agent/signals.d.ts`, all
+        //    `@experimental`); surfacing them would leak harness internals up.
+        //  - `'system'` — not a member of the SDK's `MessageRole` (`'user' |
+        //    'assistant' | 'tool'`). System state rides `instructions` / session
+        //    context, never the transcript, so a persisted `system` row (if one
+        //    ever exists) must not surface on `getMessages`.
+        // If Mastra promotes signals to stable and we want them, the SDK contract
+        // needs to add the role first.
         // Per-position fallback for any persisted row whose `createdAt` is
         // null/undefined (legacy rows from before the optional-on-write
         // contract, partial-write recovery, or a libsql schema change).
@@ -1613,7 +1644,9 @@ export class MastraHarness {
         // silently bucket null-timestamp rows at epoch and propagate
         // `undefined` to consumers.
         let lastFallback = this.clock.now();
-        const mapped = messages.filter((m) => m.role !== 'signal').map((m) => mapMastraToMessage(m, logBus));
+        const mapped = messages
+            .filter((m) => m.role !== 'signal' && m.role !== 'system')
+            .map((m) => mapMastraToMessage(m, logBus));
         // Hoist every completed tool call's `tool-result` part onto its own
         // `role: 'tool'` message so the consumer-visible layout matches the
         // cross-harness `getMessages` contract (assistant carries the
@@ -1652,7 +1685,7 @@ export class MastraHarness {
      * - MUST throw an error if the specified `agentId` is not found.
      * - MUST save context messages without triggering an LLM response.
      */
-    async addContext(agentId, threadId, messages) {
+    async addMessages(agentId, threadId, messages) {
         const memory = await this.getMemoryOrThrow(agentId);
         const resourceId = this.agentResourceId(agentId);
         // Backfill `createdAt` on any caller-supplied message that omits it.
@@ -1674,6 +1707,31 @@ export class MastraHarness {
         const mapped = filled.map((m) => mapMessageToMastra(m, threadId, resourceId));
         await memory.saveMessages({ messages: mapped });
     }
+    /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
+    async addContext(agentId, threadId, messages) {
+        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.
+     */
+    async setSessionContext(agentId, threadId, content) {
+        this.getAgentStateOrThrow(agentId);
+        await this.sessionContext.write(agentId, threadId, content);
+    }
+    /**
+     * 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.
+     */
+    async getSessionContext(agentId, threadId) {
+        this.getAgentStateOrThrow(agentId);
+        return this.sessionContext.read(agentId, threadId);
+    }
     // ── Private Helpers ──────────────────────────────────────────────
     /**
      * Issue a single non-agentic model call (`maxSteps: 1`) for one-shot

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

@@ -4,8 +4,10 @@ import type { LogBus } from '@salesforce/agentic-common';
 /**
  * Converts a Mastra persisted message into the SDK's {@link Message} type.
  *
- * Callers must filter out Mastra's experimental `'signal'` role before invoking;
- * those messages have no SDK equivalent and must not surface in `Message[]`.
+ * Callers must filter out roles with no SDK `Message` equivalent before invoking:
+ * Mastra's experimental `'signal'` role and `'system'` (which is not a
+ * consumer-visible SDK {@link MessageRole} — system state rides `instructions` /
+ * session context, never the transcript). Neither must surface in `Message[]`.
  *
  * Parts that have no SDK equivalent (source, file, step-start, and any
  * unrecognized upstream types including AI SDK v5 `data-*` metadata parts)

package/dist/mastra-message-mapper.js

@@ -59,8 +59,10 @@ function buildCompletedToolInvocation(toolCallId, toolName, args, result) {
 /**
  * Converts a Mastra persisted message into the SDK's {@link Message} type.
  *
- * Callers must filter out Mastra's experimental `'signal'` role before invoking;
- * those messages have no SDK equivalent and must not surface in `Message[]`.
+ * Callers must filter out roles with no SDK `Message` equivalent before invoking:
+ * Mastra's experimental `'signal'` role and `'system'` (which is not a
+ * consumer-visible SDK {@link MessageRole} — system state rides `instructions` /
+ * session context, never the transcript). Neither must surface in `Message[]`.
  *
  * Parts that have no SDK equivalent (source, file, step-start, and any
  * unrecognized upstream types including AI SDK v5 `data-*` metadata parts)
@@ -69,8 +71,8 @@ function buildCompletedToolInvocation(toolCallId, toolName, args, result) {
  * message history retrieval.
  */
 export function mapMastraToMessage(msg, logBus) {
-    if (msg.role === 'signal') {
-        throw new Error("mapMastraToMessage: 'signal' role messages must be filtered out before mapping");
+    if (msg.role === 'signal' || msg.role === 'system') {
+        throw new Error(`mapMastraToMessage: '${msg.role}' role messages must be filtered out before mapping`);
     }
     const parts = [];
     for (const part of msg.content.parts) {

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

@@ -0,0 +1,87 @@
+import { type LogBus } from '@salesforce/agentic-common';
+import 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.
+ */
+export declare class SessionContextStore {
+    private readonly storageRootFolder;
+    private readonly logBus;
+    private readonly inflight;
+    constructor(storageRootFolder: string, logBus: LogBus | undefined);
+    /**
+     * This thread's persisted session-context object, or `{}` when nothing has
+     * been set (missing file) or the file is unparseable. Never `null`/`undefined`,
+     * never throws on a miss.
+     */
+    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.
+     */
+    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.
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    private readContext;
+    private writeContext;
+    private deleteContext;
+    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).
+     */
+    private serialize;
+}

package/dist/session-context-store.js

@@ -0,0 +1,183 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getErrorMessage } from '@salesforce/agentic-common';
+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.
+ */
+export class SessionContextStore {
+    storageRootFolder;
+    logBus;
+    inflight = new Map();
+    constructor(storageRootFolder, logBus) {
+        this.storageRootFolder = storageRootFolder;
+        this.logBus = logBus;
+    }
+    /**
+     * This thread's persisted session-context object, or `{}` when nothing has
+     * been set (missing file) or the file is unparseable. Never `null`/`undefined`,
+     * never throws on a miss.
+     */
+    async read(agentId, threadId) {
+        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.
+     */
+    async write(agentId, threadId, content) {
+        await this.serialize(agentId, threadId, () => 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.
+     */
+    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.
+     */
+    async deleteAgent(agentId) {
+        await rm(this.dirFor(agentId), { recursive: true, force: true });
+    }
+    // ── Internals (called only inside `serialize`) ───────────────────────────
+    async readContext(agentId, threadId) {
+        const file = this.fileFor(agentId, threadId);
+        let raw;
+        try {
+            raw = await readFile(file, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return {};
+            throw err;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            this.logBus?.warn('skipping unparseable Mastra session-context file', {
+                file,
+                error: getErrorMessage(err),
+            });
+            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.
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            this.logBus?.warn('skipping non-object Mastra session-context file', { file });
+            return {};
+        }
+        return parsed;
+    }
+    async writeContext(agentId, threadId, 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 rename(tmp, file);
+    }
+    async deleteContext(agentId, threadId) {
+        // `force: true` makes a missing file a no-op (no ENOENT throw) — deleting
+        // a thread that never had session context set is not an error.
+        await rm(this.fileFor(agentId, threadId), { force: true });
+    }
+    dirFor(agentId) {
+        return join(this.storageRootFolder, SESSION_CONTEXT_SUBDIR, encodeSegment(agentId));
+    }
+    fileFor(agentId, threadId) {
+        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).
+     */
+    serialize(agentId, threadId, fn) {
+        const k = `${encodeSegment(agentId)} ${encodeSegment(threadId)}`;
+        const previous = this.inflight.get(k) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(fn);
+        this.inflight.set(k, next);
+        next.finally(() => {
+            if (this.inflight.get(k) === next)
+                this.inflight.delete(k);
+        }).catch(() => undefined);
+        return next;
+    }
+}
+/**
+ * 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.
+ */
+function encodeSegment(s) {
+    return Buffer.from(s, 'utf8').toString('base64url');
+}
+//# sourceMappingURL=session-context-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.48.0",
+  "version": "0.49.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.49.0"
+    "@salesforce/sfdx-agent-sdk": "0.50.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.49.0",
+    "@salesforce/sfdx-agent-sdk": "0.50.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.26",