@salesforce/sfdx-agent-sdk 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.50.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.49.0] - 2026-08-14
+
+### Fixes
+- **agent-sdk**: export ACCEPTED_MODEL_WIRE_IDS for wire-boundary modelId validation @W-23694670@ ([#752](https://github.com/forcedotcom/agentic-dx/pull/752))
+
 ## [0.48.0] - 2026-08-10
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -159,22 +159,25 @@ keeps unparameterized call sites working.
 
 A single conversation thread.
 
-| Method              | Signature                                                                 | Description                                                                                                                                                                                     |
-| ------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                                                                                      |
-| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.                                                                             |
-| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream.                                                                      |
-| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. `{ remember: true }` ("Allow always") appends an `allow` rule to `AgentConfig.toolPolicies` and persists it before settling. Control message on the existing turn. |
-| `declineToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Decline a pending tool call. `{ remember: true }` ("Deny always") appends a `deny` rule and persists it before settling. Control message on the existing turn.                                  |
-| `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                                                                                                   |
-| `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                                                                                            |
-| `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                                                                                                   |
-| `addContext`        | `(message: string \| Message[]) => Promise<void>`                         | Inject context without triggering an LLM response.                                                                                                                                              |
-| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                          | Register a real-time event listener.                                                                                                                                                            |
-| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                          | Remove a listener.                                                                                                                                                                              |
-| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                       | Subscribe to telemetry scoped to this session.                                                                                                                                                  |
-| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                  | Subscribe to logs scoped to this session.                                                                                                                                                       |
-| `dispose`           | `() => void`                                                              | Release session-level event resources. Idempotent.                                                                                                                                              |
+| Method              | Signature                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. `{ remember: true }` ("Allow always") appends an `allow` rule to `AgentConfig.toolPolicies` and persists it before settling. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `declineToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Decline a pending tool call. `{ remember: true }` ("Deny always") appends a `deny` rule and persists it before settling. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `addMessages`       | `(message: string \| Message[]) => Promise<void>`                         | Append real transcript messages (`user` / `assistant` / `tool`) to the thread **without requesting an agent response** — the write-only half of a turn. The messages persist, appear in `getMessageHistory()`, and replay to the model as prior conversation on the next `chat()`. Use it to seed earlier turns (e.g. file contents as a user message) before the first live prompt; the SDK equivalent of the service's `POST /messages` with `noReply=true`. **Not** `setSessionContext`: this writes _transcript history_ (visible in `getMessageHistory`, additive); `setSessionContext` writes an _out-of-history overlay object_ (never in history, whole-object replace). `'system'` is not a valid role here — system-level state rides `setSessionContext` / `AgentConfig.instructions`. |
+| `addContext`        | `(message: string \| Message[]) => Promise<void>`                         | **Deprecated** — renamed to `addMessages` (identical signature/behavior); delegates to it. The old name read as a sibling of `setSessionContext`, but the two are distinct channels. Will be removed in a future release; migrate to `addMessages`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `setSessionContext` | `(content: SessionContext) => Promise<void>`                              | Replace this session's session-context object in full (whole-object set, not a merge). Persisted per-thread and durable across restart; kept out of message history, so it never appears in `getMessageHistory()`. **Currently persistence-only** — the stored object is not yet rendered into the model's system-level context; per-harness rendering on subsequent turns lands in a follow-up. Delegates to `AgentHarness.setSessionContext` — see that method's JSDoc for the full delivery/durability/isolation contract.                                                                                                                                                                                                                                                                     |
+| `getSessionContext` | `() => Promise<SessionContext>`                                           | Read this session's current session-context object. Returns `{}` (an empty object) — never `null` or `undefined` — when nothing has been set on this thread yet, so callers never need a null-check. Unrelated to `getContextUsage()`, which reports context-window token occupancy, not the seeded context object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                          | Register a real-time event listener.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                          | Remove a listener.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                       | Subscribe to telemetry scoped to this session.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                  | Subscribe to logs scoped to this session.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `dispose`           | `() => void`                                                              | Release session-level event resources. Idempotent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ### `ChatStreamResult`
 
@@ -505,9 +508,15 @@ type ToolResultInfo = {
 ### Message Types
 
 ```typescript
+// The message role, exported as a named type. `'system'` is not a member:
+// system-level state rides `AgentConfig.instructions` and `setSessionContext`,
+// never the transcript, so `getMessages` never returns a `system` message and
+// one cannot be seeded via `addMessages` / `POST /messages`.
+type MessageRole = 'user' | 'assistant' | 'tool';
+
 type Message = {
   id: string;
-  role: 'system' | 'user' | 'assistant' | 'tool';
+  role: MessageRole;
   content: string | MessagePart[];
   createdAt?: Date;
 };
@@ -520,7 +529,7 @@ type ReasoningPart = { type: 'reasoning'; text: string };
 
 // Tool invocation / result segments persisted on `Message.content`. Extend the
 // `ToolCallInfo` / `ToolResultInfo` shapes with a discriminator. They appear in
-// message history; they are NOT valid input on `chat()` / `addContext()`.
+// message history; they are NOT valid input on `chat()` / `addMessages()`.
 type ToolCallPart = ToolCallInfo & { type: 'tool-call' };
 type ToolResultPart = ToolResultInfo & { type: 'tool-result' };
 
@@ -533,9 +542,28 @@ type FilePart = { type: 'file'; mimeType: 'application/pdf'; data: string; fileN
 
 - Messages returned from `ChatSession.getMessageHistory()` always have `createdAt` populated, and the array is sorted
   ascending by `createdAt`. Consumer code can read `msg.createdAt` directly.
-- Consumers constructing `Message` literals for `ChatSession.addContext()` may omit `createdAt`; the SDK backfills the
+- Consumers constructing `Message` literals for `ChatSession.addMessages()` may omit `createdAt`; the SDK backfills the
   current time before forwarding to the harness. Pass an explicit value to override.
 
+### Session Context Types
+
+The per-chat session-context channel (`ChatSession.setSessionContext` / `getSessionContext`, documented in the
+`ChatSession` method table above) carries a JSON-serializable object, exported as two named types:
+
+```typescript
+// A JSON value: the transitive closure of what survives a JSON round-trip.
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+// The session-context object: a bare JSON object at the root (no envelope).
+type SessionContext = { [key: string]: JsonValue };
+```
+
+`setSessionContext` persists the object verbatim (so a nested / array / null-bearing object round-trips unchanged) and
+`getSessionContext` returns `{}` — never `null` / `undefined` — when nothing was set. The channel is disjoint from
+message history: a set object never appears in `getMessageHistory()`. Session context is the harness-agnostic channel
+for system-level background state — which is why `MessageRole` (above) has no `'system'` member: there is no separate
+role-capability surface to consult, because the type itself makes a `system` transcript message unconstructible.
+
 #### Multimodal input
 
 `ChatSession.chat()` (and the harness `stream()` it delegates to) accept either a plain string or a `MessagePart[]`. Use
@@ -570,9 +598,9 @@ await session.chat([
   },
 ]);
 
-// Inject multimodal context before a chat turn. `createdAt` is omitted —
-// the SDK backfills it before forwarding to the harness.
-await session.addContext([
+// Seed multimodal transcript messages before a chat turn. `createdAt` is
+// omitted — the SDK backfills it before forwarding to the harness.
+await session.addMessages([
   {
     id: 'ctx-screenshot',
     role: 'user',
@@ -1176,6 +1204,10 @@ recognizes today, plus an escape hatch for consumers who need a Claude variant t
 - `Model` — abstract base class. Returned by `Models.getByName(...)` and accepted as an `AgentConfig.modelId` value.
 - `ModelName` — enum of in-tree model identifiers.
 - `Models` — registry: `Models.getByName(name)`, `Models.getDefault()`.
+- `ACCEPTED_MODEL_WIRE_IDS` — the `readonly string[]` union of canonical `ModelName` values and the legacy pinned
+  `llmgateway__*` alias keys `Models.getByName(...)` remaps. Consumers that validate an inbound `modelId` (e.g. a REST
+  body schema) should enumerate against this set, not `Object.values(ModelName)` alone, so a legacy id the resolver can
+  heal is not rejected at the wire boundary.
 - `createClaudeModel(gatewayId, overrides?)` — escape-hatch factory for opting into a Bedrock-Anthropic Claude variant
   the SDK has not released yet (`AgentConfig.modelId` accepts the returned instance directly).
 - `ClaudeModelOverrides` — optional caps for `createClaudeModel`.
@@ -1451,7 +1483,7 @@ This package publishes two ESM entry points:
 | `matchesAlwaysActive`              | `/harness` only                             | Predicate `(entries, serverName, toolName) → boolean` consulted per-tool when stamping always-load metadata or partitioning a tool-search pool. Use this instead of pattern-matching entries by hand so harness behavior stays uniform.                                                                                                                                                                                                                                                                                                                                   |
 | `validateAlwaysActiveEntry`        | `/harness` only                             | Throws on a malformed entry (`{}`, both fields empty). Call once per entry at the harness boundary so a typo fails loud at config time rather than silently dropping the entry on every `stream()`.                                                                                                                                                                                                                                                                                                                                                                       |
 | `splitToolResultsIntoToolMessages` | `/harness` only                             | Read-side normalizer `(Message[]) → Message[]`. Hoists every completed tool call's `tool-result` part onto its own `role: 'tool'` message (leaving the `tool-call` on the assistant message), so `getMessages()` returns the canonical cross-harness layout. Idempotent; backfills a blank result `toolName` from the matching call; preserves `isError` and (in-memory) `error`. Call it at the end of `getMessages()`. (Whether `error` survives to the returned history is a harness-persistence concern — see `AgentHarness.getMessages`; `isError` always survives.) |
-| `mergeToolResultsIntoAssistant`    | `/harness` only                             | Write-side inverse `(Message[]) → Message[]`. Folds each `role: 'tool'` message's result back adjacent to its `tool-call` in the preceding assistant message, so a runtime that stores a completed call as one merged object round-trips losslessly. Call it at the start of `addContext()` before persisting.                                                                                                                                                                                                                                                            |
+| `mergeToolResultsIntoAssistant`    | `/harness` only                             | Write-side inverse `(Message[]) → Message[]`. Folds each `role: 'tool'` message's result back adjacent to its `tool-call` in the preceding assistant message, so a runtime that stores a completed call as one merged object round-trips losslessly. Call it at the start of `addMessages()` before persisting.                                                                                                                                                                                                                                                           |
 
 Minimal skeleton:
 

package/dist/chat-session.d.ts

@@ -4,6 +4,7 @@ import type { StreamOptions } from './harness/harness-config.js';
 import type { TelemetrySlice } from './internal/telemetry-router.js';
 import type { ChatEvent, ChatStreamResult } from './types/events.js';
 import type { Message, MessagePart } from './types/messages.js';
+import type { SessionContext } from './types/session-context.js';
 import { type TelemetryBus, type TelemetryEventCallback } from './types/telemetry-events.js';
 import type { ToolPolicyRule, ToolResultInfo } from './types/tools.js';
 import type { ContextUsage } from './types/usage.js';
@@ -191,15 +192,55 @@ export interface ChatSession {
      */
     getContextUsage(): ContextUsage;
     /**
-     * Inject context messages into the thread without triggering an LLM response.
-     * Useful for seeding file contents, system instructions, or prior conversation
-     * state before the user's first prompt.
+     * Append real conversation messages to the thread **without requesting an
+     * agent response** — the write-only half of a normal turn. The messages
+     * become part of the transcript: they are persisted as `Message`s, appear in
+     * {@link getMessageHistory}, and are replayed to the model as prior
+     * conversation on the next {@link chat}. Use it to seed a thread with earlier
+     * `user` / `assistant` / `tool` turns (e.g. file contents surfaced as a user
+     * message, or a reconstructed prior conversation) before the user's first
+     * live prompt. This is the SDK's equivalent of the service's
+     * `POST /messages` with `noReply=true`, and mirrors OpenCode's
+     * `session.prompt({ noReply: true })` pattern.
      *
-     * Borrowed from OpenCode's `session.prompt({ noReply: true })` pattern.
+     * NOT the same as {@link setSessionContext}. `addMessages` writes *transcript
+     * history* (visible in `getMessageHistory`, one message per call, additive).
+     * `setSessionContext` writes an *out-of-history overlay object* (never in
+     * `getMessageHistory`, whole-object replace, delivered as system-level
+     * background context each turn). Reach for `addMessages` when you want the
+     * model to see prior turns; reach for `setSessionContext` when you want to
+     * attach standing background state that should not read as a conversation
+     * message. `'system'` is not a valid role here (see {@link MessageRole}) —
+     * system-level state belongs on `setSessionContext` or `AgentConfig.instructions`.
      *
-     * @param message - Context to inject (string shorthand or structured messages).
+     * @param message - Messages to append (string shorthand for a single `user`
+     *   message, or structured `Message[]`).
+     */
+    addMessages(message: string | Message[]): Promise<void>;
+    /**
+     * @deprecated Renamed to {@link addMessages} (identical signature and
+     * behavior). The old name read as a sibling of {@link setSessionContext}, but
+     * the two are different channels — `addMessages` appends transcript history,
+     * `setSessionContext` sets an out-of-history overlay. `addContext` will be
+     * removed in a future release; migrate to `addMessages`.
+     *
+     * @param message - Messages to append (string shorthand or structured `Message[]`).
      */
     addContext(message: string | Message[]): Promise<void>;
+    /**
+     * Replace this session's context object in full. Delegates to
+     * {@link AgentHarness.setSessionContext}; see that method's JSDoc for the
+     * full delivery/durability/isolation contract.
+     *
+     * @param content - The full replacement session-context object.
+     */
+    setSessionContext(content: SessionContext): Promise<void>;
+    /**
+     * Read this session's current context object. `{}` if never set.
+     *
+     * @returns The last object passed to {@link setSessionContext}.
+     */
+    getSessionContext(): Promise<SessionContext>;
     /**
      * Register a callback to receive chat events in real-time. Returns an `Unsubscribe` function
      * that removes the listener. The returned function is safe to call after `dispose()` (no-op).
@@ -419,9 +460,23 @@ export declare class DefaultChatSession implements ChatSession {
      * - The formatted message MUST have a newly generated `id` from the injected `idGenerator`.
      * - The formatted message MUST have a `createdAt` timestamp from the injected `clock`.
      * - IF `message` is already an array of `Message` objects, it MUST be used directly.
-     * - MUST delegate the final array of messages to `this.harness.addContext()`, passing `this.agentId` and `this.threadId`.
+     * - MUST delegate the final array of messages to `this.harness.addMessages()`, passing `this.agentId` and `this.threadId`.
      */
+    addMessages(message: string | Message[]): Promise<void>;
+    /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
     addContext(message: string | Message[]): Promise<void>;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.setSessionContext()`, passing `this.agentId`, `this.threadId`,
+     *   and the `content` object unchanged (whole-object set, no merge).
+     */
+    setSessionContext(content: SessionContext): Promise<void>;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.getSessionContext()`, passing `this.agentId` and `this.threadId`.
+     * - MUST return the result directly (`{}` when nothing has been set on this thread).
+     */
+    getSessionContext(): Promise<SessionContext>;
     /**
      * @requirements
      * - MUST register the provided `callback` on the internal `chatEventBus`.

package/dist/chat-session.js

@@ -401,9 +401,9 @@ export class DefaultChatSession {
      * - The formatted message MUST have a newly generated `id` from the injected `idGenerator`.
      * - The formatted message MUST have a `createdAt` timestamp from the injected `clock`.
      * - IF `message` is already an array of `Message` objects, it MUST be used directly.
-     * - MUST delegate the final array of messages to `this.harness.addContext()`, passing `this.agentId` and `this.threadId`.
+     * - MUST delegate the final array of messages to `this.harness.addMessages()`, passing `this.agentId` and `this.threadId`.
      */
-    async addContext(message) {
+    async addMessages(message) {
         this.assertNotDisposed();
         const messages = typeof message === 'string'
             ? [
@@ -423,7 +423,29 @@ export class DefaultChatSession {
                 // same helper at their own `addContext` boundary so a
                 // direct `harness.addContext` call gets the same shape.
                 backfillCreatedAt(message, this.clock);
-        await this.harness.addContext(this.agentId, this.threadId, messages);
+        await this.harness.addMessages(this.agentId, this.threadId, messages);
+    }
+    /** @deprecated Renamed to {@link addMessages}; this delegates verbatim. */
+    async addContext(message) {
+        await this.addMessages(message);
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.setSessionContext()`, passing `this.agentId`, `this.threadId`,
+     *   and the `content` object unchanged (whole-object set, no merge).
+     */
+    async setSessionContext(content) {
+        this.assertNotDisposed();
+        await this.harness.setSessionContext(this.agentId, this.threadId, content);
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.getSessionContext()`, passing `this.agentId` and `this.threadId`.
+     * - MUST return the result directly (`{}` when nothing has been set on this thread).
+     */
+    async getSessionContext() {
+        this.assertNotDisposed();
+        return this.harness.getSessionContext(this.agentId, this.threadId);
     }
     /**
      * @requirements

package/dist/harness/agent-harness.d.ts

@@ -8,6 +8,7 @@ import type { AgentHooks } from '../types/redaction.js';
 import type { WireCommunicationEventCallback } from '../types/wire-communication-event.js';
 import type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
 import type { ModelConnectivityInfo } from '../types/model-connectivity-info.js';
+import type { SessionContext } from '../types/session-context.js';
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
 /**
  * Opt-in helper that brands a harness type with the {@link AgentConfig}
@@ -453,12 +454,99 @@ export interface AgentHarness {
      */
     clearMessages(agentId: string, threadId: string): Promise<void>;
     /**
-     * Save context messages to a thread without triggering an LLM response.
-     * Used for injecting system context, file contents, or prior conversation state.
+     * Append real transcript messages to a thread **without triggering an LLM
+     * response** — the write-only half of a turn. The messages join the thread's
+     * message history: they persist, surface in {@link getMessages} (in canonical
+     * layout, ascending by `createdAt`), and replay to the model as prior
+     * conversation on the next {@link stream}. Used to seed a thread with earlier
+     * `user` / `assistant` / `tool` turns (e.g. file contents as a user message,
+     * or a reconstructed conversation) before the first live prompt.
+     *
+     * Distinct from {@link setSessionContext}, which writes an out-of-history
+     * overlay object that never appears in {@link getMessages}. `addMessages`
+     * writes transcript history; `setSessionContext` writes standing background
+     * state. `'system'` is not a valid role on the messages here (see
+     * {@link MessageRole}); system-level state rides `setSessionContext` or
+     * `AgentConfig.instructions`, never the transcript.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
-     * @param messages - Messages to add to the thread history.
+     * @param messages - Transcript messages to append to the thread history.
      */
-    addContext(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    addMessages(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    /**
+     * @deprecated Renamed to {@link addMessages} (identical signature/behavior).
+     * The name collided semantically with {@link setSessionContext}; the two are
+     * distinct channels (transcript history vs. out-of-history overlay). Optional
+     * during the deprecation window: harnesses keep it as a thin delegator to
+     * {@link addMessages} so existing direct callers keep working, and it will be
+     * removed in a follow-up. New harnesses need only implement `addMessages`.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @param messages - Transcript messages to append to the thread history.
+     */
+    addContext?(agentId: string, threadId: string, messages: Message[]): Promise<void>;
+    /**
+     * Replace this thread's session-context object in full (whole-object set,
+     * not a merge — merge/delete-key semantics are computed by the caller,
+     * typically the service layer's read-merge-write over {@link getSessionContext}).
+     *
+     * The full contract lands in two stages. Persistence is implemented on every
+     * harness in the contract-and-persistence milestone (W-23632685, this PR);
+     * model delivery and `compactThread` carry-forward are implemented per
+     * harness in a follow-up PR (Mastra W-23632686, Claude W-23632691, OpenAI
+     * W-23632694) and are pinned by the seam-gated `runSessionContextConformance`
+     * assertions, which register only once a harness supplies its
+     * render/carry-forward adapter. The staged bullets below state the contract
+     * each harness converges on — not behavior guaranteed live before that
+     * harness's follow-up PR lands.
+     *
+     * Live on every harness this milestone:
+     * - Persists per-thread, durably (survives harness restart against the same
+     *   `storageRootFolder`), with no LLM call.
+     * - Does NOT appear in {@link getMessages} output — this channel is disjoint
+     *   from message history.
+     * - Kept separate from the agent's `instructions` — the stored object is an
+     *   overlay for the turn's system context (once delivery lands), never a
+     *   mutation of `AgentConfig.instructions` or any shared, cross-thread state.
+     * - {@link getSessionContext} returns ONLY the consumer object, and this
+     *   whole-object set replaces ONLY the consumer's session context. It stays
+     *   separate from the SDK-owned carried-forward compaction summary (the
+     *   `previousConversationContext` out-of-history channel that lands later with
+     *   the History-Continuity subsystem, W-23799514) and MUST NOT clobber it —
+     *   the two out-of-history channels never share storage. That summary channel
+     *   does not exist yet, so the "must not clobber" half is pinned by a
+     *   seam-gated assertion that goes live alongside it.
+     *
+     * Staged per harness (follow-up PR above; conformance-pinned):
+     * - Delivered to the model as system-level context on every subsequent turn
+     *   on this thread, rendered deterministically (stable key order) so two
+     *   calls with the same object produce byte-identical rendered text.
+     * - Carries forward to the new thread on {@link compactThread}.
+     *   `compactThread` ROTATES to a new thread (summarize → seed the new
+     *   thread → best-effort destroy the source), so the source thread does not
+     *   survive the call. Carry-forward therefore means the object is COPIED
+     *   from the source onto the new thread DURING compaction, before the
+     *   source is retired — reading the returned thread yields the same object
+     *   the source carried.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @param content - The full replacement session-context object.
+     */
+    setSessionContext(agentId: string, threadId: string, content: SessionContext): Promise<void>;
+    /**
+     * Read this thread's current session-context object.
+     *
+     * Returns `{}` — never `null` or `undefined` — when nothing has been set on
+     * this thread yet. An empty and a never-set context are behaviorally
+     * identical (both contribute nothing to the rendered prompt), so callers
+     * never need a null-check.
+     *
+     * @param agentId - ID of the agent.
+     * @param threadId - ID of the conversation thread.
+     * @returns The last object passed to {@link setSessionContext}, or `{}`.
+     */
+    getSessionContext(agentId: string, threadId: string): Promise<SessionContext>;
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export type { Message, MessagePart, ImagePart, FilePart } from './types/messages.js';
+export type { Message, MessagePart, MessageRole, ImagePart, FilePart } from './types/messages.js';
+export type { JsonValue, SessionContext } from './types/session-context.js';
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolCallDeltaEvent, ToolApprovalRequestEvent, ToolResultEvent, ToolProgressEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
 export type { Decision, ToolDefinition, ToolCallInfo, ToolMatcher, ToolPolicyRule, ToolResultInfo, } from './types/tools.js';
 export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
@@ -9,7 +10,7 @@ export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/h
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
-export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles } from './models/index.js';
+export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles, ACCEPTED_MODEL_WIRE_IDS, } from './models/index.js';
 export type { ClaudeModelOverrides, MultimodalFile, SupportedFileFormat, ThinkingMode } from './models/index.js';
 export { MimeType } from './models/index.js';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';

package/dist/index.js

@@ -10,7 +10,7 @@
 export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
-export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles } from './models/index.js';
+export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles, ACCEPTED_MODEL_WIRE_IDS, } from './models/index.js';
 export { MimeType } from './models/index.js';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 // ── Agent Layer ─────────────────────────────────────────────────────

package/dist/models/index.d.ts

@@ -25,6 +25,16 @@ export { createClaudeModel, type ClaudeModelOverrides } from './create-claude-mo
  * (`sfdc_ai__DefaultGPT5` etc.) are already live `ModelName` values.
  */
 export declare const LEGACY_MODEL_ID_ALIASES: Readonly<Record<string, ModelName>>;
+/**
+ * Every model id accepted on an inbound request: the canonical {@link ModelName}
+ * values plus the legacy `llmgateway__*` alias keys {@link getByName} remaps.
+ *
+ * Consumers validating an inbound `modelId` should enumerate against this set, not
+ * `Object.values(ModelName)` alone — otherwise a legacy id is rejected at the wire
+ * boundary before the resolver that would heal it is reached. Deriving both this
+ * set and the resolver from {@link LEGACY_MODEL_ID_ALIASES} keeps them from drifting.
+ */
+export declare const ACCEPTED_MODEL_WIRE_IDS: readonly string[];
 export declare function getDefault(): Model;
 export declare function getByName(modelName: ModelName): Model;
 export declare const Models: {

package/dist/models/index.js

@@ -51,6 +51,19 @@ export const LEGACY_MODEL_ID_ALIASES = {
     llmgateway__BedrockAnthropicClaude47Opus: ModelName.CLAUDE_OPUS_4_7,
     llmgateway__BedrockAnthropicClaude48Opus: ModelName.CLAUDE_OPUS_4_8,
 };
+/**
+ * Every model id accepted on an inbound request: the canonical {@link ModelName}
+ * values plus the legacy `llmgateway__*` alias keys {@link getByName} remaps.
+ *
+ * Consumers validating an inbound `modelId` should enumerate against this set, not
+ * `Object.values(ModelName)` alone — otherwise a legacy id is rejected at the wire
+ * boundary before the resolver that would heal it is reached. Deriving both this
+ * set and the resolver from {@link LEGACY_MODEL_ID_ALIASES} keeps them from drifting.
+ */
+export const ACCEPTED_MODEL_WIRE_IDS = Object.freeze([
+    ...Object.values(ModelName),
+    ...Object.keys(LEGACY_MODEL_ID_ALIASES),
+]);
 export function getDefault() {
     return new ClaudeSonnet46();
 }

package/dist/types/messages.d.ts

@@ -2,12 +2,19 @@ import type { ToolCallInfo, ToolResultInfo } from './tools.js';
 /**
  * Role of a message in a conversation. Aligned with AI SDK `ModelMessage` roles.
  *
- * - `system` -- Instructions to the model (not visible to end users)
  * - `user` -- Messages from the human user
  * - `assistant` -- Messages generated by the model
  * - `tool` -- Results from tool executions
+ *
+ * `'system'` is deliberately NOT a member. System-level state has two dedicated,
+ * harness-agnostic channels — static agent instructions (`AgentConfig.instructions`)
+ * and per-thread session context (`setSessionContext`) — neither of which flows
+ * through the `Message` transcript. `getMessages` never emits a `system` message,
+ * and a consumer can never construct one to seed via `addContext` / `POST /messages`.
+ * A harness may widen this role set internally for its own runtime, but MUST NOT
+ * surface a `system`-role message back across the SDK boundary.
  */
-export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export type MessageRole = 'user' | 'assistant' | 'tool';
 /**
  * A single message in a conversation thread.
  *
@@ -27,7 +34,7 @@ export type Message = {
     /**
      * Timestamp of when the message was created. **Always populated** on
      * messages returned from `ChatSession.getMessageHistory()`. **Optional on
-     * write** — consumers constructing `Message` for `ChatSession.addContext()`
+     * write** — consumers constructing `Message` for `ChatSession.addMessages()`
      * may omit it; the SDK backfills the current time before forwarding to
      * the harness, so the on-read contract still holds.
      *

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

@@ -0,0 +1,19 @@
+/**
+ * A JSON-serializable value. Excludes `undefined`, functions, `Date`, class
+ * instances, and anything else that doesn't survive `JSON.stringify` /
+ * `JSON.parse` unchanged.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * A per-thread session-context object: arbitrary consumer-defined keys mapped
+ * to JSON-serializable values, delivered to the model as system-level context
+ * on every turn and kept durable across harness restart.
+ *
+ * See {@link AgentHarness.setSessionContext} / {@link AgentHarness.getSessionContext}
+ * for the full contract every harness implementation upholds.
+ */
+export type SessionContext = {
+    [key: string]: JsonValue;
+};

package/dist/types/session-context.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=session-context.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -47,9 +47,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.44.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.47.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.13.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.46.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.49.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.15.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.26",