@salesforce/sfdx-agent-sdk 0.7.0 → 0.9.0

package/README.md

@@ -129,23 +129,24 @@ A configured AI agent. Factory for chat sessions. The optional `H` type paramete
 — harness-specific features are reached through `manager.extensions`, not `agent.extensions`. The default `AgentHarness`
 keeps unparameterized call sites working.
 
-| Method                 | Signature                                                                          | Description                                                            |
-| ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `getId`                | `() => string`                                                                     | Agent identifier.                                                      |
-| `getProjectRoot`       | `() => string`                                                                     | Absolute project path.                                                 |
-| `getOrgConnectionInfo` | `() => OrgConnectionInfo`                                                          | Org metadata (orgId, alias, instanceUrl, username, env).               |
-| `getAgentConfig`       | `() => AgentConfig`                                                                | Current configuration (shallow copy).                                  |
-| `getMcpServerInfo`     | `() => McpServerInfo[]`                                                            | MCP server status and discovered tools.                                |
-| `updateAgentConfig`    | `(config?: AgentConfig, options?: { abortSignal?: AbortSignal }) => Promise<void>` | Merge new config into the live agent.                                  |
-| `createChatSession`    | `() => Promise<ChatSession>`                                                       | Open a new conversation thread.                                        |
-| `getChatSession`       | `(sessionId: string) => ChatSession`                                               | Retrieve a session. Throws `AgentSDKError` (`CHAT_SESSION_NOT_FOUND`). |
-| `getChatSessionIds`    | `() => string[]`                                                                   | List active session IDs.                                               |
-| `destroyChatSession`   | `(sessionId: string) => Promise<void>`                                             | Destroy a session and its history.                                     |
-| `cloneChatSession`     | `(sourceSessionId: string) => Promise<ChatSession>`                                | Clone a session with its message history.                              |
-| `compactChatSession`   | `(sessionId: string) => Promise<ChatSession>`                                      | Compact a session into a summarized new session.                       |
-| `destroy`              | `() => Promise<void>`                                                              | Destroy the agent and all its sessions.                                |
-| `onTelemetry`          | `(callback: TelemetryEventCallback) => Unsubscribe`                                | Subscribe to telemetry scoped to this agent (and its sessions).        |
-| `onLog`                | `(callback: (record: LogRecord) => void) => Unsubscribe`                           | Subscribe to logs scoped to this agent (and its sessions).             |
+| Method                 | Signature                                                                          | Description                                                                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `getId`                | `() => string`                                                                     | Agent identifier.                                                                                                                         |
+| `getProjectRoot`       | `() => string`                                                                     | Absolute project path.                                                                                                                    |
+| `getOrgConnectionInfo` | `() => OrgConnectionInfo`                                                          | Org metadata (orgId, alias, instanceUrl, username, env).                                                                                  |
+| `getAgentConfig`       | `() => AgentConfig`                                                                | Current configuration (shallow copy).                                                                                                     |
+| `getMcpServerInfo`     | `() => McpServerInfo[]`                                                            | MCP server status and discovered tools.                                                                                                   |
+| `reconnectMcpServer`   | `(serverName: string) => Promise<void>`                                            | Recover one MCP server without recycling the agent. Semantics vary by harness — observe via `getMcpServerInfo()` and discovery telemetry. |
+| `updateAgentConfig`    | `(config?: AgentConfig, options?: { abortSignal?: AbortSignal }) => Promise<void>` | Merge new config into the live agent.                                                                                                     |
+| `createChatSession`    | `() => Promise<ChatSession>`                                                       | Open a new conversation thread.                                                                                                           |
+| `getChatSession`       | `(sessionId: string) => ChatSession`                                               | Retrieve a session. Throws `AgentSDKError` (`CHAT_SESSION_NOT_FOUND`).                                                                    |
+| `getChatSessionIds`    | `() => string[]`                                                                   | List active session IDs.                                                                                                                  |
+| `destroyChatSession`   | `(sessionId: string) => Promise<void>`                                             | Destroy a session and its history.                                                                                                        |
+| `cloneChatSession`     | `(sourceSessionId: string) => Promise<ChatSession>`                                | Clone a session with its message history.                                                                                                 |
+| `compactChatSession`   | `(sessionId: string) => Promise<ChatSession>`                                      | Compact a session into a summarized new session.                                                                                          |
+| `destroy`              | `() => Promise<void>`                                                              | Destroy the agent and all its sessions.                                                                                                   |
+| `onTelemetry`          | `(callback: TelemetryEventCallback) => Unsubscribe`                                | Subscribe to telemetry scoped to this agent (and its sessions).                                                                           |
+| `onLog`                | `(callback: (record: LogRecord) => void) => Unsubscribe`                           | Subscribe to logs scoped to this agent (and its sessions).                                                                                |
 
 ### `ChatSession`
 
