@salesforce/sfdx-agent-sdk 0.7.0 → 0.8.0

package/README.md

@@ -180,19 +180,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 +302,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 = {
@@ -417,6 +421,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 +433,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 +691,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/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/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.8.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -36,11 +36,12 @@
   ],
   "dependencies": {
     "@salesforce/agentic-common": "0.4.0",
-    "@salesforce/llm-gateway-sdk": "0.4.0"
+    "@salesforce/llm-gateway-sdk": "0.5.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-mastra": "0.6.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.4.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.7.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",