@salesforce/sfdx-agent-harness-claude 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to `@salesforce/sfdx-agent-harness-claude` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.46.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.45.0] - 2026-08-14
 
 _No changes — released alongside dependent packages._

package/dist/claude-harness.d.ts

@@ -1,5 +1,5 @@
 import { type Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
-import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, 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, type WithAgentConfig } from '@salesforce/sfdx-agent-sdk/harness';
 import type { ClaudeAgentConfig } from './claude-config.js';
 import type { ClaudeQueryEnvBuilder } from './claude-query-env-builder.js';
@@ -222,16 +222,36 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      */
     cloneThread(agentId: string, sourceThreadId: string): Promise<string>;
     /**
-     * Write the sidecar for a thread so its `contextHistory`,
-     * `pendingContext`, AND `claudeSessionId` survive across restart.
+     * Allocate and register a fresh `ThreadState` for `threadId`, mirroring
+     * `createThread`'s initial shape (legacy 1:1 `claudeSessionId === threadId`,
+     * empty context arrays, `sessionContext` absent). Used by `setSessionContext`
+     * to seed a thread the consumer references before `createThread` / the first
+     * `stream()` — the session-context contract allows seeding context on an
+     * as-yet-unregistered thread.
+     */
+    private allocateThreadState;
+    /**
+     * Project a `ThreadState` into the on-disk `ThreadContextRecord`. Every
+     * sidecar write goes through this one builder so all persisted channels —
+     * addContext arrays, the `claudeSessionId` mapping, AND `sessionContext` —
+     * travel together and no write site can silently drop one. `sessionContext`
+     * is included only when set, so a thread that never set it writes no field
+     * (and reads back `{}`).
+     */
+    private threadContextRecordFrom;
+    /**
+     * Write the sidecar for a thread so its `contextHistory`, `pendingContext`,
+     * `claudeSessionId`, AND `sessionContext` survive across restart.
      *
-     * The early-return optimization for "nothing to persist" only fires
-     * when ALL three pieces of state match the legacy default
-     * (no addContext history AND `claudeSessionId === threadId`). The
-     * `claudeSessionId` check matters post-#511: a thread that has had
-     * its sessionId reassigned by `clearMessages()` MUST write a sidecar
-     * so the next `createAgent` rehydrates with the divergent mapping
-     * even when the thread otherwise has no addContext data.
+     * The early-return optimization for "nothing to persist" only fires when
+     * EVERY channel matches the legacy default: no addContext history, an
+     * un-rotated `claudeSessionId` (`=== threadId`), and no session context set.
+     * The `claudeSessionId` check matters post-#511 (a thread whose sessionId
+     * was rotated by `clearMessages()` MUST write a sidecar even with no
+     * addContext data); the `sessionContext` check matters symmetrically — a
+     * thread carrying only session context MUST persist it. `setSessionContext`
+     * itself writes unconditionally rather than through this helper, so this
+     * guard is for the incidental persist sites (stream-consume, clone).
      */
     private persistThreadContextIfPresent;
     /**
@@ -384,7 +404,11 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
     getMessages(agentId: string, threadId: string): Promise<Message[]>;
     clearMessages(agentId: string, threadId: string): Promise<void>;
     private buildContextPrompt;
+    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>;
+    setSessionContext(agentId: string, threadId: string, content: SessionContext): Promise<void>;
+    getSessionContext(agentId: string, threadId: string): Promise<SessionContext>;
     /**
      * Synchronously flips `serverState.currentStatus` (no-op when the next
      * status equals the current) and returns a closure that, when invoked,

package/dist/claude-harness.js

@@ -48,6 +48,24 @@ function extractSystemPromptBody(systemPrompt) {
     }
     return undefined;
 }
+/**
+ * Deep-copy a `SessionContext` at the harness's public boundary so the consumer
+ * and the in-memory `ThreadState.sessionContext` never share a reference — a
+ * caller mutating either the object it passed to `setSessionContext` or the one
+ * `getSessionContext` returns must not reach into harness-internal state (which
+ * would silently diverge from what is persisted to disk until the next write).
+ * A JSON round-trip is the right copy here: `SessionContext` is a `JsonValue`
+ * object by contract (no functions / `Date` / class instances), so the round-trip
+ * is lossless AND it normalizes the object to the exact shape a post-restart read
+ * off disk would produce — so `getSessionContext` returns an identical value
+ * whether or not a restart intervened. Caveat: `JSON.stringify` drops keys whose
+ * value is `undefined`; type-safe here because `JsonValue` excludes `undefined`,
+ * but an `any`-typed caller that smuggles one in would see that key silently
+ * dropped rather than preserved as `undefined`.
+ */
+function cloneSessionContext(content) {
+    return JSON.parse(JSON.stringify(content));
+}
 export class ClaudeHarness {
     envBuilder;
     optionsBuilder;
@@ -319,6 +337,11 @@ export class ClaudeHarness {
                 claudeSessionId,
                 pendingContext: ctx.pendingContext,
                 contextHistory: ctx.contextHistory,
+                // Rehydrate the session-context channel so a set survives
+                // restart. Absent on the record (never set, or a pre-session-
+                // context sidecar) leaves `ThreadState.sessionContext`
+                // undefined → `getSessionContext` reads back `{}`.
+                ...(ctx.sessionContext !== undefined ? { sessionContext: ctx.sessionContext } : {}),
             });
             consumedSessionIds.add(claudeSessionId);
         }
