@salesforce/sfdx-agent-sdk 0.69.0 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +1 -1
  3. package/dist/harness/agent-harness.d.ts +21 -9
  4. package/package.json +4 -4
package/CHANGELOG.md CHANGED
@@ -3,6 +3,11 @@
3
3
  All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
4
4
  Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
5
5
 
6
+ ## [0.70.0] - 2026-09-02
7
+
8
+ ### Features
9
+ - **harness-claude**: render session context + clone/compact carry-forward @W-23632691@ ([#758](https://github.com/forcedotcom/agentic-dx/pull/758))
10
+
6
11
  ## [0.69.0] - 2026-09-02
7
12
 
8
13
  _No changes — released alongside dependent packages._
package/README.md CHANGED
@@ -174,7 +174,7 @@ A single conversation thread.
174
174
  | `getContextUsage` | `() => ContextUsage` | Snapshot of how much of the model's context window the most recent turn used. |
175
175
  | `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`. |
176
176
  | `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`. |
177
- | `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()`. Rendering the stored object into the model's system-level context on subsequent turns is delivered per harness (live on Mastra; the remaining harnesses land it in their own follow-ups). Delegates to `AgentHarness.setSessionContext` — see that method's JSDoc for the full delivery/durability/isolation contract. |
177
+ | `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()`. **Rendering is staged per harness** — the Mastra and Claude harnesses render the stored object into the model's system-level context on every subsequent turn (deterministic, key-ordered); OpenAI Agents stages its rendering in a follow-up PR (persistence is already live on all three). Delegates to `AgentHarness.setSessionContext` — see that method's JSDoc for the full delivery/durability/isolation contract. |
178
178
  | `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. |
179
179
  | `subscribe` | `(callback: (event: ChatEvent) => void) => void` | Register a real-time event listener. |
180
180
  | `unsubscribe` | `(callback: (event: ChatEvent) => void) => void` | Remove a listener. |
package/dist/harness/agent-harness.d.ts CHANGED
@@ -338,6 +338,15 @@ export interface AgentHarness {
338
338
  * harnesses that mirror them in-process, but no persisted transcript
339
339
  * exists to fork.
340
340
  *
341
+ * **Session context carries forward.** A clone is a continuation of the same
342
+ * session, so the source thread's `SessionContext` (see
343
+ * {@link setSessionContext}) MUST be copied onto the new thread — a
344
+ * subsequent `getSessionContext(agentId, clonedThreadId)` returns the source's
345
+ * object, while the source is left intact. This mirrors the same carry-forward
346
+ * requirement on {@link compactThread}. Pinned by the shared
347
+ * `runSessionContextConformance` clone carry-forward assertion, staged per
348
+ * harness (Claude first; Mastra / OpenAI follow in their own render PRs).
349
+ *
341
350
  * @param agentId - ID of the owning agent.
342
351
  * @param sourceThreadId - ID of the thread to clone.
343
352
  * @returns The ID of the cloned thread.
@@ -538,15 +547,18 @@ export interface AgentHarness {
538
547
  * does not exist yet, so the "must not clobber" half is pinned by a
539
548
  * seam-gated assertion that goes live alongside it.
540
549
  *
541
- * Enforcement runs ahead on Mastra: it rejects a set on a never-created
542
- * thread with `THREAD_NOT_FOUND` (create-first) and an oversized / too-deeply
543
- * nested object with `INVALID_MESSAGE_CONTENT` pre-write. Claude and OpenAI do
544
- * not enforce these yet (no create-first check, no size/depth cap), so a
545
- * consumer targeting cross-harness portability should not rely on either being
546
- * enforced until those harnesses' work lands.
547
- *
548
- * Staged per harness (live on Mastra, pending on Claude/OpenAI above;
549
- * conformance-pinned):
550
+ * Enforcement is staged per harness. Create-first (reject a set on a
551
+ * never-created thread with `THREAD_NOT_FOUND`) runs on Mastra AND Claude;
552
+ * OpenAI does not enforce it yet. The size / depth caps (reject an oversized
553
+ * or too-deeply nested object with `INVALID_MESSAGE_CONTENT` pre-write) run on
554
+ * Mastra only — Claude and OpenAI do not cap size/depth at the harness; the
555
+ * cross-harness size limit is enforced once at the service `/context` wire. A
556
+ * consumer targeting cross-harness portability should not rely on create-first
557
+ * on OpenAI, nor on size/depth being enforced at any harness other than
558
+ * Mastra, until that work lands.
559
+ *
560
+ * Staged per harness (render + carry-forward live on Mastra and Claude,
561
+ * pending on OpenAI; conformance-pinned):
550
562
  * - Delivered to the model as system-level context on every subsequent turn
551
563
  * on this thread, rendered deterministically (stable key order) so two
552
564
  * calls with the same object produce byte-identical rendered text.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@salesforce/sfdx-agent-sdk",
3
- "version": "0.69.0",
3
+ "version": "0.70.0",
4
4
  "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -47,9 +47,9 @@
47
47
  },
48
48
  "devDependencies": {
49
49
  "@eslint/js": "^10.0.1",
50
- "@salesforce/sfdx-agent-harness-claude": "0.65.0",
51
- "@salesforce/sfdx-agent-harness-mastra": "0.68.0",
52
- "@salesforce/sfdx-agent-harness-openai": "0.34.0",
50
+ "@salesforce/sfdx-agent-harness-claude": "0.66.0",
51
+ "@salesforce/sfdx-agent-harness-mastra": "0.69.0",
52
+ "@salesforce/sfdx-agent-harness-openai": "0.35.0",
53
53
  "@types/node": "^22.20.1",
54
54
  "@vitest/coverage-istanbul": "^4.1.10",
55
55
  "@vitest/eslint-plugin": "^1.6.27",