@@ -180,19 +181,19 @@ Returned by `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToo
 
 Discriminated union (`event.type`) of streaming events:
 
-| Type                    | Key Fields                                     | Description                                              |
-| ----------------------- | ---------------------------------------------- | -------------------------------------------------------- |
-| `start`                 | —                                              | Stream has begun.                                        |
-| `text-delta`            | `text`                                         | Incremental response text.                               |
-| `reasoning-delta`       | `text`                                         | Chain-of-thought fragment.                               |
-| `tool-call`             | `toolCallId`, `toolName`, `args`               | Tool invocation.                                         |
-| `tool-approval-request` | `toolCall: ToolCallInfo`                       | Engine requests approval before executing a tool.        |
-| `tool-result`           | `toolCallId`, `toolName`, `result`, `isError?` | Tool execution completed.                                |
-| `step-start`            | `stepIndex`                                    | New LLM invocation step began.                           |
-| `step-finish`           | `stepIndex`, `finishReason`, `usage?`          | Step completed with per-step token usage.                |
-| `error`                 | `error`, `code?`                               | Mid-stream error (yielded, not thrown).                  |
-| `finish`                | `finishReason`, `usage?`                       | Stream completed with aggregate token usage.             |
-| `unmapped-chunk`        | `chunkType`, `rawChunk`                        | Unrecognized harness event, preserved for observability. |
+| Type                    | Key Fields                                                                    | Description                                                                                                                                                                           |
+| ----------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start`                 | —                                                                             | Stream has begun.                                                                                                                                                                     |
+| `text-delta`            | `text`                                                                        | Incremental response text.                                                                                                                                                            |
+| `reasoning-delta`       | `text`                                                                        | Chain-of-thought fragment.                                                                                                                                                            |
+| `tool-call`             | `toolCallId`, `toolName`, `args`, `annotations?`, `serverName?`               | Tool invocation. `annotations` is the MCP-spec hints (`readOnlyHint`, `destructiveHint`, …) when the source declared them; `serverName` is set when the tool came from an MCP server. |
+| `tool-approval-request` | `toolCall: ToolCallInfo`, `annotations?`, `serverName?`                       | Engine requests approval before executing a tool. Same `annotations` / `serverName` semantics as `tool-call`.                                                                         |
+| `tool-result`           | `toolCallId`, `toolName`, `result`, `isError?`, `annotations?`, `serverName?` | Tool execution completed. Same `annotations` / `serverName` semantics as `tool-call`.                                                                                                 |
+| `step-start`            | `stepIndex`                                                                   | New LLM invocation step began.                                                                                                                                                        |
+| `step-finish`           | `stepIndex`, `finishReason`, `usage?`                                         | Step completed with per-step token usage.                                                                                                                                             |
+| `error`                 | `error`, `code?`                                                              | Mid-stream error (yielded, not thrown).                                                                                                                                               |
+| `finish`                | `finishReason`, `usage?`                                                      | Stream completed with aggregate token usage.                                                                                                                                          |
+| `unmapped-chunk`        | `chunkType`, `rawChunk`                                                       | Unrecognized harness event, preserved for observability.                                                                                                                              |
 
 ### Configuration Types
 