@@ -415,6 +438,13 @@ export class ClaudeHarness {
             await closeClientWithTimeout(s.client);
             await s.ready.catch(() => undefined);
         }));
+        // Session context now shares the `ThreadContextStore` sidecar with the
+        // addContext channel (the spike's "extend the existing sidecar" for
+        // Claude), so it inherits that channel's lifecycle: sidecars are cleaned
+        // per-thread by `destroyThread`, NOT wiped en masse here. `destroyAgent`
+        // already leaves addContext sidecars on disk so a recreate over the same
+        // `projectRoot` rehydrates the threads (#455); session context rides the
+        // same durability. There is deliberately no agent-level sidecar wipe.
         return this.agents.delete(agentId);
     }
     async getAgentIds() {
@@ -642,6 +672,17 @@ export class ClaudeHarness {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
         }
         const id = threadId ?? this.idGenerator.getUniqueId();
+        // A thread id may already carry state if the consumer seeded session
+        // context before creating the thread — `setSessionContext` lazily
+        // allocates a `ThreadState` for an unregistered id (the contract allows
+        // seeding pre-`createThread`). Carry that `sessionContext` forward so a
+        // later `createThread` on the same id does not silently drop the last
+        // object the consumer set — `getSessionContext` MUST still return it
+        // (and its persisted sidecar copy stays consistent with memory). The
+        // message channels DO reset here: `createThread` semantically starts a
+        // fresh conversation, and session context is the one out-of-history
+        // piece that outlives that reset.
+        const existingSessionContext = agent.threads.get(id)?.sessionContext;
         // claudeSessionId starts equal to threadId — only diverges after a
         // `clearMessages()` cycle (see issue #511 / ThreadState docstring).
         agent.threads.set(id, {
@@ -649,6 +690,7 @@ export class ClaudeHarness {
             claudeSessionId: id,
             pendingContext: [],
             contextHistory: [],
+            ...(existingSessionContext !== undefined ? { sessionContext: existingSessionContext } : {}),
         });
         return id;
     }
@@ -669,10 +711,11 @@ export class ClaudeHarness {
                 sessionStore: this.sessionStore,
             });
         }
-        // Delete the addContext sidecar regardless of `hasStreamed` — a
-        // thread can have addContext-injected turns without ever being
-        // streamed, and leaving the sidecar would resurrect them on the
-        // next createAgent rehydrate pass.
+        // Delete the sidecar regardless of `hasStreamed` — a thread can have
+        // addContext-injected turns OR setSessionContext state without ever
+        // being streamed, and leaving the sidecar would resurrect either on the
+        // next createAgent rehydrate pass (or if the thread id is recreated).
+        // Both channels share this one sidecar, so a single delete covers them.
         await this.threadContextStore.delete(agent.projectRoot, threadId);
         agent.threads.delete(threadId);
     }
