@salesforce/sfdx-agent-sdk 0.8.0 → 0.9.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/README.md +20 -17
- package/dist/agent.d.ts +22 -0
- package/dist/agent.js +4 -0
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +2 -0
- package/dist/harness/agent-harness.d.ts +28 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -129,23 +129,24 @@ A configured AI agent. Factory for chat sessions. The optional `H` type paramete
|
|
|
129
129
|
— harness-specific features are reached through `manager.extensions`, not `agent.extensions`. The default `AgentHarness`
|
|
130
130
|
keeps unparameterized call sites working.
|
|
131
131
|
|
|
132
|
-
| Method | Signature | Description
|
|
133
|
-
| ---------------------- | ---------------------------------------------------------------------------------- |
|
|
134
|
-
| `getId` | `() => string` | Agent identifier.
|
|
135
|
-
| `getProjectRoot` | `() => string` | Absolute project path.
|
|
136
|
-
| `getOrgConnectionInfo` | `() => OrgConnectionInfo` | Org metadata (orgId, alias, instanceUrl, username, env).
|
|
137
|
-
| `getAgentConfig` | `() => AgentConfig` | Current configuration (shallow copy).
|
|
138
|
-
| `getMcpServerInfo` | `() => McpServerInfo[]` | MCP server status and discovered tools.
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
132
|
+
| Method | Signature | Description |
|
|
133
|
+
| ---------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| `getId` | `() => string` | Agent identifier. |
|
|
135
|
+
| `getProjectRoot` | `() => string` | Absolute project path. |
|
|
136
|
+
| `getOrgConnectionInfo` | `() => OrgConnectionInfo` | Org metadata (orgId, alias, instanceUrl, username, env). |
|
|
137
|
+
| `getAgentConfig` | `() => AgentConfig` | Current configuration (shallow copy). |
|
|
138
|
+
| `getMcpServerInfo` | `() => McpServerInfo[]` | MCP server status and discovered tools. |
|
|
139
|
+
| `reconnectMcpServer` | `(serverName: string) => Promise<void>` | Recover one MCP server without recycling the agent. Semantics vary by harness — observe via `getMcpServerInfo()` and discovery telemetry. |
|
|
140
|
+
| `updateAgentConfig` | `(config?: AgentConfig, options?: { abortSignal?: AbortSignal }) => Promise<void>` | Merge new config into the live agent. |
|
|
141
|
+
| `createChatSession` | `() => Promise<ChatSession>` | Open a new conversation thread. |
|
|
142
|
+
| `getChatSession` | `(sessionId: string) => ChatSession` | Retrieve a session. Throws `AgentSDKError` (`CHAT_SESSION_NOT_FOUND`). |
|
|
143
|
+
| `getChatSessionIds` | `() => string[]` | List active session IDs. |
|
|
144
|
+
| `destroyChatSession` | `(sessionId: string) => Promise<void>` | Destroy a session and its history. |
|
|
145
|
+
| `cloneChatSession` | `(sourceSessionId: string) => Promise<ChatSession>` | Clone a session with its message history. |
|
|
146
|
+
| `compactChatSession` | `(sessionId: string) => Promise<ChatSession>` | Compact a session into a summarized new session. |
|
|
147
|
+
| `destroy` | `() => Promise<void>` | Destroy the agent and all its sessions. |
|
|
148
|
+
| `onTelemetry` | `(callback: TelemetryEventCallback) => Unsubscribe` | Subscribe to telemetry scoped to this agent (and its sessions). |
|
|
149
|
+
| `onLog` | `(callback: (record: LogRecord) => void) => Unsubscribe` | Subscribe to logs scoped to this agent (and its sessions). |
|
|
149
150
|
|
|
150
151
|
### `ChatSession`
|
|
151
152
|
|
|
@@ -361,6 +362,8 @@ from `AgentSDKErrorType`:
|
|
|
361
362
|
| `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. |
|
|
362
363
|
| `DISPOSED` | `Agent` and `ChatSession` methods called after the owner has been destroyed |
|
|
363
364
|
| `INCOMPATIBLE_HARNESS` | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
|
|
365
|
+
| `MCP_SERVER_DISABLED` | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false` |
|
|
366
|
+
| `MCP_SERVER_NOT_FOUND` | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config |
|
|
364
367
|
|
|
365
368
|
```typescript
|
|
366
369
|
import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
|
package/dist/agent.d.ts
CHANGED
|
@@ -41,6 +41,27 @@ export interface Agent {
|
|
|
41
41
|
* snapshot — status is updated asynchronously by background discovery promises.
|
|
42
42
|
*/
|
|
43
43
|
getMcpServerInfo(): McpServerInfo[];
|
|
44
|
+
/**
|
|
45
|
+
* Request a reconnect of one MCP server on this agent without recycling
|
|
46
|
+
* any other server, custom tool, instruction, or skill. Useful for
|
|
47
|
+
* recovering a single failed MCP server without paying the full
|
|
48
|
+
* `updateAgentConfig` destroy/recreate cost.
|
|
49
|
+
*
|
|
50
|
+
* Throws if `serverName` is not configured on this agent or if the named
|
|
51
|
+
* server is disabled (`enabled: false`).
|
|
52
|
+
*
|
|
53
|
+
* **Semantics vary by harness.** Some harnesses await transport reconnect
|
|
54
|
+
* + discovery before this resolves (eager); others schedule the work and
|
|
55
|
+
* resolve as soon as the request is accepted (deferred — the actual
|
|
56
|
+
* reconnect happens on the next opportunity, typically the next stream).
|
|
57
|
+
* Consumers observe the result through {@link getMcpServerInfo} and the
|
|
58
|
+
* harness's MCP-discovery telemetry events, not the returned promise's
|
|
59
|
+
* resolution. Discovery / transport failures are reported on the
|
|
60
|
+
* per-server status, not by rejecting this promise.
|
|
61
|
+
*
|
|
62
|
+
* @param serverName - Name of the MCP server to reconnect.
|
|
63
|
+
*/
|
|
64
|
+
reconnectMcpServer(serverName: string): Promise<void>;
|
|
44
65
|
/**
|
|
45
66
|
* Update the agent's configuration. The harness applies the changes
|
|
46
67
|
* to the live agent (e.g., new instructions, tools, model).
|
|
@@ -152,6 +173,7 @@ export declare class DefaultAgent implements Agent {
|
|
|
152
173
|
*/
|
|
153
174
|
getAgentConfig(): AgentConfig;
|
|
154
175
|
getMcpServerInfo(): McpServerInfo[];
|
|
176
|
+
reconnectMcpServer(serverName: string): Promise<void>;
|
|
155
177
|
/**
|
|
156
178
|
* @requirements
|
|
157
179
|
* - MUST merge the provided `config` with the internal `config` object.
|
package/dist/agent.js
CHANGED
|
@@ -91,6 +91,10 @@ export class DefaultAgent {
|
|
|
91
91
|
this.assertNotDisposed();
|
|
92
92
|
return this.harness.getMcpServerInfo(this.agentId);
|
|
93
93
|
}
|
|
94
|
+
async reconnectMcpServer(serverName) {
|
|
95
|
+
this.assertNotDisposed();
|
|
96
|
+
await this.harness.reconnectMcpServer(this.agentId, serverName);
|
|
97
|
+
}
|
|
94
98
|
/**
|
|
95
99
|
* @requirements
|
|
96
100
|
* - MUST merge the provided `config` with the internal `config` object.
|
package/dist/errors.d.ts
CHANGED
|
@@ -4,6 +4,8 @@ export declare const AgentSDKErrorType: {
|
|
|
4
4
|
readonly COMPACTION_FAILED: "COMPACTION_FAILED";
|
|
5
5
|
readonly DISPOSED: "DISPOSED";
|
|
6
6
|
readonly INCOMPATIBLE_HARNESS: "INCOMPATIBLE_HARNESS";
|
|
7
|
+
readonly MCP_SERVER_DISABLED: "MCP_SERVER_DISABLED";
|
|
8
|
+
readonly MCP_SERVER_NOT_FOUND: "MCP_SERVER_NOT_FOUND";
|
|
7
9
|
readonly NOT_SUPPORTED: "NOT_SUPPORTED";
|
|
8
10
|
};
|
|
9
11
|
export type AgentSDKErrorType = (typeof AgentSDKErrorType)[keyof typeof AgentSDKErrorType];
|
package/dist/errors.js
CHANGED
|
@@ -8,6 +8,8 @@ export const AgentSDKErrorType = {
|
|
|
8
8
|
COMPACTION_FAILED: 'COMPACTION_FAILED',
|
|
9
9
|
DISPOSED: 'DISPOSED',
|
|
10
10
|
INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
|
|
11
|
+
MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED',
|
|
12
|
+
MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND',
|
|
11
13
|
NOT_SUPPORTED: 'NOT_SUPPORTED',
|
|
12
14
|
};
|
|
13
15
|
export class AgentSDKError extends Error {
|
|
@@ -128,6 +128,34 @@ export interface AgentHarness {
|
|
|
128
128
|
* @returns Info for each configured MCP server (empty array if none configured).
|
|
129
129
|
*/
|
|
130
130
|
getMcpServerInfo(agentId: string): McpServerInfo[];
|
|
131
|
+
/**
|
|
132
|
+
* Request a reconnect of one MCP server attached to the agent without
|
|
133
|
+
* recycling any other server, custom tool, instruction, or skill.
|
|
134
|
+
*
|
|
135
|
+
* **Scheduled-minimum contract.** Implementors MUST validate the request
|
|
136
|
+
* (unknown agent id / unknown server name / disabled server reject) and
|
|
137
|
+
* MUST cause the named server to be reconnected. They MAY satisfy the
|
|
138
|
+
* reconnect eagerly (await transport reconnect + discovery before
|
|
139
|
+
* resolving) or schedule it (resolve once the request is accepted; carry
|
|
140
|
+
* out the work on the next opportunity, e.g. the next stream). Consumers
|
|
141
|
+
* observe the result via {@link getMcpServerInfo} and the harness's
|
|
142
|
+
* MCP-discovery telemetry events, not the returned promise's resolution.
|
|
143
|
+
*
|
|
144
|
+
* Implementors MUST:
|
|
145
|
+
* - throw if `agentId` is not registered.
|
|
146
|
+
* - throw if `serverName` is not configured on this agent.
|
|
147
|
+
* - throw if `serverName` is configured but disabled (`enabled: false`).
|
|
148
|
+
*
|
|
149
|
+
* Implementors MUST NOT:
|
|
150
|
+
* - reject on transient transport / discovery failure — record those on
|
|
151
|
+
* the per-server status (visible via {@link getMcpServerInfo}).
|
|
152
|
+
* - mutate `AgentConfig` or persist anything — reconnect is a runtime
|
|
153
|
+
* operation, not a config update.
|
|
154
|
+
*
|
|
155
|
+
* @param agentId - ID of the agent owning the server.
|
|
156
|
+
* @param serverName - Name of the MCP server to reconnect.
|
|
157
|
+
*/
|
|
158
|
+
reconnectMcpServer(agentId: string, serverName: string): Promise<void>;
|
|
131
159
|
/**
|
|
132
160
|
* Create a new conversation thread for an agent.
|
|
133
161
|
* @param agentId - ID of the owning agent.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@salesforce/sfdx-agent-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -35,13 +35,13 @@
|
|
|
35
35
|
"LICENSE.txt"
|
|
36
36
|
],
|
|
37
37
|
"dependencies": {
|
|
38
|
-
"@salesforce/agentic-common": "0.
|
|
39
|
-
"@salesforce/llm-gateway-sdk": "0.
|
|
38
|
+
"@salesforce/agentic-common": "0.5.0",
|
|
39
|
+
"@salesforce/llm-gateway-sdk": "0.6.0"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"@eslint/js": "^10.0.1",
|
|
43
|
-
"@salesforce/sfdx-agent-harness-claude": "0.
|
|
44
|
-
"@salesforce/sfdx-agent-harness-mastra": "0.
|
|
43
|
+
"@salesforce/sfdx-agent-harness-claude": "0.5.0",
|
|
44
|
+
"@salesforce/sfdx-agent-harness-mastra": "0.8.0",
|
|
45
45
|
"@types/node": "^22.19.17",
|
|
46
46
|
"@vitest/coverage-istanbul": "^4.1.7",
|
|
47
47
|
"@vitest/eslint-plugin": "^1.6.17",
|