@@ -302,6 +303,10 @@ type ToolDefinition = {
   name: string;
   description?: string;
   inputSchema: Record<string, unknown>;
+  // Optional MCP-spec UI/behavioral hints. Consumer-declared tools can carry
+  // the same hints as MCP-discovered tools and receive matching UI treatment.
+  // Example: `{ name: 'read_doc', annotations: { readOnlyHint: true } }`.
+  annotations?: McpToolAnnotations;
 };
 
 type ToolCallInfo = {
@@ -357,6 +362,8 @@ from `AgentSDKErrorType`:
 | `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.        |
 | `DISPOSED`               | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                 |
 | `INCOMPATIBLE_HARNESS`   | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
+| `MCP_SERVER_DISABLED`    | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false`                                                                                      |
+| `MCP_SERVER_NOT_FOUND`   | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config                                                                                 |
 
 ```typescript
 import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
@@ -417,6 +424,11 @@ for (const s of servers) {
 
 ### Tool Approval Flow
 
+`tool-call`, `tool-result`, and `tool-approval-request` events all carry optional `annotations` and `serverName` so
+consumers can branch on tool hints (e.g. auto-approve `readOnlyHint`) or group by originating MCP server without
+reparsing namespaced tool names. `annotations` is `undefined` when the source did not declare them (per the MCP spec);
+`serverName` is `undefined` when the tool is not from an MCP server.
+
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
   requireToolApproval: true,
@@ -424,9 +436,21 @@ const { eventStream } = await session.chat('Run the deployment', {
 
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
-    const continuation = await session.approveToolCall(event.toolCall.toolCallId);
-    for await (const e of continuation.eventStream) {
-      // process continuation
+    if (event.annotations?.readOnlyHint) {
+      // Safe read — auto-approve.
+      const continuation = await session.approveToolCall(event.toolCall.toolCallId);
+      for await (const e of continuation.eventStream) {
+        // process continuation
+      }
+    } else {
+      // Route to the user; group/label by event.serverName when set.
+      const approved = await promptUser(event);
+      const continuation = approved
+        ? await session.approveToolCall(event.toolCall.toolCallId)
+        : await session.declineToolCall(event.toolCall.toolCallId);
+      for await (const e of continuation.eventStream) {
+        // process continuation
+      }
     }
   }
 }
@@ -670,13 +694,17 @@ All variants share `{ type: <discriminant>, timestamp: Date }` plus the fields b
 | `chat-stream-started`            | `agentId`, `threadId`, `trigger` (`'chat' \| 'submit-tool-result' \| 'approve-tool-call' \| 'decline-tool-call'`) |
 | `chat-stream-completed`          | `agentId`, `threadId`, `durationMs`, `usage?`                                                                     |
 | `chat-stream-error`              | `agentId`, `threadId`, `durationMs`, `error`                                                                      |
-| `tool-execution-started`         | `agentId`, `threadId`, `toolCallId`, `toolName`                                                                   |
-| `tool-execution-completed`       | `agentId`, `threadId`, `toolCallId`, `toolName`, `durationMs`, `isError`                                          |
-| `tool-approval-requested`        | `agentId`, `threadId`, `toolCallId`, `toolName`                                                                   |
+| `tool-execution-started`         | `agentId`, `threadId`, `toolCallId`, `toolName`, `annotations?`, `serverName?`                                    |
+| `tool-execution-completed`       | `agentId`, `threadId`, `toolCallId`, `toolName`, `durationMs`, `isError`, `annotations?`, `serverName?`           |
+| `tool-approval-requested`        | `agentId`, `threadId`, `toolCallId`, `toolName`, `annotations?`, `serverName?`                                    |
 | `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()`.
 
 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/agent.d.ts

@@ -41,6 +41,27 @@ export interface Agent {
      * snapshot — status is updated asynchronously by background discovery promises.
      */
     getMcpServerInfo(): McpServerInfo[];
+    /**
+     * Request a reconnect of one MCP server on this agent without recycling
+     * any other server, custom tool, instruction, or skill. Useful for
+     * recovering a single failed MCP server without paying the full
+     * `updateAgentConfig` destroy/recreate cost.
+     *
+     * Throws if `serverName` is not configured on this agent or if the named
+     * server is disabled (`enabled: false`).
+     *
+     * **Semantics vary by harness.** Some harnesses await transport reconnect
+     * + discovery before this resolves (eager); others schedule the work and
+     * resolve as soon as the request is accepted (deferred — the actual
+     * reconnect happens on the next opportunity, typically the next stream).
+     * Consumers observe the result through {@link getMcpServerInfo} and the
+     * harness's MCP-discovery telemetry events, not the returned promise's
+     * resolution. Discovery / transport failures are reported on the
+     * per-server status, not by rejecting this promise.
+     *
+     * @param serverName - Name of the MCP server to reconnect.
+     */
+    reconnectMcpServer(serverName: string): Promise<void>;
     /**
      * Update the agent's configuration. The harness applies the changes
      * to the live agent (e.g., new instructions, tools, model).
@@ -152,6 +173,7 @@ export declare class DefaultAgent implements Agent {
      */
     getAgentConfig(): AgentConfig;
     getMcpServerInfo(): McpServerInfo[];
+    reconnectMcpServer(serverName: string): Promise<void>;
     /**
      * @requirements
      * - MUST merge the provided `config` with the internal `config` object.

package/dist/agent.js

@@ -91,6 +91,10 @@ export class DefaultAgent {
         this.assertNotDisposed();
         return this.harness.getMcpServerInfo(this.agentId);
     }
+    async reconnectMcpServer(serverName) {
+        this.assertNotDisposed();
+        await this.harness.reconnectMcpServer(this.agentId, serverName);
+    }
     /**
      * @requirements
      * - MUST merge the provided `config` with the internal `config` object.

package/dist/chat-session.js

@@ -326,6 +326,8 @@ export class DefaultChatSession {
                 threadId: this.threadId,
                 toolCallId: event.toolCallId,
                 toolName: event.toolName,
+                ...(event.annotations ? { annotations: event.annotations } : {}),
+                ...(event.serverName ? { serverName: event.serverName } : {}),
             });
         }
         else if (event.type === 'tool-result') {
@@ -342,6 +344,8 @@ export class DefaultChatSession {
                 toolName: event.toolName,
                 durationMs: this.clock.now().getTime() - start,
                 isError: event.isError === true,
+                ...(event.annotations ? { annotations: event.annotations } : {}),
+                ...(event.serverName ? { serverName: event.serverName } : {}),
             });
         }
         else if (event.type === 'tool-approval-request') {
@@ -352,6 +356,8 @@ export class DefaultChatSession {
                 threadId: this.threadId,
                 toolCallId: event.toolCall.toolCallId,
                 toolName: event.toolCall.toolName,
+                ...(event.annotations ? { annotations: event.annotations } : {}),
+                ...(event.serverName ? { serverName: event.serverName } : {}),
             });
         }
     }

package/dist/errors.d.ts

@@ -4,6 +4,8 @@ export declare const AgentSDKErrorType: {
     readonly COMPACTION_FAILED: "COMPACTION_FAILED";
     readonly DISPOSED: "DISPOSED";
     readonly INCOMPATIBLE_HARNESS: "INCOMPATIBLE_HARNESS";
+    readonly MCP_SERVER_DISABLED: "MCP_SERVER_DISABLED";
+    readonly MCP_SERVER_NOT_FOUND: "MCP_SERVER_NOT_FOUND";
     readonly NOT_SUPPORTED: "NOT_SUPPORTED";
 };
 export type AgentSDKErrorType = (typeof AgentSDKErrorType)[keyof typeof AgentSDKErrorType];

package/dist/errors.js

@@ -8,6 +8,8 @@ export const AgentSDKErrorType = {
     COMPACTION_FAILED: 'COMPACTION_FAILED',
     DISPOSED: 'DISPOSED',
     INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
+    MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED',
+    MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND',
     NOT_SUPPORTED: 'NOT_SUPPORTED',
 };
 export class AgentSDKError extends Error {

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

@@ -128,6 +128,34 @@ export interface AgentHarness {
      * @returns Info for each configured MCP server (empty array if none configured).
      */
     getMcpServerInfo(agentId: string): McpServerInfo[];
+    /**
+     * Request a reconnect of one MCP server attached to the agent without
+     * recycling any other server, custom tool, instruction, or skill.
+     *
+     * **Scheduled-minimum contract.** Implementors MUST validate the request
+     * (unknown agent id / unknown server name / disabled server reject) and
+     * MUST cause the named server to be reconnected. They MAY satisfy the
+     * reconnect eagerly (await transport reconnect + discovery before
+     * resolving) or schedule it (resolve once the request is accepted; carry
+     * out the work on the next opportunity, e.g. the next stream). Consumers
+     * observe the result via {@link getMcpServerInfo} and the harness's
+     * MCP-discovery telemetry events, not the returned promise's resolution.
+     *
+     * Implementors MUST:
+     * - throw if `agentId` is not registered.
+     * - throw if `serverName` is not configured on this agent.
+     * - throw if `serverName` is configured but disabled (`enabled: false`).
+     *
+     * Implementors MUST NOT:
+     * - reject on transient transport / discovery failure — record those on
+     *   the per-server status (visible via {@link getMcpServerInfo}).
+     * - mutate `AgentConfig` or persist anything — reconnect is a runtime
+     *   operation, not a config update.
+     *
+     * @param agentId - ID of the agent owning the server.
+     * @param serverName - Name of the MCP server to reconnect.
+     */
+    reconnectMcpServer(agentId: string, serverName: string): Promise<void>;
     /**
      * Create a new conversation thread for an agent.
      * @param agentId - ID of the owning agent.

package/dist/index.d.ts

@@ -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, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.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 { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 export { resolveMcpServerHeaders } from './mcp-auth.js';
 export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';

package/dist/types/events.d.ts

@@ -1,3 +1,4 @@
+import type { McpToolAnnotations } from '../mcp-config.js';
 import type { ToolCallInfo, ToolResultInfo } from './tools.js';
 import type { FinishReason, UsageMetadata } from './usage.js';
 /**
@@ -47,9 +48,25 @@ export type ReasoningDeltaEvent = {
  *
  * Extends {@link ToolCallInfo} with a discriminator type for use in the
  * {@link ChatEvent} discriminated union.
+ *
+ * `annotations` and `serverName` are populated by the harness when the tool is
+ * in an MCP server's catalog, mirroring the enrichment on
+ * {@link ToolApprovalRequestEvent}. They are stream-event metadata — not part
+ * of {@link ToolCallInfo} — so persisted message history (`MessagePart`s) does
+ * not carry per-stream MCP enrichment.
  */
 export type ToolCallEvent = ToolCallInfo & {
     type: 'tool-call';
+    /**
+     * Behavioral / UI-presentation hints declared for the tool. See
+     * {@link ToolApprovalRequestEvent.annotations}.
+     */
+    annotations?: McpToolAnnotations;
+    /**
+     * Originating MCP server name when the tool was discovered through an MCP
+     * server. `undefined` for consumer-declared tools or workspace tools.
+     */
+    serverName?: string;
 };
 /**
  * The harness is requesting approval before executing a tool call.
@@ -65,15 +82,42 @@ export type ToolApprovalRequestEvent = {
     type: 'tool-approval-request';
     /** The tool call awaiting approval. */
     toolCall: ToolCallInfo;
+    /**
+     * Behavioral / UI-presentation hints declared for the tool. Populated by
+     * the harness when the tool is in an MCP server's tool catalog and the
+     * server declared annotations; `undefined` when the source did not declare
+     * them (per the MCP spec) or the tool is not from an MCP server.
+     */
+    annotations?: McpToolAnnotations;
+    /**
+     * Originating MCP server name when the tool was discovered through an MCP
+     * server. `undefined` for consumer-declared tools or workspace tools that
+     * have no MCP origin.
+     */
+    serverName?: string;
 };
 /**
  * A real-time stream event indicating a tool execution has completed.
  *
  * Extends {@link ToolResultInfo} with a discriminator type for use in the
  * {@link ChatEvent} discriminated union.
+ *
+ * `annotations` and `serverName` are populated by the harness when the tool is
+ * in an MCP server's catalog, mirroring the enrichment on
+ * {@link ToolApprovalRequestEvent} and {@link ToolCallEvent}.
  */
 export type ToolResultEvent = ToolResultInfo & {
     type: 'tool-result';
+    /**
+     * Behavioral / UI-presentation hints declared for the tool. See
+     * {@link ToolApprovalRequestEvent.annotations}.
+     */
+    annotations?: McpToolAnnotations;
+    /**
+     * Originating MCP server name when the tool was discovered through an MCP
+     * server. `undefined` for consumer-declared tools or workspace tools.
+     */
+    serverName?: string;
 };
 /**
  * Marks the beginning of a new LLM invocation within a multi-step agentic loop.

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

@@ -1,4 +1,5 @@
 import type { EventBus } from '@salesforce/agentic-common';
+import type { McpServerInfo, McpToolAnnotations } from '../mcp-config.js';
 import type { UsageMetadata } from './usage.js';
 /**
  * Telemetry events emitted by the Agent SDK.
@@ -50,6 +51,10 @@ export type ToolExecutionStartedEvent = Base<'tool-execution-started'> & {
     threadId: string;
     toolCallId: string;
     toolName: string;
+    /** Annotations declared for the tool, when available. See {@link ToolApprovalRequestEvent.annotations}. */
+    annotations?: McpToolAnnotations;
+    /** Originating MCP server name, when the tool was discovered through MCP. */
+    serverName?: string;
 };
 export type ToolExecutionCompletedEvent = Base<'tool-execution-completed'> & {
     agentId: string;
@@ -58,12 +63,20 @@ export type ToolExecutionCompletedEvent = Base<'tool-execution-completed'> & {
     toolName: string;
     durationMs: number;
     isError: boolean;
+    /** Annotations declared for the tool, when available. See {@link ToolApprovalRequestEvent.annotations}. */
+    annotations?: McpToolAnnotations;
+    /** Originating MCP server name, when the tool was discovered through MCP. */
+    serverName?: string;
 };
 export type ToolApprovalRequestedEvent = Base<'tool-approval-requested'> & {
     agentId: string;
     threadId: string;
     toolCallId: string;
     toolName: string;
+    /** Annotations declared for the tool, when available. See {@link ToolApprovalRequestEvent.annotations}. */
+    annotations?: McpToolAnnotations;
+    /** Originating MCP server name, when the tool was discovered through MCP. */
+    serverName?: string;
 };
 export type ToolApprovalResolvedEvent = Base<'tool-approval-resolved'> & {
     agentId: string;
@@ -87,7 +100,21 @@ export type McpServerDiscoveryFailedEvent = Base<'mcp-server-discovery-failed'>
     durationMs: number;
     error: Error;
 };
-export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export type McpDiscoverySnapshotEvent = Base<'mcp-discovery-snapshot'> & {
+    agentId: string;
+    servers: McpServerInfo[];
+};
+export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpDiscoverySnapshotEvent;
 export type TelemetryEventCallback = (event: TelemetryEvent) => void;
 export type TelemetryBus = EventBus<TelemetryEvent>;
 export {};

package/dist/types/tools.d.ts

@@ -1,3 +1,4 @@
+import type { McpToolAnnotations } from '../mcp-config.js';
 /**
  * Declares a consumer-executed tool that an agent can invoke.
  *
@@ -24,6 +25,15 @@ export type ToolDefinition = {
      * Harnesses use this to validate arguments before execution.
      */
     inputSchema: Record<string, unknown>;
+    /**
+     * Behavioral / UI-presentation hints for this tool. Mirrors the MCP
+     * protocol's `Tool.annotations` shape so consumer-declared tools can carry
+     * the same hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
+     * `openWorldHint`, `title`) as MCP-discovered tools and receive matching
+     * UI treatment. Absence of a field means "the author did not declare this
+     * hint," not "false."
+     */
+    annotations?: McpToolAnnotations;
 };
 /**
  * Base shape for a tool call.

package/package.json

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