@@ -707,6 +750,12 @@ export class ClaudeHarness {
         if (!sourceState) {
             throw new Error(`Thread "${sourceThreadId}" not found`);
         }
+        // Both branches below build the clone's `ThreadState` inline rather than
+        // through `threadContextRecordFrom`, and deliberately do NOT copy
+        // `sourceState.sessionContext`: session-context carry-forward is deferred
+        // to this harness's render PR (W-23632691). When it lands, copy
+        // `sessionContext` here too. Until then a clone starts with empty session
+        // context by design, not by omission.
         if (!sourceState.hasStreamed) {
             const newId = this.idGenerator.getUniqueId();
             agent.threads.set(newId, {
@@ -739,27 +788,60 @@ export class ClaudeHarness {
         return result.sessionId;
     }
     /**
-     * Write the sidecar for a thread so its `contextHistory`,
-     * `pendingContext`, AND `claudeSessionId` survive across restart.
+     * Allocate and register a fresh `ThreadState` for `threadId`, mirroring
+     * `createThread`'s initial shape (legacy 1:1 `claudeSessionId === threadId`,
+     * empty context arrays, `sessionContext` absent). Used by `setSessionContext`
+     * to seed a thread the consumer references before `createThread` / the first
+     * `stream()` — the session-context contract allows seeding context on an
+     * as-yet-unregistered thread.
+     */
+    allocateThreadState(agent, threadId) {
+        const state = {
+            hasStreamed: false,
+            claudeSessionId: threadId,
+            pendingContext: [],
+            contextHistory: [],
+        };
+        agent.threads.set(threadId, state);
+        return state;
+    }
+    /**
+     * Project a `ThreadState` into the on-disk `ThreadContextRecord`. Every
+     * sidecar write goes through this one builder so all persisted channels —
+     * addContext arrays, the `claudeSessionId` mapping, AND `sessionContext` —
+     * travel together and no write site can silently drop one. `sessionContext`
+     * is included only when set, so a thread that never set it writes no field
+     * (and reads back `{}`).
+     */
+    threadContextRecordFrom(source) {
+        return {
+            contextHistory: source.contextHistory,
+            pendingContext: source.pendingContext,
+            claudeSessionId: source.claudeSessionId,
+            ...(source.sessionContext !== undefined ? { sessionContext: source.sessionContext } : {}),
+        };
+    }
+    /**
+     * Write the sidecar for a thread so its `contextHistory`, `pendingContext`,
+     * `claudeSessionId`, AND `sessionContext` survive across restart.
      *
-     * The early-return optimization for "nothing to persist" only fires
-     * when ALL three pieces of state match the legacy default
-     * (no addContext history AND `claudeSessionId === threadId`). The
-     * `claudeSessionId` check matters post-#511: a thread that has had
-     * its sessionId reassigned by `clearMessages()` MUST write a sidecar
-     * so the next `createAgent` rehydrates with the divergent mapping
-     * even when the thread otherwise has no addContext data.
+     * The early-return optimization for "nothing to persist" only fires when
+     * EVERY channel matches the legacy default: no addContext history, an
+     * un-rotated `claudeSessionId` (`=== threadId`), and no session context set.
+     * The `claudeSessionId` check matters post-#511 (a thread whose sessionId
+     * was rotated by `clearMessages()` MUST write a sidecar even with no
+     * addContext data); the `sessionContext` check matters symmetrically — a
+     * thread carrying only session context MUST persist it. `setSessionContext`
+     * itself writes unconditionally rather than through this helper, so this
+     * guard is for the incidental persist sites (stream-consume, clone).
      */
     async persistThreadContextIfPresent(projectRoot, threadId, source) {
         const hasContext = source.contextHistory.length > 0 || source.pendingContext.length > 0;
         const hasDivergedSessionId = source.claudeSessionId !== threadId;
-        if (!hasContext && !hasDivergedSessionId)
+        const hasSessionContext = source.sessionContext !== undefined;
+        if (!hasContext && !hasDivergedSessionId && !hasSessionContext)
             return;
-        await this.threadContextStore.write(projectRoot, threadId, {
-            contextHistory: source.contextHistory,
-            pendingContext: source.pendingContext,
-            claudeSessionId: source.claudeSessionId,
-        });
+        await this.threadContextStore.write(projectRoot, threadId, this.threadContextRecordFrom(source));
     }
     /**
      * Compacts a thread into a new thread seeded with an LLM-generated summary
@@ -815,7 +897,7 @@ export class ClaudeHarness {
         const 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',
@@ -1261,12 +1343,11 @@ export class ClaudeHarness {
             // systemPrompt. contextHistory persists unchanged and verbatim —
             // structured MessagePart[] content (incl. image/file base64) is
             // preserved so the getMessages() round-trip stays lossless across a
-            // restart, matching Mastra's persist-verbatim behavior.
-            await this.threadContextStore.write(projectRoot, threadId, {
-                pendingContext: [],
-                contextHistory: threadState.contextHistory,
-                claudeSessionId: threadState.claudeSessionId,
-            });
+            // restart, matching Mastra's persist-verbatim behavior. Routed
+            // through `threadContextRecordFrom` (reading the just-cleared
+            // in-memory `pendingContext`) so any `sessionContext` on the thread
+            // survives the clear.
+            await this.threadContextStore.write(projectRoot, threadId, this.threadContextRecordFrom(threadState));
         }
         // Wire-communication monitoring on Claude (subscriber-gated): the Claude Agent SDK runs
         // the model client in a subprocess with no programmatic HTTP-interception seam, so we
@@ -1445,7 +1526,14 @@ export class ClaudeHarness {
         // the contract's ascending-by-createdAt post-condition under stable
         // sort, so step the fallback per-position via `clock.nextAfter`.
         let lastFallback = this.clock.now();
-        const persisted = sessionMessages.map((msg) => {
+        const persisted = sessionMessages.flatMap((msg) => {
+            // The SDK's `MessageRole` is `'user' | 'assistant' | 'tool'` — `'system'`
+            // is not a consumer-visible transcript role (system state rides
+            // `instructions` / session context). The Anthropic transcript never
+            // stores a bare `system` turn on this path, but drop it defensively
+            // rather than surface an off-contract role across the SDK boundary.
+            if (msg.type !== 'user' && msg.type !== 'assistant')
+                return [];
             const recorded = timestamps.get(msg.uuid);
             let createdAt;
             if (recorded) {
@@ -1455,12 +1543,14 @@ export class ClaudeHarness {
                 lastFallback = this.clock.nextAfter(lastFallback);
                 createdAt = lastFallback;
             }
-            return {
-                id: msg.uuid,
-                role: msg.type,
-                content: mapSessionMessageContent(msg.message),
-                createdAt,
-            };
+            return [
+                {
+                    id: msg.uuid,
+                    role: msg.type,
+                    content: mapSessionMessageContent(msg.message),
+                    createdAt,
+                },
+            ];
         });
         // Merge the addContext-injected mirror with the persisted transcript
         // and sort chronologically (#464). The Claude SDK has no public API
@@ -1542,7 +1632,7 @@ export class ClaudeHarness {
         const prefix = baseInstructions ? `${baseInstructions}\n\n` : '';
         return `${prefix}<prior-context>\n${contextBlock}\n</prior-context>`;
     }
-    async addContext(agentId, threadId, messages) {
+    async addMessages(agentId, threadId, messages) {
         const agent = this.agents.get(agentId);
         if (!agent) {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
@@ -1578,12 +1668,59 @@ export class ClaudeHarness {
         // restart — matching Mastra's persist-verbatim (LibSQL) behavior. The
         // earlier placeholder-flattening (#491) was a premature optimization that
         // silently destroyed structured tool parts on rehydrate and diverged from
-        // Mastra; removed in favor of cross-harness correctness.
-        await this.threadContextStore.write(agent.projectRoot, threadId, {
-            pendingContext: threadState.pendingContext,
-            contextHistory: threadState.contextHistory,
-            claudeSessionId: threadState.claudeSessionId,
-        });
+        // Mastra; removed in favor of cross-harness correctness. Routed through
+        // `threadContextRecordFrom` so any `sessionContext` on the thread is
+        // carried in the same write and never clobbered by this addContext path.
+        await this.threadContextStore.write(agent.projectRoot, threadId, this.threadContextRecordFrom(threadState));
+    }
+    /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
+    async addContext(agentId, threadId, messages) {
+        await this.addMessages(agentId, threadId, messages);
+    }
+    async setSessionContext(agentId, threadId, content) {
+        // AGENT_NOT_FOUND guard runs before any state touch — matches the
+        // cross-harness contract (#464) that every agent-scoped method throws
+        // on an unknown id. threadId is NOT validated: session context is a
+        // per-thread channel the consumer can seed before a thread's first
+        // stream (or before `createThread`), so an arbitrary threadId is a
+        // legal write target — a `ThreadState` is allocated lazily for it,
+        // mirroring `createThread`'s initial shape (`claudeSessionId ===
+        // threadId`, empty context arrays), and only its `sessionContext`
+        // field is set. An existing thread keeps all its other state.
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
+        const threadState = agent.threads.get(threadId) ?? this.allocateThreadState(agent, threadId);
+        // Update the in-memory source of truth first, then persist — mirrors
+        // `addMessages`, which mutates the arrays before writing the sidecar.
+        // Store a DEEP COPY, not the caller's reference: the consumer keeps
+        // ownership of the object it passed, so a later mutation of it must not
+        // reach into harness-internal state (and diverge from what was written
+        // to disk). The deleted `SessionContextStore` got this for free by
+        // JSON-serializing to disk on every write; `cloneSessionContext`
+        // preserves that isolation now that the object is held in memory.
+        threadState.sessionContext = cloneSessionContext(content);
+        // Unconditional write (not `persistThreadContextIfPresent`): an explicit
+        // set MUST be durable even when the thread has no addContext history and
+        // an un-rotated `claudeSessionId`.
+        await this.threadContextStore.write(agent.projectRoot, threadId, this.threadContextRecordFrom(threadState));
+    }
+    async getSessionContext(agentId, threadId) {
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
+        // In-memory `ThreadState` is the source of truth (rehydrated from the
+        // sidecar at `createAgent`, same as `contextHistory` / `pendingContext`).
+        // `{}`-on-miss — never `null`/`undefined`, never throws — for a thread
+        // that was never registered or never had context set. Return a DEEP COPY
+        // so a caller mutating the result can't reach into harness-internal state
+        // (which would silently diverge from disk until the next persist); this
+        // matches the fresh-object-per-read the deleted `SessionContextStore`
+        // gave via its `JSON.parse` read path.
+        const current = agent.threads.get(threadId)?.sessionContext;
+        return current === undefined ? {} : cloneSessionContext(current);
     }
     /**
      * Synchronously flips `serverState.currentStatus` (no-op when the next