@salesforce/sfdx-agent-sdk 0.9.0 → 0.10.0

package/README.md

@@ -245,12 +245,27 @@ type MCPRemoteServerConfig = {
 
 #### `McpServerInfo`
 
-| Field    | Type                                                   | Description                             |
-| -------- | ------------------------------------------------------ | --------------------------------------- |
-| `name`   | `string`                                               | Server identifier.                      |
-| `status` | `'connected' \| 'connecting' \| 'disabled' \| 'error'` | Connection state.                       |
-| `tools`  | [`McpToolInfo[]`](#mcptoolinfo)                        | Discovered tools (name + metadata).     |
-| `error?` | `string`                                               | Error message when status is `'error'`. |
+| Field          | Type                                                                     | Description                                                                                                                               |
+| -------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | `string`                                                                 | Server identifier.                                                                                                                        |
+| `status`       | `'connected' \| 'connecting' \| 'disabled' \| 'error' \| 'reconnecting'` | Connection state. `'reconnecting'` is reported during an `Agent.reconnectMcpServer(name)` call against a previously-`'connected'` server. |
+| `tools`        | [`McpToolInfo[]`](#mcptoolinfo)                                          | Discovered tools (name + metadata).                                                                                                       |
+| `error?`       | `string`                                                                 | Sanitized human-readable error message when status is `'error'`. Stack frames and file paths are stripped at the harness boundary.        |
+| `errorDetail?` | [`McpServerErrorDetail`](#mcpservererrordetail)                          | Structured failure projection for programmatic routing (category / code / retriable). Populated when status is `'error'`.                 |
+
+#### `McpServerErrorDetail`
+
+Structured projection of an MCP server failure. Mirror is also attached to the `mcp-server-discovery-failed` telemetry
+event so subscribers can route on it without pattern-matching `error.message`.
+
+| Field       | Type                     | Description                                                                                                                                                                                                                 |
+| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `category`  | `McpServerErrorCategory` | Stable category for routing logic. Set is additive across minor versions — values are added but never renamed or removed.                                                                                                   |
+| `code?`     | `number`                 | JSON-RPC error code from the underlying `McpError`, when the failure originated as a JSON-RPC error. Undefined for transport-level failures and for harnesses whose underlying SDK does not surface the code (e.g. Claude). |
+| `retriable` | `boolean`                | Whether the SDK considers the failure transient (worth `Agent.reconnectMcpServer` / `Agent.refreshMcpAuth`) versus fatal.                                                                                                   |
+
+`McpServerErrorCategory` values: `'connect-timeout'`, `'http-401'`, `'http-403'`, `'http-4xx'`, `'http-5xx'`,
+`'transport-eof'`, `'protocol-error'`, `'config-error'`, `'aborted'`, `'unknown'`.
 
 #### `McpToolInfo`
 
@@ -510,6 +525,12 @@ Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod,
 
 - `ModelName` — enum of supported model identifiers
 - `SfApiEnv` — Salesforce API environment enum (`dev`, `perf`, `prod`, `stage`, `test`)
+- `inferSfApiEnv(instanceUrl, options?)` — maps an instance URL to a `SfApiEnv`. Re-exported from
+  `@salesforce/agentic-common` for consumers that need the mapping without an `OrgConnection` (e.g. building a
+  Salesforce platform MCP URL). Defaults the unrecognized-`.pc-rnd.` fallback to `SfApiEnv.Test` (`.pc-rnd.` is an
+  internal-only OrgFarm domain — not Prod by definition); pass `{ pcRndFallback: SfApiEnv.Prod }` to override. See the
+  [`@salesforce/agentic-common` README](../agentic-common/README.md#infersfapienvinstanceurl-options-sfapienv) for the
+  full resolution order.
 
 ### Telemetry & structured logs
 
@@ -700,11 +721,14 @@ All variants share `{ type: <discriminant>, timestamp: Date }` plus the fields b
 | `tool-approval-resolved`         | `agentId`, `threadId`, `toolCallId`, `approved`                                                                   |
 | `mcp-server-discovery-started`   | `agentId`, `serverName`                                                                                           |
 | `mcp-server-discovery-completed` | `agentId`, `serverName`, `toolCount`, `durationMs`                                                                |
-| `mcp-server-discovery-failed`    | `agentId`, `serverName`, `durationMs`, `error`                                                                    |
-| `mcp-discovery-snapshot`         | `agentId`, `servers` (`McpServerInfo[]`)                                                                          |
-
-`mcp-discovery-snapshot` is emitted by harnesses whose runtime exposes aggregate MCP server status (currently only the
-Claude harness, once per `init` arrival). Its `servers` payload mirrors `agent.getMcpServerInfo()`.
+| `mcp-server-discovery-failed`    | `agentId`, `serverName`, `durationMs`, `error`, `errorDetail?` ([`McpServerErrorDetail`](#mcpservererrordetail))  |
+| `mcp-server-status-changed`      | `agentId`, `serverName`, `previousStatus`, `nextStatus`, `error?`                                                 |
+
+`mcp-server-status-changed` fires on every per-server status transition — emitted in addition to the discovery trio so
+consumers can route on the `(previousStatus, nextStatus)` pair without polling `getMcpServerInfo()`. A reconnect on a
+previously-`connected` server emits, in order: `connected → reconnecting`, then on success `reconnecting → connected`,
+or on failure `reconnecting → error`. Emitted by the Mastra harness today; the Claude harness emits the discovery trio
+on the same lifecycle moments and consumers can converge on the same `getMcpServerInfo()` snapshot from either side.
 
 Every chat entry point (`chat`, `submitToolResult`, `approveToolCall`, `declineToolCall`) emits exactly one
 `chat-stream-started` followed by exactly one terminal event — either `chat-stream-completed` (natural completion) or

package/dist/chat-session.d.ts

@@ -55,15 +55,28 @@ export interface ChatSession {
      */
     chat(message: string, options?: ChatOptions): Promise<ChatStreamResult>;
     /**
-     * Feed the result of a client-side tool execution back into the conversation
-     * and resume stream generation.
+     * Feed the result of a **consumer-executed (client-side) tool** back into the
+     * conversation and resume stream generation.
      *
-     * Resumes the suspended agentic loop from the most recent `chat()` call.
+     * "Client-side tool" means a tool you declared in {@link AgentConfig.tools}
+     * without an `execute` function — the SDK registers its name + schema with the
+     * model but does not run it. When the model calls one, the chat eventStream
+     * emits a `tool-call` event and ends with `finishReason: 'tool-calls'`. Your
+     * application runs the tool however it likes (HTTP call, DB query, UI prompt,
+     * etc.) and calls this method with the result; the agent loop resumes and
+     * produces its next turn on the returned `ChatStreamResult.eventStream`.
+     *
+     * Use this method ONLY for client-side tools. Tools provided via
+     * {@link AgentConfig.mcpServers} are executed by the harness — their results
+     * flow naturally as `tool-result` events without consumer involvement.
+     * Human-in-the-loop approval of harness-executed tools uses
+     * {@link approveToolCall} / {@link declineToolCall}, not this method.
      *
      * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
      * the returned promise rejects. See the interface-level "Failure handling" notes for details.
      *
-     * @param toolResult - The completed tool execution result.
+     * @param toolResult - The completed tool execution result. `toolCallId` and
+     *   `toolName` MUST match the values from the originating `tool-call` event.
      */
     submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
     /**
@@ -151,6 +164,17 @@ export declare class DefaultChatSession implements ChatSession {
     private readonly parentUnsubs;
     private readonly clock;
     private readonly idGenerator;
+    /**
+     * Tracks the start timestamp of every in-flight `tool-call` keyed by `toolCallId`,
+     * used by `deriveToolTelemetry` to compute `tool-execution-completed.durationMs`.
+     *
+     * Lifetime is per-session (not per-stream) so a `tool-call` on the initial chat stream
+     * pairs with a `tool-result` on the approval-continuation / submit-tool-result
+     * continuation stream — those are continuations of the same logical chat turn. Cleared
+     * on every terminal `finish` ChatEvent (the turn closed cleanly; any unmatched entries
+     * are stale and should not bleed into the next turn).
+     */
+    private readonly toolStartMs;
     private disposed;
     /**
      * @param harness - The agent harness managing thread and message lifecycle.
@@ -195,8 +219,12 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST derive `tool-execution-started`, `tool-execution-completed`, and
      *   `tool-approval-requested` telemetry from the corresponding `ChatEvent` types so harness
      *   implementations don't reimplement this. `tool-execution-completed.durationMs` is measured
-     *   between the matching `tool-call` and `tool-result`; an unmatched `tool-result` (e.g. from
-     *   a resume flow that crosses a stream boundary) is skipped.
+     *   between the matching `tool-call` and `tool-result`, including across approval / resume
+     *   continuations within the same chat turn — those are continuations of one logical turn
+     *   and the tool start timestamp lives on the session, not the stream. The tracking map is
+     *   cleared on every terminal `finish` ChatEvent so stale entries from one turn never bleed
+     *   into the next. An unmatched `tool-result` (no recorded `tool-call` in the session) is
+     *   still skipped.
      *
      * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
      * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
@@ -269,9 +297,13 @@ export declare class DefaultChatSession implements ChatSession {
      * implementation free of telemetry plumbing — they just yield the right `ChatEvent` shapes.
      *
      * `tool-execution-completed.durationMs` is measured between the matching `tool-call` and
-     * `tool-result` using `this.clock`. An unmatched `tool-result` (e.g. a resume flow that
-     * crosses a stream boundary so the original `tool-call` was on a previous stream) is skipped
-     * — the consumer correlates by `toolCallId` against the earlier `tool-execution-started`.
+     * `tool-result` using `this.clock`. The tracking map (`this.toolStartMs`) lives on the
+     * session, so a `tool-call` on the initial stream pairs with a `tool-result` on the
+     * approval-continuation / submit-tool-result continuation stream — those are continuations
+     * of the same logical chat turn. The map is cleared on every terminal `finish` ChatEvent
+     * (handled by `wrapEventStream`). An unmatched `tool-result` (no recorded `tool-call`) is
+     * skipped — the consumer correlates by `toolCallId` against the earlier
+     * `tool-execution-started`.
      */
     private deriveToolTelemetry;
     /**

package/dist/chat-session.js

@@ -20,6 +20,17 @@ export class DefaultChatSession {
     parentUnsubs;
     clock;
     idGenerator;
+    /**
+     * Tracks the start timestamp of every in-flight `tool-call` keyed by `toolCallId`,
+     * used by `deriveToolTelemetry` to compute `tool-execution-completed.durationMs`.
+     *
+     * Lifetime is per-session (not per-stream) so a `tool-call` on the initial chat stream
+     * pairs with a `tool-result` on the approval-continuation / submit-tool-result
+     * continuation stream — those are continuations of the same logical chat turn. Cleared
+     * on every terminal `finish` ChatEvent (the turn closed cleanly; any unmatched entries
+     * are stale and should not bleed into the next turn).
+     */
+    toolStartMs = new Map();
     disposed = false;
     /**
      * @param harness - The agent harness managing thread and message lifecycle.
@@ -103,8 +114,12 @@ export class DefaultChatSession {
      * - MUST derive `tool-execution-started`, `tool-execution-completed`, and
      *   `tool-approval-requested` telemetry from the corresponding `ChatEvent` types so harness
      *   implementations don't reimplement this. `tool-execution-completed.durationMs` is measured
-     *   between the matching `tool-call` and `tool-result`; an unmatched `tool-result` (e.g. from
-     *   a resume flow that crosses a stream boundary) is skipped.
+     *   between the matching `tool-call` and `tool-result`, including across approval / resume
+     *   continuations within the same chat turn — those are continuations of one logical turn
+     *   and the tool start timestamp lives on the session, not the stream. The tracking map is
+     *   cleared on every terminal `finish` ChatEvent so stale entries from one turn never bleed
+     *   into the next. An unmatched `tool-result` (no recorded `tool-call` in the session) is
+     *   still skipped.
      *
      * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
      * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
@@ -112,18 +127,21 @@ export class DefaultChatSession {
      * `durationMs` measures real elapsed time on both terminal events.
      */
     async *wrapEventStream(stream, startedAt) {
-        const toolStartMs = new Map();
         let sawFinish = false;
         let lastError;
         let finishUsage;
         try {
             for await (const event of stream) {
                 this.chatEventBus.emit(event);
-                this.deriveToolTelemetry(event, toolStartMs);
+                this.deriveToolTelemetry(event);
                 yield event;
                 if (event.type === 'finish') {
                     sawFinish = true;
                     finishUsage = event.usage;
+                    // Turn boundary — clear any unmatched in-flight tool starts so a stale
+                    // entry from one turn cannot pair with an unrelated tool-result on the
+                    // next turn. Matched pairs already removed their entry in `deriveToolTelemetry`.
+                    this.toolStartMs.clear();
                 }
                 if (event.type === 'error')
                     lastError = event.error;
@@ -140,6 +158,10 @@ export class DefaultChatSession {
             const finishEvent = { type: 'finish', finishReason: 'error' };
             this.chatEventBus.emit(finishEvent);
             yield finishEvent;
+            // Match the natural-finish branch: every terminal `finish` clears the
+            // tool-start tracking map so a stale entry can't pair with an unrelated
+            // tool-result on the next turn.
+            this.toolStartMs.clear();
         }
         const finishedAt = this.clock.now();
         const durationMs = finishedAt.getTime() - startedAt.getTime();
@@ -312,13 +334,17 @@ export class DefaultChatSession {
      * implementation free of telemetry plumbing — they just yield the right `ChatEvent` shapes.
      *
      * `tool-execution-completed.durationMs` is measured between the matching `tool-call` and
-     * `tool-result` using `this.clock`. An unmatched `tool-result` (e.g. a resume flow that
-     * crosses a stream boundary so the original `tool-call` was on a previous stream) is skipped
-     * — the consumer correlates by `toolCallId` against the earlier `tool-execution-started`.
+     * `tool-result` using `this.clock`. The tracking map (`this.toolStartMs`) lives on the
+     * session, so a `tool-call` on the initial stream pairs with a `tool-result` on the
+     * approval-continuation / submit-tool-result continuation stream — those are continuations
+     * of the same logical chat turn. The map is cleared on every terminal `finish` ChatEvent
+     * (handled by `wrapEventStream`). An unmatched `tool-result` (no recorded `tool-call`) is
+     * skipped — the consumer correlates by `toolCallId` against the earlier
+     * `tool-execution-started`.
      */
-    deriveToolTelemetry(event, toolStartMs) {
+    deriveToolTelemetry(event) {
         if (event.type === 'tool-call') {
-            toolStartMs.set(event.toolCallId, this.clock.now().getTime());
+            this.toolStartMs.set(event.toolCallId, this.clock.now().getTime());
             this.telemetryBus.emit({
                 type: 'tool-execution-started',
                 timestamp: this.clock.now(),
@@ -331,10 +357,10 @@ export class DefaultChatSession {
             });
         }
         else if (event.type === 'tool-result') {
-            const start = toolStartMs.get(event.toolCallId);
+            const start = this.toolStartMs.get(event.toolCallId);
             if (start === undefined)
                 return;
-            toolStartMs.delete(event.toolCallId);
+            this.toolStartMs.delete(event.toolCallId);
             this.telemetryBus.emit({
                 type: 'tool-execution-completed',
                 timestamp: this.clock.now(),

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

@@ -208,16 +208,22 @@ export interface AgentHarness {
      */
     stream(agentId: string, threadId: string, message: string, options?: StreamOptions): Promise<ChatStreamResult>;
     /**
-     * Feed the result of a client-side tool execution back into the conversation
-     * and resume stream generation.
+     * Feed the result of a **consumer-executed (client-side) tool** back into the
+     * conversation and resume stream generation. Implements the consumer-facing
+     * {@link ChatSession.submitToolResult} contract: see that JSDoc for the
+     * full consumer-level semantics.
      *
-     * Resumes the suspended agentic loop from the most recent `stream()` call on
-     * the given thread. The harness feeds `toolResult` into the loop and returns
-     * a continuation stream.
+     * Called only for tools declared in {@link HarnessAgentConfig.tools} (no
+     * `execute` function). Tools provided via `mcpServers` are executed by the
+     * harness directly and never reach this method. The harness resumes the
+     * suspended agentic loop from the most recent `stream()` call on the given
+     * thread, feeds `toolResult` into the loop, and returns a continuation
+     * stream the consumer iterates for the model's next turn.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
-     * @param toolResult - The completed tool execution result.
+     * @param toolResult - The completed tool execution result; `toolCallId`
+     *   matches the id from the originating `tool-call` event.
      */
     submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<ChatStreamResult>;
     /**

package/dist/index.d.ts

@@ -4,10 +4,10 @@ export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools
 export type { FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
-export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
+export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus } from './mcp-config.js';
 export { ModelName } from '@salesforce/llm-gateway-sdk';
-export { SfApiEnv } from '@salesforce/agentic-common';
+export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 export { type AgentManager, type RestoreFailure, createAgentManager } from './agent-manager.js';
 export { type Agent } from './agent.js';
 export { type ChatSession, type ChatOptions } from './chat-session.js';
@@ -16,7 +16,7 @@ export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './
 export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
 export { HarnessBusOwner } from './harness/harness-bus-owner.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
-export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpDiscoverySnapshotEvent, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
+export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 export { resolveMcpServerHeaders } from './mcp-auth.js';
 export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';

package/dist/index.js

@@ -5,7 +5,7 @@
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
 export { McpServerStatus } from './mcp-config.js';
 export { ModelName } from '@salesforce/llm-gateway-sdk';
-export { SfApiEnv } from '@salesforce/agentic-common';
+export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 // ── Agent Layer ─────────────────────────────────────────────────────
 export { createAgentManager } from './agent-manager.js';
 export {} from './agent.js';

package/dist/mcp-config.d.ts

@@ -17,7 +17,18 @@ export type MCPStdioServerConfig = {
     command: string;
     /** Arguments passed to the command. */
     args?: string[];
-    /** Environment variables set when running the server process. */
+    /**
+     * Environment variables set when running the server process.
+     *
+     * **JWT rotation caveat.** These env vars are forwarded verbatim to the
+     * child process at spawn time. The MCP SDK's stdio transport has no
+     * per-request hook, so a JWT-bearing env var (e.g. `SF_ACCESS_TOKEN`)
+     * is frozen at spawn. After a JWT rotation, an stdio MCP server that
+     * depends on the env value will see a stale value until the child is
+     * respawned — call `Agent.reconnectMcpServer(name)` to refresh.
+     * Remote (HTTP) servers do not have this limitation; their auth headers
+     * are re-resolved per request through a host-side fetch hook.
+     */
     env?: Record<string, string>;
     /** Whether this server is enabled. Defaults to `true`. */
     enabled?: boolean;
@@ -41,7 +52,14 @@ export declare enum McpServerStatus {
     Connected = "connected",
     Connecting = "connecting",
     Disabled = "disabled",
-    Error = "error"
+    Error = "error",
+    /**
+     * Transport is being cycled after the server was previously `Connected` —
+     * e.g. an explicit `Agent.reconnectMcpServer(name)` call. The server stays
+     * in this state until the new transport + discovery resolves to either
+     * `Connected` (success) or `Error` (failure).
+     */
+    Reconnecting = "reconnecting"
 }
 /**
  * Behavioral / UI-presentation hints for an MCP-discovered tool.
@@ -106,10 +124,79 @@ export type McpToolInfo = {
     /** Behavioral / UI-presentation hints declared by the MCP server. */
     annotations?: McpToolAnnotations;
 };
+/**
+ * Stable category for routing logic on an MCP server failure. Consumers writing
+ * reconnect / retry / UX flows match on this instead of regexing the
+ * free-form `error` string. The set is additive across minor versions — values
+ * may be added but never removed or renamed.
+ */
+export type McpServerErrorCategory = 
+/** 3s default or configured timeout exceeded. */
+'connect-timeout'
+/** Unauthorized — JWT missing/expired. */
+ | 'http-401'
+/** Forbidden — JWT valid but the principal lacks permission. */
+ | 'http-403'
+/** Other 4xx — likely a config issue. */
+ | 'http-4xx'
+/** Server-side error — transient or fatal. */
+ | 'http-5xx'
+/** Connection closed unexpectedly. */
+ | 'transport-eof'
+/** MCP spec violation in response (JSON-RPC framing or schema). */
+ | 'protocol-error'
+/** Bad URL, bad headers, bad config. */
+ | 'config-error'
+/** Consumer-driven `AbortSignal`. */
+ | 'aborted'
+/** Could not be classified. */
+ | 'unknown';
+/**
+ * Structured projection of an MCP server failure attached to an
+ * {@link McpServerInfo} (post-discovery polling surface) or an
+ * {@link McpServerDiscoveryFailedEvent} (per-event telemetry).
+ *
+ * Replaces consumer pattern-matching against the free-form `error` string for
+ * routing decisions. The free-form string is still surfaced (sanitized — no V8
+ * stack frames or file paths) for human-readable display and logs.
+ */
+export type McpServerErrorDetail = {
+    /** Stable category for routing logic. */
+    category: McpServerErrorCategory;
+    /**
+     * JSON-RPC error code from the underlying `McpError`, when the failure
+     * originated as a JSON-RPC error. `undefined` for transport-level failures
+     * (DNS, TCP, TLS) and for harnesses whose underlying SDK does not surface
+     * the JSON-RPC code (e.g. the Claude harness).
+     *
+     * See [@modelcontextprotocol/sdk types](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
+     * (`McpError`) and the JSON-RPC 2.0
+     * [error object](https://www.jsonrpc.org/specification#error_object).
+     */
+    code?: number;
+    /**
+     * Whether the failure is transient (worth a retry via
+     * `Agent.reconnectMcpServer` / `Agent.refreshMcpAuth`) vs fatal (consumer
+     * must fix config). Harness implementations populate this with their best
+     * heuristic; consumers may override per-category.
+     */
+    retriable: boolean;
+};
 /** Runtime status of a configured MCP server, including its discovered tools. */
 export type McpServerInfo = {
     name: string;
     status: McpServerStatus;
     tools: McpToolInfo[];
+    /**
+     * Human-readable error string. Sanitized at the harness boundary — no V8
+     * stack frames, no file paths, no internal class names. Safe for UI
+     * display and telemetry tags. For programmatic routing, prefer
+     * {@link errorDetail}.
+     */
     error?: string;
+    /**
+     * Structured failure projection. Populated by the harness when `status` is
+     * `Error`; absent otherwise. See {@link McpServerErrorDetail}.
+     */
+    errorDetail?: McpServerErrorDetail;
 };

package/dist/mcp-config.js

@@ -9,5 +9,12 @@ export var McpServerStatus;
     McpServerStatus["Connecting"] = "connecting";
     McpServerStatus["Disabled"] = "disabled";
     McpServerStatus["Error"] = "error";
+    /**
+     * Transport is being cycled after the server was previously `Connected` —
+     * e.g. an explicit `Agent.reconnectMcpServer(name)` call. The server stays
+     * in this state until the new transport + discovery resolves to either
+     * `Connected` (success) or `Error` (failure).
+     */
+    McpServerStatus["Reconnecting"] = "reconnecting";
 })(McpServerStatus || (McpServerStatus = {}));
 //# sourceMappingURL=mcp-config.js.map

package/dist/types/telemetry-events.d.ts

@@ -1,5 +1,5 @@
 import type { EventBus } from '@salesforce/agentic-common';
-import type { McpServerInfo, McpToolAnnotations } from '../mcp-config.js';
+import type { McpServerErrorDetail, McpServerStatus, McpToolAnnotations } from '../mcp-config.js';
 import type { UsageMetadata } from './usage.js';
 /**
  * Telemetry events emitted by the Agent SDK.
@@ -99,22 +99,41 @@ export type McpServerDiscoveryFailedEvent = Base<'mcp-server-discovery-failed'>
     serverName: string;
     durationMs: number;
     error: Error;
+    /**
+     * Structured failure projection. Mirrors `McpServerInfo.errorDetail` so
+     * subscribers can route on category / code / retriable without
+     * pattern-matching `error.message`. Populated by harnesses that classify
+     * MCP failures.
+     */
+    errorDetail?: McpServerErrorDetail;
 };
 /**
- * Whole-snapshot MCP discovery event emitted by harnesses whose underlying SDK
- * surfaces MCP status in a single aggregate message rather than as per-server
- * lifecycle events. Currently emitted by the Claude harness on each
- * `SDKSystemMessage init` arrival.
+ * Per-transition MCP transport-state event emitted whenever a server's
+ * `McpServerStatus` changes. Consumers that need to react to specific
+ * transitions filter on the `(previousStatus, nextStatus)` pair.
  *
- * The `servers` payload mirrors the result of `harness.getMcpServerInfo(agentId)`
- * at the moment of the snapshot, so consumers can read status + tools without
- * a follow-up call.
+ * Emitted in addition to `mcp-server-discovery-{started,completed,failed}` —
+ * the discovery trio reports work boundaries (start/end of a discovery run)
+ * while this event reports the status the server is now in. A reconnect on a
+ * `Connected` server emits, in order:
+ * `Connected → Reconnecting` (transport is being cycled),
+ * then on success `Reconnecting → Connected`, or on failure
+ * `Reconnecting → Error`.
+ *
+ * Emitted by the Mastra harness today. The Claude harness emits it through
+ * the per-server discovery telemetry triple (started → completed/failed) but
+ * not as a standalone transition event — both harnesses converge on the same
+ * `McpServerInfo[]` shape via `getMcpServerInfo()`.
  */
-export type McpDiscoverySnapshotEvent = Base<'mcp-discovery-snapshot'> & {
+export type McpServerStatusChangedEvent = Base<'mcp-server-status-changed'> & {
     agentId: string;
-    servers: McpServerInfo[];
+    serverName: string;
+    previousStatus: McpServerStatus;
+    nextStatus: McpServerStatus;
+    /** Populated when `nextStatus === 'error'`. */
+    error?: string;
 };
-export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpDiscoverySnapshotEvent;
+export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent;
 export type TelemetryEventCallback = (event: TelemetryEvent) => void;
 export type TelemetryBus = EventBus<TelemetryEvent>;
 export {};

package/dist/types/tools.d.ts

@@ -1,17 +1,28 @@
 import type { McpToolAnnotations } from '../mcp-config.js';
 /**
- * Declares a consumer-executed tool that an agent can invoke.
+ * Declares a **consumer-executed (client-side) tool** that an agent can invoke.
  *
  * Tools declared here are schema-only: the harness registers the name,
  * description, and input schema with the model so it can generate tool-call
  * chunks, but the harness never executes these tools itself. When the model
  * calls one, the stream ends with `finishReason: 'tool-calls'` and the
  * consumer is responsible for running the tool locally and feeding the result
- * back via `ChatSession.submitToolResult()`.
+ * back via {@link ChatSession.submitToolResult}.
+ *
+ * Typical flow:
+ *   1. Pass `{ tools: [{ name, description, inputSchema }] }` in `AgentConfig`.
+ *   2. Iterate `eventStream` from `session.chat(...)`; capture the `tool-call`
+ *      event for one of your declared tools.
+ *   3. Run the tool locally (HTTP call, DB query, UI prompt — anything).
+ *   4. Call `session.submitToolResult({ toolCallId, toolName, result, isError })`
+ *      with the same `toolCallId` from the event. Iterate the returned
+ *      `ChatStreamResult.eventStream` for the model's next turn.
  *
  * For harness-executed (native) tools such as MCP tools, use
- * `AgentConfig.mcpServers`. To gate native tool calls with human approval,
- * use `StreamOptions.requireToolApproval`.
+ * `AgentConfig.mcpServers` — those run in the harness and never need
+ * `submitToolResult`. To gate harness-executed tool calls with human approval,
+ * use `StreamOptions.requireToolApproval` plus `approveToolCall` /
+ * `declineToolCall`.
  *
  * Structurally compatible with AI SDK `LanguageModelV4FunctionTool`.
  */
@@ -53,15 +64,26 @@ export type ToolCallInfo = {
 /**
  * Base shape for a tool result.
  *
- * Extended by {@link ToolResultPart} (message content) and {@link ToolResultEvent} (stream event).
+ * Used by {@link ChatSession.submitToolResult} to feed a consumer-executed tool's
+ * output back into the agent loop. Extended by {@link ToolResultPart} (message
+ * content) and {@link ToolResultEvent} (stream event).
+ *
+ * `toolCallId` and `toolName` MUST match the values from the originating
+ * `tool-call` event the consumer observed on the chat eventStream — that's how
+ * the harness pairs the result with the suspended call.
  */
 export type ToolResultInfo = {
     /** Identifier linking this result to the originating tool call. */
     toolCallId: string;
     /** Name of the tool that produced this result. */
     toolName: string;
-    /** The tool's output value. */
+    /** The tool's output value. Pass through whatever your tool produced. */
     result: unknown;
-    /** Whether the tool execution resulted in an error. */
+    /**
+     * Set to `true` to signal that the tool execution failed. The model
+     * receives a structured error and can recover (apologize, retry with
+     * different args, ask the user, etc.) rather than seeing the failure as
+     * the SDK or harness crashing.
+     */
     isError?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -35,13 +35,13 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.5.0",
-    "@salesforce/llm-gateway-sdk": "0.6.0"
+    "@salesforce/agentic-common": "0.6.0",
+    "@salesforce/llm-gateway-sdk": "0.7.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.5.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.8.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.6.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.9.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",