@salesforce/sfdx-agent-sdk 0.53.0 → 0.55.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.
- package/CHANGELOG.md +11 -0
- package/README.md +16 -15
- package/dist/errors.d.ts +1 -0
- package/dist/errors.js +1 -0
- package/dist/harness/agent-harness.d.ts +18 -9
- package/package.json +7 -7
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,17 @@
|
|
|
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.55.0] - 2026-08-25
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
- **harness-mastra**: store session context in a harness-owned per-thread store @W-23632686@ ([#765](https://github.com/forcedotcom/agentic-dx/pull/765))
|
|
10
|
+
|
|
11
|
+
## [0.54.0] - 2026-08-25
|
|
12
|
+
|
|
13
|
+
### Chores
|
|
14
|
+
- **deps-dev**: bump @vitest/eslint-plugin from 1.6.26 to 1.6.27 in the vitest group across 1 directory ([#762](https://github.com/forcedotcom/agentic-dx/pull/762))
|
|
15
|
+
- **deps-dev**: bump globals from 17.9.0 to 17.11.0 in the dev-dependencies group ([#761](https://github.com/forcedotcom/agentic-dx/pull/761))
|
|
16
|
+
|
|
6
17
|
## [0.53.0] - 2026-08-24
|
|
7
18
|
|
|
8
19
|
### Features
|
package/README.md
CHANGED
|
@@ -173,7 +173,7 @@ A single conversation thread.
|
|
|
173
173
|
| `getContextUsage` | `() => ContextUsage` | Snapshot of how much of the model's context window the most recent turn used. |
|
|
174
174
|
| `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`. |
|
|
175
175
|
| `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`. |
|
|
176
|
-
| `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()`.
|
|
176
|
+
| `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
177
|
| `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. |
|
|
178
178
|
| `subscribe` | `(callback: (event: ChatEvent) => void) => void` | Register a real-time event listener. |
|
|
179
179
|
| `unsubscribe` | `(callback: (event: ChatEvent) => void) => void` | Remove a listener. |
|
|
@@ -757,20 +757,21 @@ totals, subscribe to `chat-stream-completed` telemetry instead.
|
|
|
757
757
|
The SDK throws `AgentSDKError` for predictable not-found and compatibility conditions. Each error has a `type` property
|
|
758
758
|
from `AgentSDKErrorType`:
|
|
759
759
|
|
|
760
|
-
| Type | Thrown By
|
|
761
|
-
| -------------------------------- |
|
|
762
|
-
| `AGENT_NOT_FOUND` | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`
|
|
763
|
-
| `CHAT_SESSION_NOT_FOUND` | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`
|
|
764
|
-
| `COMPACTION_FAILED` | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.
|
|
765
|
-
| `DISPOSED` | `Agent` and `ChatSession` methods called after the owner has been destroyed
|
|
766
|
-
| `INCOMPATIBLE_HARNESS` | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's
|
|
767
|
-
| `INVALID_MESSAGE_CONTENT` | `ChatSession.chat()` / harness `stream()` when a message part is not valid as input (a `tool-call`/`tool-result` part, or non-base64-string file data)
|
|
768
|
-
| `MCP_SERVER_DISABLED` | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false`
|
|
769
|
-
| `MCP_SERVER_NOT_FOUND` | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config
|
|
770
|
-
| `MODEL_NOT_SUPPORTED_BY_HARNESS` | `AgentManager.createAgent()` / `Agent.updateAgentConfig()` (G8 pre-flight) when the resolved `ModelConnectivityInfo.providerHint` isn't in the harness's `supportedProviderHints`. Surfaces before any harness work runs (no MCP discovery, no subprocess spawn, no language-model construction) so the consumer can branch cleanly on `err.type` and recover without resource cleanup.
|
|
771
|
-
| `MULTIMODAL_NOT_SUPPORTED` | `ChatSession.chat()` / harness `stream()` when a file fails pre-stream capability validation (unsupported format, too large, or too many files)
|
|
772
|
-
| `NOT_SUPPORTED` | `ApiKeyConnectivityResolver.resolve()` when the consumer-supplied `getApiKey` returns an empty / nullish value. Surfaces locally so the consumer sees "the resolver returned an empty key" rather than chasing a 401 through provider logs after `Authorization: Bearer ` (no key) lands on the wire.
|
|
773
|
-
| `
|
|
760
|
+
| Type | Thrown By |
|
|
761
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
762
|
+
| `AGENT_NOT_FOUND` | `AgentManager.getAgent()`, `AgentManager.destroyAgent()` |
|
|
763
|
+
| `CHAT_SESSION_NOT_FOUND` | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()` |
|
|
764
|
+
| `COMPACTION_FAILED` | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact. |
|
|
765
|
+
| `DISPOSED` | `Agent` and `ChatSession` methods called after the owner has been destroyed |
|
|
766
|
+
| `INCOMPATIBLE_HARNESS` | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
|
|
767
|
+
| `INVALID_MESSAGE_CONTENT` | `ChatSession.chat()` / harness `stream()` when a message part is not valid as input (a `tool-call`/`tool-result` part, or non-base64-string file data); also `ChatSession.setSessionContext()` / harness `setSessionContext()` when the object exceeds a harness's size / nesting bounds (Mastra: 256 KiB serialized, depth 200). `getSessionContext()` never throws on a corrupt stored slot — it soft-skips to `{}` and logs. |
|
|
768
|
+
| `MCP_SERVER_DISABLED` | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false` |
|
|
769
|
+
| `MCP_SERVER_NOT_FOUND` | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config |
|
|
770
|
+
| `MODEL_NOT_SUPPORTED_BY_HARNESS` | `AgentManager.createAgent()` / `Agent.updateAgentConfig()` (G8 pre-flight) when the resolved `ModelConnectivityInfo.providerHint` isn't in the harness's `supportedProviderHints`. Surfaces before any harness work runs (no MCP discovery, no subprocess spawn, no language-model construction) so the consumer can branch cleanly on `err.type` and recover without resource cleanup. |
|
|
771
|
+
| `MULTIMODAL_NOT_SUPPORTED` | `ChatSession.chat()` / harness `stream()` when a file fails pre-stream capability validation (unsupported format, too large, or too many files) |
|
|
772
|
+
| `NOT_SUPPORTED` | `ApiKeyConnectivityResolver.resolve()` when the consumer-supplied `getApiKey` returns an empty / nullish value. Surfaces locally so the consumer sees "the resolver returned an empty key" rather than chasing a 401 through provider logs after `Authorization: Bearer ` (no key) lands on the wire. |
|
|
773
|
+
| `THREAD_NOT_FOUND` | `ChatSession.setSessionContext()` / harness `setSessionContext()` when seeding context on a thread that was never created (create-first contract). A `ChatSession` is only reachable via `createChatSession()` → `createThread`, so this indicates a seed-before-create misuse; the harness maps its runtime "thread not found" to this typed error. |
|
|
774
|
+
| `TOOL_CALL_NOT_FOUND` | `ChatSession.approveToolCall()` / `declineToolCall()` / `submitToolResult()` when the supplied `toolCallId` doesn't match any pending tool-call request on the current session. Typically indicates a wrong-id, wrong-session, or already-settled call. Both production harnesses (Mastra, Claude) throw this from their per-turn approval coordinator. |
|
|
774
775
|
|
|
775
776
|
```typescript
|
|
776
777
|
import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
|
package/dist/errors.d.ts
CHANGED
|
@@ -11,6 +11,7 @@ export declare const AgentSDKErrorType: {
|
|
|
11
11
|
readonly MODEL_NOT_SUPPORTED_BY_HARNESS: 'MODEL_NOT_SUPPORTED_BY_HARNESS';
|
|
12
12
|
readonly MULTIMODAL_NOT_SUPPORTED: 'MULTIMODAL_NOT_SUPPORTED';
|
|
13
13
|
readonly NOT_SUPPORTED: 'NOT_SUPPORTED';
|
|
14
|
+
readonly THREAD_NOT_FOUND: 'THREAD_NOT_FOUND';
|
|
14
15
|
readonly TOOL_CALL_NOT_FOUND: 'TOOL_CALL_NOT_FOUND';
|
|
15
16
|
};
|
|
16
17
|
export type AgentSDKErrorType = (typeof AgentSDKErrorType)[keyof typeof AgentSDKErrorType];
|
package/dist/errors.js
CHANGED
|
@@ -15,6 +15,7 @@ export const AgentSDKErrorType = {
|
|
|
15
15
|
MODEL_NOT_SUPPORTED_BY_HARNESS: 'MODEL_NOT_SUPPORTED_BY_HARNESS',
|
|
16
16
|
MULTIMODAL_NOT_SUPPORTED: 'MULTIMODAL_NOT_SUPPORTED',
|
|
17
17
|
NOT_SUPPORTED: 'NOT_SUPPORTED',
|
|
18
|
+
THREAD_NOT_FOUND: 'THREAD_NOT_FOUND',
|
|
18
19
|
TOOL_CALL_NOT_FOUND: 'TOOL_CALL_NOT_FOUND',
|
|
19
20
|
};
|
|
20
21
|
export class AgentSDKError extends Error {
|
|
@@ -510,14 +510,15 @@ export interface AgentHarness {
|
|
|
510
510
|
* typically the service layer's read-merge-write over {@link getSessionContext}).
|
|
511
511
|
*
|
|
512
512
|
* The full contract lands in two stages. Persistence is implemented on every
|
|
513
|
-
* harness in the contract-and-persistence milestone (W-23632685
|
|
514
|
-
*
|
|
515
|
-
*
|
|
516
|
-
* W-23632694)
|
|
517
|
-
* assertions, which register only once a
|
|
518
|
-
* render/carry-forward adapter
|
|
519
|
-
*
|
|
520
|
-
* harness
|
|
513
|
+
* harness in the contract-and-persistence milestone (W-23632685). Model
|
|
514
|
+
* delivery and `compactThread` carry-forward are implemented per harness:
|
|
515
|
+
* **Mastra is live (W-23632686)**; Claude (W-23632691) and OpenAI
|
|
516
|
+
* (W-23632694) are pending. They are pinned by the seam-gated
|
|
517
|
+
* `runSessionContextConformance` assertions, which register only once a
|
|
518
|
+
* harness supplies its render/carry-forward adapter (live for Mastra,
|
|
519
|
+
* `it.todo` for the harnesses still pending). The staged bullets below state
|
|
520
|
+
* the contract each harness converges on — not behavior guaranteed live on a
|
|
521
|
+
* harness before its delivery work lands.
|
|
521
522
|
*
|
|
522
523
|
* Live on every harness this milestone:
|
|
523
524
|
* - Persists per-thread, durably (survives harness restart against the same
|
|
@@ -536,7 +537,15 @@ export interface AgentHarness {
|
|
|
536
537
|
* does not exist yet, so the "must not clobber" half is pinned by a
|
|
537
538
|
* seam-gated assertion that goes live alongside it.
|
|
538
539
|
*
|
|
539
|
-
*
|
|
540
|
+
* Enforcement runs ahead on Mastra: it rejects a set on a never-created
|
|
541
|
+
* thread with `THREAD_NOT_FOUND` (create-first) and an oversized / too-deeply
|
|
542
|
+
* nested object with `INVALID_MESSAGE_CONTENT` pre-write. Claude and OpenAI do
|
|
543
|
+
* not enforce these yet (no create-first check, no size/depth cap), so a
|
|
544
|
+
* consumer targeting cross-harness portability should not rely on either being
|
|
545
|
+
* enforced until those harnesses' work lands.
|
|
546
|
+
*
|
|
547
|
+
* Staged per harness (live on Mastra, pending on Claude/OpenAI above;
|
|
548
|
+
* conformance-pinned):
|
|
540
549
|
* - Delivered to the model as system-level context on every subsequent turn
|
|
541
550
|
* on this thread, rendered deterministically (stable key order) so two
|
|
542
551
|
* 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.
|
|
3
|
+
"version": "0.55.0",
|
|
4
4
|
"description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -43,22 +43,22 @@
|
|
|
43
43
|
"LICENSE.txt"
|
|
44
44
|
],
|
|
45
45
|
"dependencies": {
|
|
46
|
-
"@salesforce/agentic-common": "0.
|
|
46
|
+
"@salesforce/agentic-common": "0.17.0"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"@eslint/js": "^10.0.1",
|
|
50
|
-
"@salesforce/sfdx-agent-harness-claude": "0.
|
|
51
|
-
"@salesforce/sfdx-agent-harness-mastra": "0.
|
|
52
|
-
"@salesforce/sfdx-agent-harness-openai": "0.
|
|
50
|
+
"@salesforce/sfdx-agent-harness-claude": "0.51.0",
|
|
51
|
+
"@salesforce/sfdx-agent-harness-mastra": "0.54.0",
|
|
52
|
+
"@salesforce/sfdx-agent-harness-openai": "0.20.0",
|
|
53
53
|
"@types/node": "^22.20.1",
|
|
54
54
|
"@vitest/coverage-istanbul": "^4.1.10",
|
|
55
|
-
"@vitest/eslint-plugin": "^1.6.
|
|
55
|
+
"@vitest/eslint-plugin": "^1.6.27",
|
|
56
56
|
"eslint": "^10.8.1",
|
|
57
57
|
"eslint-config-prettier": "^10.1.8",
|
|
58
58
|
"eslint-import-resolver-typescript": "^4.4.5",
|
|
59
59
|
"eslint-plugin-import": "^2.32.0",
|
|
60
60
|
"eslint-plugin-n": "^18.3.0",
|
|
61
|
-
"globals": "^17.
|
|
61
|
+
"globals": "^17.11.0",
|
|
62
62
|
"lint-staged": "^17.3.0",
|
|
63
63
|
"prettier": "^3.9.6",
|
|
64
64
|
"rimraf": "^6.1.3",
|