@salesforce/sfdx-agent-sdk 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.41.0] - 2026-08-03
+
+### Features
+- **agent-sdk,harnesses**: emit Tier-1 logBus siblings for lifecycle telemetry @W-23547150@ ([#716](https://github.com/forcedotcom/agentic-dx/pull/716))
+
+## [0.40.0] - 2026-08-03
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: observability gaps — mcp-tool-call-completed, llm-retry, responseText/TTFT @W-23528008@ ([#717](https://github.com/forcedotcom/agentic-dx/pull/717))
+
 ## [0.39.0] - 2026-07-30
 
 ### Features

package/README.md

@@ -1192,6 +1192,9 @@ const unsubscribe = manager.onWireCommunication((event) => {
     case 'llm-response':
       // matching response (or terminal failure)
       break;
+    case 'mcp-tool-call-completed':
+      // completed MCP tool call; redact args/result before persisting
+      break;
     case 'wire-monitoring-not-supported':
       // harness can't emit per-call events for this stream;
       // event.message points at the workaround (typically a debug log file path)
@@ -1200,17 +1203,28 @@ const unsubscribe = manager.onWireCommunication((event) => {
 });
 ```
 
-**Discriminated union — three variants keyed on `type`:**
+**Discriminated union — four variants keyed on `type`:**
+
+| `type`                          | Fields                                                                                                                                                                                                                                    |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `llm-request`                   | `timestamp`, `url`, `method`, `model`, `correlationId?`, `xClientTraceId?`, `body?`                                                                                                                                                       |
+| `llm-response`                  | `timestamp`, `model`, `correlationId?`, `status`, `xClientTraceId?`, `totalDurationMs?`, `timeToFirstTokenMs?`, `usage?` (`inputTokens?`, `outputTokens?`, `totalTokens?`, `reasoningTokens?`), `responseText?`, `error?` ({ `message` }) |
+| `mcp-tool-call-completed`       | `timestamp`, `serverName`, `toolName`, `bareToolName`, `args`, `result`, `durationMs?`                                                                                                                                                    |
+| `wire-monitoring-not-supported` | `timestamp`, `harnessId`, `message` (free-form text — typically explains why direct wire monitoring isn't available and points at a fallback log file the harness wrote)                                                                  |
 
-| `type`                          | Fields                                                                                                                                                                                                                  |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `llm-request`                   | `timestamp`, `url`, `method`, `model`, `body?`                                                                                                                                                                          |
-| `llm-response`                  | `timestamp`, `model`, `status`, `xClientTraceId?`, `totalDurationMs?`, `timeToFirstTokenMs?`, `usage?` (`inputTokens?`, `outputTokens?`, `totalTokens?`, `reasoningTokens?`), `responseText?`, `error?` ({ `message` }) |
-| `wire-monitoring-not-supported` | `timestamp`, `harnessId`, `message` (free-form text — typically explains why direct wire monitoring isn't available and points at a fallback log file the harness wrote)                                                |
+`correlationId` is the harness-guaranteed pairing key stamped identically on a matching `llm-request` / `llm-response`
+pair. Pair requests and responses on it, **not** on their positions in the event stream. `xClientTraceId` is an optional
+header value for cross-checking, not the pairing contract.
 
-**Privacy contract.** Events MAY contain user prompts, tool arguments, and model output in the `body` field. They are
-**not** flowed to the structured-log channel by default — consumers opt in to wire-level visibility explicitly via
-`onWireCommunication`. Apply your own redaction / scrubbing before persisting or sharing. Note that request HTTP headers
+`mcp-tool-call-completed` is a **DEBUG-ONLY** diagnostic event: it is opt-in and subscriber-gated like the rest of this
+channel, is never a `TelemetryEvent`, and is never shipped through telemetry or other externally-shipped event surfaces.
+Its `args` and `result` are captured verbatim and MAY contain PII. Apply your own redaction / scrubbing before
+persisting or sharing. `durationMs` is harness-specific: Claude reports RPC latency, while Mastra and OpenAI report an
+adapter-observed window. Do not compare `durationMs` across harnesses.
+
+**Privacy contract.** LLM events MAY contain user prompts and model output in `body` / `responseText`; MCP completion
+events MAY contain PII in verbatim `args` / `result`. These events are **not** flowed to the structured-log channel by
+default — consumers opt in to wire-level visibility explicitly via `onWireCommunication`. Note that request HTTP headers
 (e.g. `Authorization`) are **not** captured on the events; the harness's fetch wrapper sees them but doesn't forward
 them onto the channel.
 
@@ -1221,17 +1235,26 @@ harness in particular skips writing the subprocess's debug log when nobody is li
 `chat()` you want to inspect: subscriptions added mid-stream miss the in-flight subprocess on Claude (the listener count
 is captured at stream-start).
 
-**Cross-harness coverage.**
+#### Cross-harness coverage
+
+This table is the canonical compatibility reference for the SDK's public observability and wire-diagnostic surfaces.
+Feature availability is intentionally asymmetric where a runtime does not expose a faithful observation seam.
 
-- **Mastra harness**: emits one `llm-request` + one `llm-response` per outbound HTTP call to the LLM provider (every
-  provider — Bedrock-Anthropic, direct Anthropic, OpenAI Responses, OpenAI Chat Completions). The body is captured from
-  the in-process fetch wrapper.
-- **Claude harness**: cannot emit per-call events because the Claude Agent SDK runs the model client in a subprocess
-  with no programmatic HTTP-interception seam. Instead, when at least one consumer is subscribed at stream-start, the
-  harness writes the subprocess's debug log to `${storageRoot}/claude-debug-logs/${agentId}__${threadId}.log` (one file
-  per thread; turns of the same conversation accumulate, separated by greppable `# Turn started: <ISO>` banners) and
-  emits a single `wire-monitoring-not-supported` event whose `message` field embeds the file path. The file is left in
-  place; the consumer is responsible for retention and cleanup.
+| Feature                                                   | Claude                                                                                                                                                                                              | Mastra                                                                                                                                                                       | OpenAI                                                                                                                                                                       |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Structured `llm-request` / `llm-response` wire events     | **Not implemented.** The opaque native subprocess provides no capturable, parseable per-call format. When subscribed, emits `wire-monitoring-not-supported` and writes a subprocess debug-log file. | **Delivered.** Emits one request/response pair per outbound LLM HTTP call.                                                                                                   | **Delivered.** Emits one request/response pair per outbound LLM HTTP call.                                                                                                   |
+| Pairing structured LLM events                             | N/A — no structured LLM wire events.                                                                                                                                                                | **Delivered.** Matching request/response events share a harness-generated `correlationId`; pair on it, never event position or `xClientTraceId` alone.                       | **Delivered.** Matching request/response events share a harness-generated `correlationId`; pair on it, never event position or `xClientTraceId` alone.                       |
+| `responseText` and `timeToFirstTokenMs` on `llm-response` | N/A — no structured LLM wire events.                                                                                                                                                                | **Delivered.** A streaming-body tee produces one HTTP-body-terminal response event with best-effort response text and first-token latency.                                   | **Delivered.** A streaming-body tee produces one HTTP-body-terminal response event with best-effort response text and first-token latency.                                   |
+| `mcp-tool-call-completed` debug event                     | **Delivered.** External-MCP bridge observation with true RPC latency in `durationMs`.                                                                                                               | **Delivered.** Adapter/coordinator-observed `durationMs`, which can include a model round-trip.                                                                              | **Delivered.** Adapter/coordinator-observed `durationMs`, which can include a model round-trip.                                                                              |
+| `llm-retry` telemetry                                     | **Delivered.** Emits numeric-only, PII-free data when the Claude Agent SDK reports an actual `api_retry`.                                                                                           | **Documented limitation:** does not emit; the stateless fetch layer has no retry loop or attempt counter. A `429` / `retry-after` response is a failed attempt, not a retry. | **Documented limitation:** does not emit; the stateless fetch layer has no retry loop or attempt counter. A `429` / `retry-after` response is a failed attempt, not a retry. |
+
+Claude's debug log is written to `${storageRoot}/claude-debug-logs/${agentId}__${threadId}.log` when at least one
+consumer is subscribed at stream-start (one file per thread; turns of the same conversation accumulate, separated by
+greppable `# Turn started: <ISO>` banners). It is left in place; the consumer is responsible for retention and cleanup.
+
+Mastra and OpenAI callers can identify any upstream-retried requests only as distinct `llm-request` / `llm-response`
+pairs, using `correlationId`, `xClientTraceId`, and timestamps. Neither harness synthesizes a partial `llm-retry` event
+from an HTTP response header.
 
 #### `WireCommunicationFileWriter`
 
@@ -1253,11 +1276,11 @@ const writer = new WireCommunicationFileWriter(manager, {
 writer.detach();
 ```
 
-The output file is plain Markdown with one `### <iso-timestamp> [llm-request]`, `[llm-response]`, or
-`[wire-monitoring-not-supported]` header per event followed by the populated fields. Optional fields are emitted only
-when set — sparse responses do not pad the file with empty `**Field**: N/A` lines. On the Claude harness, the
-`wire-monitoring-not-supported` block links to the per-thread debug log file where raw wire detail can be inspected
-directly.
+The output file is plain Markdown with one `### <iso-timestamp> [llm-request]`, `[llm-response]`,
+`[mcp-tool-call-completed]`, or `[wire-monitoring-not-supported]` header per event followed by the populated fields.
+Optional fields are emitted only when set — sparse responses do not pad the file with empty `**Field**: N/A` lines. On
+the Claude harness, the `wire-monitoring-not-supported` block links to the per-thread debug log file where raw wire
+detail can be inspected directly.
 
 The same privacy contract applies: the resulting file may contain prompts, tool arguments, and model output. Treat it as
 sensitive and apply your own retention / scrubbing rules before sharing.
@@ -1491,6 +1514,7 @@ All variants share `{ type: <discriminant>, timestamp: Date }` plus the fields b
 | `mcp-server-discovery-completed` | `agentId`, `serverName`, `toolCount`, `durationMs`                                                                |
 | `mcp-server-discovery-failed`    | `agentId`, `serverName`, `durationMs`, `error`, `errorDetail?` ([`McpServerErrorDetail`](#mcpservererrordetail))  |
 | `mcp-server-status-changed`      | `agentId`, `serverName`, `previousStatus`, `nextStatus`, `error?`                                                 |
+| `llm-retry`                      | `attempt`, `maxRetries`, `retryDelayMs`, `errorStatus?` — Claude-only; numeric-only and PII-free                  |
 
 Each variant is also exported as a named type so consumers can write narrowed handlers: `AgentCreatedEvent`,
 `AgentDestroyedEvent`, `SessionCreatedEvent`, `SessionDestroyedEvent`, `ChatStreamStartedEvent`,
@@ -1522,6 +1546,13 @@ Abandoning the iterator mid-stream emits no terminal telemetry — the stream di
 Harness implementations may emit additional structured logs through their own `LogBus`. Those records surface to
 consumers via the same `onLog` channel.
 
+Selected lifecycle moments are reported on **both** channels: the typed telemetry event, plus a log record carrying the
+same facts for log sinks. On those records `message` is human-readable prose intended for display and may be reworded;
+`context.event_type` carries the matching `TelemetryEvent` type and is the stable field to filter, alert, and join on.
+Records paired this way today are `agent-created`, `agent-destroyed`, `session-created`, `session-destroyed`,
+`chat-stream-completed`, `chat-stream-error`, `tool-execution-completed` (only when `isError` is true), and the harness
+MCP events `mcp-server-discovery-completed`, `mcp-server-discovery-failed`, and `mcp-server-status-changed`.
+
 ## Development
 
 See [DEVELOPING.md](DEVELOPING.md) for build-from-source setup, scripts, E2E testing, and packaging.

package/dist/agent-manager.js

@@ -189,12 +189,20 @@ export class DefaultAgentManager {
         this.wireRouter.registerAgent(agentId);
         const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.modelConnectivityInfo, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.harnessSupportedProviderHints, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
+        const agentCreatedAt = this.clock.now();
+        const modelName = runtime.modelConnectivityInfo.model.name;
         this.telemetryBus.emit({
             type: 'agent-created',
-            timestamp: this.clock.now(),
+            timestamp: agentCreatedAt,
             agentId,
             projectRoot,
-            modelName: runtime.modelConnectivityInfo.model.name,
+            modelName,
+        });
+        this.logBus.emit({
+            level: 'info',
+            message: 'Agent created',
+            timestamp: agentCreatedAt,
+            context: { event_type: 'agent-created', agentId, projectRoot, modelName },
         });
         if (options.rehydrateThreads) {
             // If thread enumeration or session attachment fails, the restore is a full failure

package/dist/agent.js

@@ -283,11 +283,18 @@ export class DefaultAgent {
         }
         this.sessions.clear();
         await this.harness.destroyAgent(this.agentId);
+        const agentDestroyedAt = this.clock.now();
         this.telemetryBus.emit({
             type: 'agent-destroyed',
-            timestamp: this.clock.now(),
+            timestamp: agentDestroyedAt,
             agentId: this.agentId,
         });
+        this.logBus.emit({
+            level: 'info',
+            message: 'Agent destroyed',
+            timestamp: agentDestroyedAt,
+            context: { event_type: 'agent-destroyed', agentId: this.agentId },
+        });
         for (const unsub of this.inboundUnsubs)
             unsub();
         for (const unsub of this.parentUnsubs)
@@ -347,12 +354,19 @@ export class DefaultAgent {
         }, getContextWindow, { clock: this.clock, idGenerator: this.idGenerator, persistRememberedRule });
         this.sessions.set(threadId, session);
         this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
+        const sessionCreatedAt = this.clock.now();
         this.telemetryBus.emit({
             type: 'session-created',
-            timestamp: this.clock.now(),
+            timestamp: sessionCreatedAt,
             agentId: this.agentId,
             threadId,
         });
+        this.logBus.emit({
+            level: 'info',
+            message: 'Chat session created',
+            timestamp: sessionCreatedAt,
+            context: { event_type: 'session-created', agentId: this.agentId, threadId },
+        });
         return session;
     }
     detachSession(threadId, session) {

package/dist/chat-session.js

@@ -237,6 +237,18 @@ export class DefaultChatSession {
                 durationMs,
                 error: lastError,
             });
+            this.logBus.emit({
+                level: 'error',
+                message: 'Chat stream failed',
+                timestamp: finishedAt,
+                context: {
+                    event_type: 'chat-stream-error',
+                    agentId: this.agentId,
+                    threadId: this.threadId,
+                    durationMs,
+                },
+                error: lastError,
+            });
         }
         else {
             this.telemetryBus.emit({
@@ -247,6 +259,18 @@ export class DefaultChatSession {
                 durationMs,
                 usage: finishUsage,
             });
+            this.logBus.emit({
+                level: 'info',
+                message: 'Chat stream completed',
+                timestamp: finishedAt,
+                context: {
+                    event_type: 'chat-stream-completed',
+                    agentId: this.agentId,
+                    threadId: this.threadId,
+                    durationMs,
+                    ...(finishUsage !== undefined ? { usage: finishUsage } : {}),
+                },
+            });
         }
     }
     /**
@@ -420,12 +444,23 @@ export class DefaultChatSession {
         if (this.disposed) {
             return;
         }
+        const sessionDestroyedAt = this.clock.now();
         this.telemetryBus.emit({
             type: 'session-destroyed',
-            timestamp: this.clock.now(),
+            timestamp: sessionDestroyedAt,
             agentId: this.agentId,
             threadId: this.threadId,
         });
+        this.logBus.emit({
+            level: 'info',
+            message: 'Chat session destroyed',
+            timestamp: sessionDestroyedAt,
+            context: {
+                event_type: 'session-destroyed',
+                agentId: this.agentId,
+                threadId: this.threadId,
+            },
+        });
         for (const unsub of this.inboundUnsubs)
             unsub();
         for (const unsub of this.parentUnsubs)
@@ -436,6 +471,8 @@ export class DefaultChatSession {
         this.disposed = true;
     }
     emitToolApprovalResolved(toolCallId, approved, policyWritten) {
+        // No Tier-1 logBus sibling: tool-approval-resolved fires per gated
+        // tool call — interactive-UI signal, not on-call triage
         this.telemetryBus.emit({
             type: 'tool-approval-resolved',
             timestamp: this.clock.now(),
@@ -476,6 +513,8 @@ export class DefaultChatSession {
     deriveToolTelemetry(event) {
         if (event.type === 'tool-call') {
             this.toolStartMs.set(event.toolCallId, this.clock.now().getTime());
+            // No Tier-1 logBus sibling: tool-execution-started pairs 1:1 with
+            // tool-execution-completed; the completion (isError=true) is the triage signal
             this.telemetryBus.emit({
                 type: 'tool-execution-started',
                 timestamp: this.clock.now(),
@@ -492,19 +531,42 @@ export class DefaultChatSession {
             if (start === undefined)
                 return;
             this.toolStartMs.delete(event.toolCallId);
+            const completedAt = this.clock.now();
+            const durationMs = completedAt.getTime() - start;
+            const isError = event.isError === true;
             this.telemetryBus.emit({
                 type: 'tool-execution-completed',
-                timestamp: this.clock.now(),
+                timestamp: completedAt,
                 agentId: this.agentId,
                 threadId: this.threadId,
                 toolCallId: event.toolCallId,
                 toolName: event.toolName,
-                durationMs: this.clock.now().getTime() - start,
-                isError: event.isError === true,
+                durationMs,
+                isError,
                 ...(event.error ? { error: event.error } : {}),
                 ...(event.annotations ? { annotations: event.annotations } : {}),
                 ...(event.serverName ? { serverName: event.serverName } : {}),
             });
+            // Tier-1 logBus sibling only when isError=true.
+            if (isError) {
+                this.logBus.emit({
+                    level: 'error',
+                    message: 'Tool execution failed',
+                    timestamp: completedAt,
+                    context: {
+                        event_type: 'tool-execution-completed',
+                        agentId: this.agentId,
+                        threadId: this.threadId,
+                        toolCallId: event.toolCallId,
+                        toolName: event.toolName,
+                        durationMs,
+                        isError: true,
+                        ...(event.annotations ? { annotations: event.annotations } : {}),
+                        ...(event.serverName ? { serverName: event.serverName } : {}),
+                    },
+                    ...(event.error ? { error: event.error } : {}),
+                });
+            }
         }
         else if (event.type === 'tool-approval-request') {
             // Record the (toolName, serverName?) so a later settle with
@@ -574,6 +636,7 @@ export class DefaultChatSession {
      */
     emitChatStreamStarted(trigger) {
         const startedAt = this.clock.now();
+        // chat-stream-started pairs 1:1 with chat-stream-completed, which already carries outcomes
         this.telemetryBus.emit({
             type: 'chat-stream-started',
             timestamp: startedAt,
@@ -597,12 +660,25 @@ export class DefaultChatSession {
         this.chatEventBus.emit({ type: 'error', error });
         this.chatEventBus.emit({ type: 'finish', finishReason: 'error' });
         const finishedAt = this.clock.now();
+        const durationMs = finishedAt.getTime() - startedAt.getTime();
         this.telemetryBus.emit({
             type: 'chat-stream-error',
             timestamp: finishedAt,
             agentId: this.agentId,
             threadId: this.threadId,
-            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            durationMs,
+            error,
+        });
+        this.logBus.emit({
+            level: 'error',
+            message: 'Chat stream failed',
+            timestamp: finishedAt,
+            context: {
+                event_type: 'chat-stream-error',
+                agentId: this.agentId,
+                threadId: this.threadId,
+                durationMs,
+            },
             error,
         });
     }

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

@@ -100,11 +100,14 @@ export interface AgentHarness {
      *
      * Fidelity may differ between harnesses: the Mastra (in-process) path
      * emits one `request` + one `response` event per outbound HTTP call,
-     * with the full body and status visible. The Claude (subprocess) path
-     * has the seam wired but does not emit yet — emission would parse
-     * `ANTHROPIC_LOG=debug` stderr from the CLI. Consumers subscribe once
-     * at the `AgentManager` layer; the SDK forwards events upward through
-     * the bus hierarchy the same way it does for telemetry and log records.
+     * with the full body and status visible. The Claude path runs the model
+     * client in an opaque native subprocess with no capturable, parseable
+     * per-call debug format, so it emits `wire-monitoring-not-supported`
+     * pointing at the subprocess debug-log file rather than structured
+     * `llm-request` / `llm-response` events. Structured parsing is deferred
+     * pending a stable, capturable debug format. Consumers subscribe once at
+     * the `AgentManager` layer; the SDK forwards events upward through the
+     * bus hierarchy the same way it does for telemetry and log records.
      */
     onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
     /**

package/dist/index.d.ts

@@ -19,11 +19,11 @@ export { type ChatSession, type ChatOptions } from './chat-session.js';
 export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-connectivity-resolver.js';
 export { ApiKeyConnectivityResolver, type ApiKeyConnectivityResolverConfig } from './api-key-connectivity-resolver.js';
 export type { ModelConnectivityInfo, ProviderHint } from './types/model-connectivity-info.js';
-export type { LlmRequestEvent, LlmResponseEvent, WireCommunicationEvent, WireCommunicationEventCallback, WireMonitoringNotSupportedEvent, } from './types/wire-communication-event.js';
+export type { LlmRequestEvent, LlmResponseEvent, McpToolCallCompletedEvent, WireCommunicationEvent, WireCommunicationEventCallback, WireMonitoringNotSupportedEvent, } from './types/wire-communication-event.js';
 export { WireCommunicationFileWriter, type WireCommunicationEmitter, type WireCommunicationFileWriterOptions, } from './wire-communication-file-writer.js';
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
-export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalPolicyResolvedEvent, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
+export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, LlmRetryEvent, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalPolicyResolvedEvent, 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/internal/telemetry-router.js

@@ -91,10 +91,12 @@ export class TelemetryRouter {
                 return;
             }
         }
-        const agentSlice = this.agentSlices.get(event.agentId);
-        if (agentSlice) {
-            agentSlice.telemetry.emit(event);
-            return;
+        if ('agentId' in event) {
+            const agentSlice = this.agentSlices.get(event.agentId);
+            if (agentSlice) {
+                agentSlice.telemetry.emit(event);
+                return;
+            }
         }
         this.unroutedSlice.telemetry.emit(event);
     }

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

@@ -178,7 +178,21 @@ export type McpServerStatusChangedEvent = Base<'mcp-server-status-changed'> & {
     /** Populated when `nextStatus === 'error'`. */
     error?: string;
 };
-export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | ToolApprovalPolicyResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent;
+/**
+ * Emitted for each retry attempt initiated by the Claude harness.
+ *
+ * This event is Claude-only by contract: Mastra and OpenAI expose no observable
+ * attempt counter. The type has no harness discriminant, but only the Claude
+ * harness emits it. Its required retry fields intentionally remain complete so
+ * consumers never receive a partial retry record.
+ */
+export type LlmRetryEvent = Base<'llm-retry'> & {
+    attempt: number;
+    maxRetries: number;
+    retryDelayMs: number;
+    errorStatus?: number;
+};
+export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | ToolApprovalPolicyResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent | LlmRetryEvent;
 export type TelemetryEventCallback = (event: TelemetryEvent) => void;
 export type TelemetryBus = EventBus<TelemetryEvent>;
 export {};

package/dist/types/wire-communication-event.d.ts

@@ -1,7 +1,7 @@
 import type { UsageMetadata } from './usage.js';
 /**
  * Wire-level communication events, emitted by the harness layer so consumers
- * see the same shape regardless of harness. The union has three members today:
+ * see the same shape regardless of harness. The union has four members today:
  *   - `LlmRequestEvent` (`type: 'llm-request'`) — one outbound HTTP request to
  *     the LLM provider.
  *   - `LlmResponseEvent` (`type: 'llm-response'`) — the matching inbound
@@ -12,6 +12,8 @@ import type { UsageMetadata } from './usage.js';
  *     subprocess owns the HTTP traffic). The event carries a free-form
  *     `message` explaining the situation and (when applicable) where the
  *     underlying data was written instead.
+ *   - `McpToolCallCompletedEvent` (`type: 'mcp-tool-call-completed'`) — an
+ *     opt-in debug record of an MCP tool call's completed input and output.
  *
  * **Privacy contract.** Wire-communication events may contain user prompts,
  * tool arguments, model output, and other PII. They are opt-in (subscribed
@@ -55,6 +57,18 @@ export type LlmRequestEvent = {
     method: string;
     /** Native model id sent on the wire (per `ModelConnectivityInfo.nativeModelId`). */
     model: string;
+    /**
+     * Harness-generated per-fetch pairing key. Stamped identically on the matching
+     * `LlmResponseEvent`; consumers MUST use it as the reliable pairing key rather
+     * than positional event ordering. Producers obtain it from the injected
+     * `UniqueIDGenerator` in `@salesforce/agentic-common`, never `randomUUID()`.
+     */
+    correlationId?: string;
+    /**
+     * `x-client-trace-id` header value attached to this request. Consumers pair on
+     * `correlationId` (the harness-guaranteed key) and may cross-check this value.
+     */
+    xClientTraceId?: string;
     /** Request body. Best-effort: partial / absent on harnesses that can't observe it. */
     body?: Record<string, unknown>;
 };
@@ -65,6 +79,13 @@ export type LlmResponseEvent = {
     timestamp: Date;
     /** Native model id from the matching request. */
     model: string;
+    /**
+     * Harness-generated per-fetch pairing key. Stamped identically on the matching
+     * `LlmRequestEvent`; consumers MUST use it as the reliable pairing key rather
+     * than positional event ordering. Producers obtain it from the injected
+     * `UniqueIDGenerator` in `@salesforce/agentic-common`, never `randomUUID()`.
+     */
+    correlationId?: string;
     /** HTTP status code; `0` for harness-internal terminal failures with no transport response. */
     status: number;
     /** Error captured from a transport / parse failure, if any. */
@@ -85,9 +106,42 @@ export type LlmResponseEvent = {
     totalDurationMs?: number;
     /** Best-effort extracted response text (may be omitted by the harness). */
     responseText?: string;
-    /** `x-client-trace-id` header value the SDK / harness attached to the request. */
+    /**
+     * `x-client-trace-id` header value attached to the matching request. Consumers
+     * pair on `correlationId` (the harness-guaranteed key) and may cross-check this value.
+     */
     xClientTraceId?: string;
 };
+/**
+ * Debug-only, opt-in, subscriber-gated record of a completed MCP tool call.
+ * `args` and `result` are captured verbatim and MAY contain PII, so consumers
+ * must redact before persisting or sharing. This is not a telemetry event and
+ * MUST NOT be added to `TelemetryEvent` or any externally-shipped surface.
+ *
+ * `toolName` is the harness-namespaced display name and `bareToolName` is the
+ * un-namespaced leaf. `durationMs` semantics differ by harness: the Claude
+ * bridge reports true RPC latency, while Mastra and OpenAI report an
+ * adapter/coordinator-observed window that may include a model round-trip.
+ * Consumers MUST NOT compare durations across harnesses.
+ */
+export type McpToolCallCompletedEvent = {
+    /** Direction discriminator. */
+    type: 'mcp-tool-call-completed';
+    /** Wall-clock timestamp when the tool call completed. */
+    timestamp: Date;
+    /** Logical MCP server name from the configured server catalog. */
+    serverName: string;
+    /** Harness-namespaced display name presented to the model. */
+    toolName: string;
+    /** Un-namespaced tool-name leaf. */
+    bareToolName: string;
+    /** Verbatim arguments passed to the tool. May contain PII. */
+    args: Record<string, unknown>;
+    /** Verbatim result returned by the tool. May contain PII. */
+    result: unknown;
+    /** Harness-dependent observed duration; do not compare across harnesses. */
+    durationMs?: number;
+};
 /**
  * Emitted by harnesses whose runtime doesn't expose a programmatic seam for
  * per-call wire monitoring. The event signals to consumers that
@@ -120,5 +174,5 @@ export type WireMonitoringNotSupportedEvent = {
  * Union over every wire-communication event the harness layer can emit.
  * Discriminate on the `type` field.
  */
-export type WireCommunicationEvent = LlmRequestEvent | LlmResponseEvent | WireMonitoringNotSupportedEvent;
+export type WireCommunicationEvent = LlmRequestEvent | LlmResponseEvent | McpToolCallCompletedEvent | WireMonitoringNotSupportedEvent;
 export type WireCommunicationEventCallback = (event: WireCommunicationEvent) => void;

package/dist/wire-communication-file-writer.js

@@ -68,6 +68,8 @@ function formatAsMarkdown(event) {
             return formatRequestMarkdown(event);
         case 'llm-response':
             return formatResponseMarkdown(event);
+        case 'mcp-tool-call-completed':
+            return formatMcpToolCallCompletedMarkdown(event);
         case 'wire-monitoring-not-supported':
             return formatWireMonitoringNotSupportedMarkdown(event);
     }
@@ -135,6 +137,32 @@ function formatResponseMarkdown(event) {
     }
     return lines.join('\n');
 }
+function formatMcpToolCallCompletedMarkdown(event) {
+    const lines = [
+        `### ${event.timestamp.toISOString()} [${event.type}]`,
+        ``,
+        `**Server**: ${event.serverName}`,
+        ``,
+        `**Tool**: ${event.toolName}`,
+        ``,
+        `**Bare tool**: ${event.bareToolName}`,
+        ``,
+        `**Args**:`,
+        '```json',
+        JSON.stringify(event.args, null, 2),
+        '```',
+        ``,
+        `**Result**:`,
+        '```json',
+        JSON.stringify(event.result, null, 2),
+        '```',
+        ``,
+    ];
+    if (event.durationMs !== undefined) {
+        lines.push(`**Duration**: ${event.durationMs}`, ``);
+    }
+    return lines.join('\n');
+}
 function formatWireMonitoringNotSupportedMarkdown(event) {
     const dateTime = event.timestamp.toISOString();
     return [`### ${dateTime} [${event.type}]`, ``, `**Harness**: ${event.harnessId}`, ``, event.message, ``, ``].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -47,9 +47,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.35.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.38.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.4.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.37.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.40.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.6.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.22",