@salesforce/sfdx-agent-harness-mastra 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to `@salesforce/sfdx-agent-harness-mastra` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.40.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.39.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.38.0] - 2026-07-30
 
 ### Features

package/README.md

@@ -24,6 +24,16 @@ const manager = await createAgentManager('/path/to/storage', new MastraHarnessFa
 See the [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full consumer-facing API. For
 internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
+### Observability compatibility
+
+This in-process harness emits structured `llm-request` / `llm-response` wire events. Matching events carry the
+harness-generated `correlationId`; `llm-response` provides best-effort `responseText` and `timeToFirstTokenMs` after the
+streaming body terminates. It also emits the debug-only `mcp-tool-call-completed` event; its `durationMs` is an
+adapter/coordinator-observed window and can include a model round-trip. It does **not** emit `llm-retry` telemetry
+because its stateless fetch layer has no observable retry attempt counter. See the SDK README's
+[cross-harness coverage table](../sfdx-agent-sdk/README.md#cross-harness-coverage) for the complete contract and
+cross-harness comparison.
+
 ### Removing the storage directory on Windows
 
 `manager.shutdown()` checkpoints the WAL and closes the libsql client (forcedotcom/agentic-dx#429,

package/dist/mastra-approval-coordinator.d.ts

@@ -1,9 +1,9 @@
 import type { Agent } from '@mastra/core/agent';
 import type { RequestContext } from '@mastra/core/request-context';
 import type { ChunkType } from '@mastra/core/stream';
-import { type ChatEvent, type Decision as PolicyDecision, type McpToolAnnotations, type ToolInvocation } from '@salesforce/sfdx-agent-sdk';
+import { type ChatEvent, type Decision as PolicyDecision, type McpToolAnnotations, type ToolInvocation, type WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
 import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
-import type { LogBus } from '@salesforce/agentic-common';
+import type { Clock, LogBus } from '@salesforce/agentic-common';
 /**
  * Output shape from `agent.stream()` / `agent.approveToolCall()` /
  * `agent.declineToolCall()`. Captured as a structural type so the
@@ -113,6 +113,9 @@ export interface MastraApprovalCoordinatorOptions {
      */
     skillBridgeToolNames?: ReadonlySet<string>;
     logBus?: LogBus;
+    clock: Clock;
+    emitWireCommunication: (event: WireCommunicationEvent) => void;
+    hasWireCommunicationSubscribers: () => boolean;
 }
 /**
  * Per-`(agentId, threadId)` coordinator that subsumes the pre-#529
@@ -161,6 +164,9 @@ export declare class MastraApprovalCoordinator {
     private readonly consumerToolNames;
     private readonly lookupMcpToolMetadata?;
     private readonly skillBridgeToolNames;
+    private readonly clock;
+    private readonly emitWireCommunication;
+    private readonly hasWireCommunicationSubscribers;
     private readonly adapter;
     /** Single per-turn sink. Issue #529 contract: one stream per turn. */
     private readonly initial;
@@ -183,6 +189,7 @@ export declare class MastraApprovalCoordinator {
     private readonly approvalTimers;
     /** Args from the adapter's `tool-call` ChatEvent keyed by `toolCallId`. */
     private readonly toolCallArgs;
+    private readonly pendingMcpToolCallStarts;
     /**
      * Mastra's current `runId` after the latest stream/resume. Updated on
      * each successful pump entry. Needed for the next
@@ -395,6 +402,12 @@ export declare class MastraApprovalCoordinator {
      * `tool-result` / `tool-approval-request`.
      */
     private routeEnriched;
+    /**
+     * Emits a coordinator-observed call-to-result window for a real MCP tool.
+     * Mastra durationMs includes model round-trip time, so it is not comparable
+     * to the Claude bridge's host-to-MCP RPC latency.
+     */
+    private emitMcpToolCallCompleted;
     private maybeEnrich;
     /**
      * Build the {@link ToolInvocation} the policy resolver matches against, and

package/dist/mastra-approval-coordinator.js

@@ -76,6 +76,9 @@ export class MastraApprovalCoordinator {
     consumerToolNames;
     lookupMcpToolMetadata;
     skillBridgeToolNames;
+    clock;
+    emitWireCommunication;
+    hasWireCommunicationSubscribers;
     adapter;
     /** Single per-turn sink. Issue #529 contract: one stream per turn. */
     initial = new GenSink();
@@ -98,6 +101,7 @@ export class MastraApprovalCoordinator {
     approvalTimers = new Map();
     /** Args from the adapter's `tool-call` ChatEvent keyed by `toolCallId`. */
     toolCallArgs = new Map();
+    pendingMcpToolCallStarts = new Map();
     /**
      * Mastra's current `runId` after the latest stream/resume. Updated on
      * each successful pump entry. Needed for the next
@@ -177,6 +181,9 @@ export class MastraApprovalCoordinator {
         this.consumerToolNames = opts.consumerToolNames;
         this.lookupMcpToolMetadata = opts.lookupMcpToolMetadata;
         this.skillBridgeToolNames = opts.skillBridgeToolNames ?? new Set();
+        this.clock = opts.clock;
+        this.emitWireCommunication = opts.emitWireCommunication;
+        this.hasWireCommunicationSubscribers = opts.hasWireCommunicationSubscribers;
         this.adapter = new MastraEventAdapter(opts.logBus);
     }
     // ───────────────────────── lifecycle / sinks ────────────────────────────
@@ -302,6 +309,7 @@ export class MastraApprovalCoordinator {
      */
     teardown(reason, error, code) {
         this.cancelAllTimers();
+        this.pendingMcpToolCallStarts.clear();
         for (const id of this.emittedApprovals)
             this.settledByCoordinator.add(id);
         // Issue #589: drain in-flight consumer-tool ids into the
@@ -546,6 +554,7 @@ export class MastraApprovalCoordinator {
                     sawTerminal = true;
                     this.cancelAllTimers();
                     this.routeEnriched(event);
+                    this.pendingMcpToolCallStarts.clear();
                     this.initial.end();
                     return 'terminal';
                 }
@@ -553,6 +562,7 @@ export class MastraApprovalCoordinator {
                     sawTerminal = true;
                     this.cancelAllTimers();
                     this.routeEnriched(event);
+                    this.pendingMcpToolCallStarts.clear();
                     // Per SDK contract: 'error' is terminal; emit a synthetic
                     // 'finish' so wrapEventStream's invariant holds.
                     this.initial.push({ type: 'finish', finishReason: 'error' });
@@ -676,6 +686,7 @@ export class MastraApprovalCoordinator {
             return 'suspended';
         }
         if (!sawTerminal && !this.initial.isEnded()) {
+            this.pendingMcpToolCallStarts.clear();
             this.initial.end();
         }
         return 'terminal';
@@ -753,14 +764,54 @@ export class MastraApprovalCoordinator {
         if (enriched.type === 'tool-call' && isRealMcpServer(enriched.serverName)) {
             this.currentMcpToolCallId = enriched.toolCallId;
             this.toolNameForCallId.set(enriched.toolCallId, enriched.toolName);
+            if (this.hasWireCommunicationSubscribers()) {
+                this.pendingMcpToolCallStarts.set(enriched.toolCallId, this.clock.now());
+            }
         }
         else if (enriched.type === 'tool-result' &&
             isRealMcpServer(enriched.serverName) &&
             this.currentMcpToolCallId === enriched.toolCallId) {
             this.currentMcpToolCallId = null;
         }
+        if (enriched.type === 'tool-result' && isRealMcpServer(enriched.serverName)) {
+            this.emitMcpToolCallCompleted(enriched);
+        }
         this.initial.push(enriched);
     }
+    /**
+     * Emits a coordinator-observed call-to-result window for a real MCP tool.
+     * Mastra durationMs includes model round-trip time, so it is not comparable
+     * to the Claude bridge's host-to-MCP RPC latency.
+     */
+    emitMcpToolCallCompleted(event) {
+        const startedAt = this.pendingMcpToolCallStarts.get(event.toolCallId);
+        if (startedAt === undefined)
+            return;
+        this.pendingMcpToolCallStarts.delete(event.toolCallId);
+        if (!this.hasWireCommunicationSubscribers())
+            return;
+        const completedAt = this.clock.now();
+        const serverName = event.serverName;
+        if (serverName === undefined)
+            return;
+        try {
+            this.emitWireCommunication({
+                type: 'mcp-tool-call-completed',
+                timestamp: completedAt,
+                serverName,
+                toolName: event.toolName,
+                bareToolName: event.bareToolName ?? event.toolName,
+                args: this.toolCallArgs.get(event.toolCallId) ?? {},
+                result: event.result,
+                durationMs: completedAt.getTime() - startedAt.getTime(),
+            });
+        }
+        catch (err) {
+            if (err instanceof AgentSDKError && err.type === AgentSDKErrorType.DISPOSED)
+                return;
+            throw err;
+        }
+    }
     maybeEnrich(event) {
         if (event.type !== 'tool-call' && event.type !== 'tool-result' && event.type !== 'tool-approval-request') {
             return event;

package/dist/mastra-harness.d.ts

@@ -266,6 +266,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly idGenerator;
     private readonly toolApprovalTimeoutMs;
     private readonly innerFetch;
+    private readonly wireObserverAbortController;
     private readonly languageModelBuilders?;
     constructor(storageRootFolder: string, opts?: MastraHarnessOptions);
     /**

package/dist/mastra-harness.js

@@ -398,6 +398,7 @@ export class MastraHarness {
     idGenerator;
     toolApprovalTimeoutMs;
     innerFetch;
+    wireObserverAbortController = new AbortController();
     languageModelBuilders;
     constructor(storageRootFolder, opts = {}) {
         this.storageRootFolder = storageRootFolder;
@@ -436,6 +437,7 @@ export class MastraHarness {
      *   (forcedotcom/agentic-dx#429, mastra-ai/mastra#17285).
      */
     async shutdown() {
+        this.wireObserverAbortController.abort();
         await Promise.all([...this.activeAgents.values()].map(async (state) => {
             for (const coordinator of state.coordinators.values()) {
                 coordinator.dispose();
@@ -849,21 +851,31 @@ export class MastraHarness {
             serverState.errorDetail = errorDetail;
             serverState.settled = true;
             const emitStatusChange = this.prepareMcpStatusChange(agentId, serverName, serverState, McpServerStatus.Error, message);
-            this.buses.getLogBus()?.warn('MCP server reconnect failed', {
-                agentId,
-                serverName,
-                error: message,
-            });
             try {
+                const failedAt = this.clock.now();
+                const failedError = effectiveError instanceof Error ? effectiveError : new Error(message);
                 this.buses.emitTelemetry({
                     type: 'mcp-server-discovery-failed',
-                    timestamp: this.clock.now(),
+                    timestamp: failedAt,
                     agentId,
                     serverName,
-                    durationMs: this.clock.now().getTime() - startTime,
-                    error: effectiveError instanceof Error ? effectiveError : new Error(message),
+                    durationMs: failedAt.getTime() - startTime,
+                    error: failedError,
                     errorDetail,
                 });
+                this.buses.emitLog({
+                    level: 'error',
+                    message: 'MCP server discovery failed',
+                    timestamp: failedAt,
+                    context: {
+                        event_type: 'mcp-server-discovery-failed',
+                        agentId,
+                        serverName,
+                        durationMs: failedAt.getTime() - startTime,
+                        errorDetail,
+                    },
+                    error: failedError,
+                });
             }
             catch (emitErr) {
                 if (!isDisposedError(emitErr))
@@ -1290,25 +1302,34 @@ export class MastraHarness {
             }
         };
         const innerFetch = this.innerFetch;
+        const wireHooks = {
+            emitWireCommunication,
+            getModel: () => getInfo().nativeModelId,
+            getProviderHint: () => getInfo().providerHint,
+            clock: this.clock,
+            idGenerator: this.idGenerator,
+            hasWireCommunicationSubscribers: () => this.buses.hasWireCommunicationSubscribers(),
+            disposeSignal: this.wireObserverAbortController.signal,
+        };
         switch (initial.providerHint) {
             case 'bedrock-anthropic':
                 // Salesforce LLM Gateway's `/invoke-with-response-stream` (Bedrock pass-through).
-                return buildAnthropicLanguageModel({ getInfo, logBus, emitWireCommunication, innerFetch });
+                return buildAnthropicLanguageModel({ getInfo, logBus, wireHooks, innerFetch });
             case 'anthropic':
                 // Direct Anthropic Messages API (`api.anthropic.com/v1/messages`) —
                 // different wire shape (`x-api-key` auth, body without `anthropic_version`).
-                return buildAnthropicDirectLanguageModel({ getInfo, logBus, emitWireCommunication, innerFetch });
+                return buildAnthropicDirectLanguageModel({ getInfo, logBus, wireHooks, innerFetch });
             case 'openai-responses':
             case 'openai':
                 // OpenAI Responses API. Salesforce LLM Gateway's `/responses` pass-through
                 // for `'openai-responses'`; `api.openai.com/v1/responses` for `'openai'` direct.
                 // Same wire shape; the only difference is the `baseUrl` the resolver supplies.
-                return buildOpenAILanguageModel({ getInfo, logBus, emitWireCommunication, innerFetch });
+                return buildOpenAILanguageModel({ getInfo, logBus, wireHooks, innerFetch });
             case 'openai-compatible':
                 // OpenAI-compatible Chat Completions API (LLMG Express, LiteLLM, etc.).
                 // Different wire shape from Responses — `/v1/chat/completions` with
                 // `choices[0].delta` streaming events.
-                return buildOpenAIChatCompletionsLanguageModel({ getInfo, logBus, emitWireCommunication, innerFetch });
+                return buildOpenAIChatCompletionsLanguageModel({ getInfo, logBus, wireHooks, innerFetch });
             default: {
                 // Consult the injected builders map before throwing. This is the
                 // extension point for consumer-registered wire shapes (e.g. a temporary
@@ -1486,6 +1507,9 @@ export class MastraHarness {
             lookupMcpToolMetadata: (name) => lookupMcpToolMetadata(agentState.mcpServers, name),
             skillBridgeToolNames: activeSkillBridgeToolNames(agentState),
             logBus: this.buses.getLogBus(),
+            clock: this.clock,
+            emitWireCommunication: (event) => this.buses.emitWireCommunication(event),
+            hasWireCommunicationSubscribers: () => this.buses.hasWireCommunicationSubscribers(),
         });
         agentState.coordinators.set(threadId, coordinator);
         const abortSignal = options?.abortSignal;
@@ -1754,15 +1778,31 @@ export class MastraHarness {
         serverState.currentStatus = nextStatus;
         return () => {
             try {
+                const changedAt = this.clock.now();
                 this.buses.emitTelemetry({
                     type: 'mcp-server-status-changed',
-                    timestamp: this.clock.now(),
+                    timestamp: changedAt,
                     agentId,
                     serverName,
                     previousStatus,
                     nextStatus,
                     ...(error !== undefined ? { error } : {}),
                 });
+                // Consider dropping this if it becomes too noisy.
+                const isErrorStatus = nextStatus === McpServerStatus.Error;
+                this.buses.emitLog({
+                    level: isErrorStatus ? 'error' : 'info',
+                    message: 'MCP server status changed',
+                    timestamp: changedAt,
+                    context: {
+                        event_type: 'mcp-server-status-changed',
+                        agentId,
+                        serverName,
+                        previousStatus,
+                        nextStatus,
+                        ...(error !== undefined ? { error } : {}),
+                    },
+                });
             }
             catch (emitErr) {
                 if (!isDisposedError(emitErr))
@@ -1891,13 +1931,29 @@ export class MastraHarness {
             // after `shutdown()` has disposed the buses. Swallow only `DISPOSED`
             // so a real listener exception still surfaces.
             try {
+                const completedAt = this.clock.now();
+                const toolCount = Object.keys(namespacedTools).length;
+                const durationMs = completedAt.getTime() - startTime;
                 this.buses.emitTelemetry({
                     type: 'mcp-server-discovery-completed',
-                    timestamp: this.clock.now(),
+                    timestamp: completedAt,
                     agentId,
                     serverName,
-                    toolCount: Object.keys(namespacedTools).length,
-                    durationMs: this.clock.now().getTime() - startTime,
+                    toolCount,
+                    durationMs,
+                });
+                // Consider dropping this if it becomes too noisy.
+                this.buses.emitLog({
+                    level: 'info',
+                    message: 'MCP server discovery completed',
+                    timestamp: completedAt,
+                    context: {
+                        event_type: 'mcp-server-discovery-completed',
+                        agentId,
+                        serverName,
+                        toolCount,
+                        durationMs,
+                    },
                 });
             }
             catch (emitErr) {
@@ -1937,21 +1993,32 @@ export class MastraHarness {
                 s.errorDetail = errorDetail;
                 s.settled = true;
                 const emitStatusChange = this.prepareMcpStatusChange(agentId, serverName, s, McpServerStatus.Error, errorMessage);
-                this.buses.getLogBus()?.warn('MCP server discovery failed', {
-                    agentId,
-                    serverName,
-                    error: errorMessage,
-                });
                 try {
+                    const failedAt = this.clock.now();
+                    const failedError = effectiveError instanceof Error ? effectiveError : new Error(String(effectiveError));
+                    const durationMs = failedAt.getTime() - startTime;
                     this.buses.emitTelemetry({
                         type: 'mcp-server-discovery-failed',
-                        timestamp: this.clock.now(),
+                        timestamp: failedAt,
                         agentId,
                         serverName,
-                        durationMs: this.clock.now().getTime() - startTime,
-                        error: effectiveError instanceof Error ? effectiveError : new Error(String(effectiveError)),
+                        durationMs,
+                        error: failedError,
                         errorDetail,
                     });
+                    this.buses.emitLog({
+                        level: 'error',
+                        message: 'MCP server discovery failed',
+                        timestamp: failedAt,
+                        context: {
+                            event_type: 'mcp-server-discovery-failed',
+                            agentId,
+                            serverName,
+                            durationMs,
+                            errorDetail,
+                        },
+                        error: failedError,
+                    });
                 }
                 catch (emitErr) {
                     if (!isDisposedError(emitErr))

package/dist/pass-through-anthropic.d.ts

@@ -2,6 +2,7 @@ import Anthropic from '@anthropic-ai/sdk';
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Prompt } from '@ai-sdk/provider';
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
+import { type GatewayFetchWireHooks } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
  * `/invoke-with-response-stream` (Bedrock-Anthropic pass-through) endpoint.
@@ -20,6 +21,7 @@ export declare function buildAnthropicLanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    wireHooks?: GatewayFetchWireHooks;
     /**
      * Inner fetch routed through the harness's `Dispatcher` (built from
      * `HTTPS_PROXY` / `HTTP_PROXY` or a consumer-supplied one). Defaults to
@@ -51,6 +53,7 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    wireHooks?: GatewayFetchWireHooks;
     /** See {@link buildAnthropicLanguageModel} `innerFetch`. */
     innerFetch?: typeof fetch;
 }): LanguageModelV3;

package/dist/pass-through-anthropic.js

@@ -20,19 +20,20 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * the next request.
  */
 export function buildAnthropicLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
     const initialInfo = getInfo();
     const ctx = {
         getInfo,
         logBus,
         emitWireCommunication,
+        wireHooks,
         buildClient: (info) => new AnthropicBedrock({
             baseURL: info.baseUrl,
             skipAuth: true,
             // The fetch wrapper re-evaluates `getHeaders()` on every outbound call —
             // JWT rotation, premium-rate-limit gate flips, BYOK provider rotation
             // all land on the next request without rebuilding the bridge.
-            fetch: createGatewayFetch(() => info.getHeaders(), buildWireHooks(ctx), innerFetch),
+            fetch: createGatewayFetch(() => info.getHeaders(), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch),
         }),
     };
     return {
@@ -68,12 +69,13 @@ export function buildAnthropicLanguageModel(opts) {
  * language model.
  */
 export function buildAnthropicDirectLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
     const initialInfo = getInfo();
     const ctx = {
         getInfo,
         logBus,
         emitWireCommunication,
+        wireHooks,
         buildClient: (info) => 
         // Anthropic SDK constructor takes `apiKey` and writes `x-api-key` itself.
         // We use a non-empty placeholder here because the SDK requires `apiKey`
@@ -85,7 +87,7 @@ export function buildAnthropicDirectLanguageModel(opts) {
         new Anthropic({
             apiKey: 'anthropic-direct-resolver-managed',
             baseURL: info.baseUrl,
-            fetch: createGatewayFetch(() => translateBearerToXApiKey(info), buildWireHooks(ctx), innerFetch),
+            fetch: createGatewayFetch(() => translateBearerToXApiKey(info), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch),
         }),
     };
     return {

package/dist/pass-through-openai-chat-completions.d.ts

@@ -2,6 +2,7 @@ import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/reso
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3FinishReason, LanguageModelV3Prompt } from '@ai-sdk/provider';
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
+import { type GatewayFetchWireHooks } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
  * `chat.completions.create({ stream: true })` against an OpenAI-compatible
@@ -26,6 +27,7 @@ export declare function buildOpenAIChatCompletionsLanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    wireHooks?: GatewayFetchWireHooks;
     /** See `buildAnthropicLanguageModel` `innerFetch`. */
     innerFetch?: typeof fetch;
 }): LanguageModelV3;

package/dist/pass-through-openai-chat-completions.js

@@ -25,9 +25,9 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * without rebuilding the language model.
  */
 export function buildOpenAIChatCompletionsLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
     const initialInfo = getInfo();
-    const ctx = { getInfo, logBus, emitWireCommunication, innerFetch };
+    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch };
     return {
         specificationVersion: 'v3',
         provider: 'openai-compatible-chat-completions-pass-through',
@@ -45,9 +45,10 @@ export function buildOpenAIChatCompletionsLanguageModel(opts) {
  */
 async function buildRequest(ctx, options) {
     const info = ctx.getInfo();
-    const wireHooks = ctx.emitWireCommunication
-        ? { getModel: () => ctx.getInfo().nativeModelId, emitWireCommunication: ctx.emitWireCommunication }
-        : undefined;
+    const wireHooks = ctx.wireHooks ??
+        (ctx.emitWireCommunication
+            ? { getModel: () => ctx.getInfo().nativeModelId, emitWireCommunication: ctx.emitWireCommunication }
+            : undefined);
     const client = new OpenAI({
         baseURL: info.baseUrl,
         // The custom fetch injects the resolver-built `Authorization` header per

package/dist/pass-through-openai.d.ts

@@ -2,6 +2,7 @@ import type { ResponseInput, Tool } from 'openai/resources/responses/responses';
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Prompt } from '@ai-sdk/provider';
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
+import { type GatewayFetchWireHooks } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
  * `responses.create({ stream: true })` against the Salesforce LLM Gateway's
@@ -18,6 +19,7 @@ export declare function buildOpenAILanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    wireHooks?: GatewayFetchWireHooks;
     /** See `buildAnthropicLanguageModel` `innerFetch`. */
     innerFetch?: typeof fetch;
 }): LanguageModelV3;

package/dist/pass-through-openai.js

@@ -17,9 +17,9 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * next request.
  */
 export function buildOpenAILanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
     const initialInfo = getInfo();
-    const ctx = { getInfo, logBus, emitWireCommunication, innerFetch };
+    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch };
     return {
         specificationVersion: 'v3',
         provider: 'salesforce-llm-gateway-pass-through-openai',
@@ -41,9 +41,10 @@ export function buildOpenAILanguageModel(opts) {
  */
 async function buildOpenAIRequest(ctx, options) {
     const info = ctx.getInfo();
-    const wireHooks = ctx.emitWireCommunication
-        ? { getModel: () => ctx.getInfo().nativeModelId, emitWireCommunication: ctx.emitWireCommunication }
-        : undefined;
+    const wireHooks = ctx.wireHooks ??
+        (ctx.emitWireCommunication
+            ? { getModel: () => ctx.getInfo().nativeModelId, emitWireCommunication: ctx.emitWireCommunication }
+            : undefined);
     const client = new OpenAI({
         baseURL: info.baseUrl,
         // The custom fetch injects the resolver-built `Authorization` header per

package/dist/v3-stream-mapping.d.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelV3FinishReason, LanguageModelV3StreamPart, LanguageModelV3ToolResultOutput, LanguageModelV3Usage } from '@ai-sdk/provider';
-import { Clock } from '@salesforce/agentic-common';
+import { type Clock, type UniqueIDGenerator } from '@salesforce/agentic-common';
 import type { Model } from '@salesforce/sfdx-agent-sdk';
 /**
  * Shared V3 helpers for the Mastra harness's `LanguageModelV3` implementations
@@ -196,6 +196,14 @@ export type GatewayFetchWireHooks = {
     emitWireCommunication: (event: WireCommunicationLikeEvent) => void;
     /** Optional clock for test determinism. Defaults to a fresh `RealClock`. */
     clock?: Clock;
+    /** ID source for pairing one fetch's request and terminal response events. */
+    idGenerator?: UniqueIDGenerator;
+    /** Current provider wire shape; response text extraction is deliberately shape-specific. */
+    getProviderHint?: () => string;
+    /** Whether the harness has subscribers; avoids teeing streams nobody observes. */
+    hasWireCommunicationSubscribers?: () => boolean;
+    /** Aborted by harness shutdown so detached body observers cannot outlive their owner. */
+    disposeSignal?: AbortSignal;
 };
 /**
  * Wraps an `innerFetch` (defaults to `globalThis.fetch`) with a per-request
@@ -212,8 +220,11 @@ export type GatewayFetchWireHooks = {
  *
  * When `wireHooks` is supplied, every outbound call emits one
  * `WireCommunicationEvent` `request` event and one `response` event onto the
- * supplied callback. Wire-communication events are best-effort: a failed body
- * decode does NOT prevent the call from completing. Body capture is
+ * supplied callback. For streaming responses the response event moves from
+ * fetch resolution to HTTP-body terminality: an owned tee branch observes only
+ * recognized assistant text deltas without blocking the provider SDK's branch.
+ * Wire-communication events are best-effort: a failed body decode does NOT
+ * prevent the call from completing. Body capture is
  * intentionally bounded — only requests with a JSON body shorter than 256 KB
  * are decoded; longer bodies are recorded as `{ truncated: true, byteLength:
  * <n> }` so wire-communication captures don't blow the consumer's log file
@@ -231,15 +242,19 @@ type WireCommunicationLikeEvent = {
     url: string;
     method: string;
     model: string;
+    correlationId?: string;
     body?: Record<string, unknown>;
 } | {
     type: 'llm-response';
     timestamp: Date;
     model: string;
     status: number;
+    correlationId?: string;
     error?: Error;
     totalDurationMs?: number;
     xClientTraceId?: string;
+    responseText?: string;
+    timeToFirstTokenMs?: number;
 };
 /**
  * Reduces a V3 `LanguageModelV3ToolResultOutput` to the string shape every

package/dist/v3-stream-mapping.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { Clock, RealClock } from '@salesforce/agentic-common';
+import { RealClock, UUIDGenerator } from '@salesforce/agentic-common';
 /**
  * Shared V3 helpers for the Mastra harness's `LanguageModelV3` implementations
  * — stream-shaping primitives, finish-reason / usage mappers, prompt-translation
@@ -254,8 +254,11 @@ export function mapOpenAIUsage(usage) {
  *
  * When `wireHooks` is supplied, every outbound call emits one
  * `WireCommunicationEvent` `request` event and one `response` event onto the
- * supplied callback. Wire-communication events are best-effort: a failed body
- * decode does NOT prevent the call from completing. Body capture is
+ * supplied callback. For streaming responses the response event moves from
+ * fetch resolution to HTTP-body terminality: an owned tee branch observes only
+ * recognized assistant text deltas without blocking the provider SDK's branch.
+ * Wire-communication events are best-effort: a failed body decode does NOT
+ * prevent the call from completing. Body capture is
  * intentionally bounded — only requests with a JSON body shorter than 256 KB
  * are decoded; longer bodies are recorded as `{ truncated: true, byteLength:
  * <n> }` so wire-communication captures don't blow the consumer's log file
@@ -283,6 +286,7 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
         const model = wireHooks.getModel();
         const clock = wireHooks.clock ?? new RealClock();
         const startedAt = clock.now();
+        const correlationId = (wireHooks.idGenerator ?? new UUIDGenerator()).getUniqueId();
         const requestStart = performance.now();
         wireHooks.emitWireCommunication({
             type: 'llm-request',
@@ -290,19 +294,41 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
             url,
             method,
             model,
+            correlationId,
             body: tryDecodeBody(finalInit.body),
         });
         try {
             const response = await innerFetch(input, finalInit);
-            wireHooks.emitWireCommunication({
-                type: 'llm-response',
-                timestamp: clock.now(),
-                model,
-                status: response.status,
-                totalDurationMs: Math.round(performance.now() - requestStart),
-                xClientTraceId: response.headers.get('x-client-trace-id') ?? undefined,
-            });
-            return response;
+            const emitResponse = (result = {}) => {
+                wireHooks.emitWireCommunication({
+                    type: 'llm-response',
+                    timestamp: clock.now(),
+                    model,
+                    status: response.status,
+                    correlationId,
+                    totalDurationMs: Math.round(performance.now() - requestStart),
+                    xClientTraceId: response.headers.get('x-client-trace-id') ?? undefined,
+                    ...(result.responseText !== undefined ? { responseText: result.responseText } : {}),
+                    ...(result.timeToFirstTokenMs !== undefined
+                        ? { timeToFirstTokenMs: result.timeToFirstTokenMs }
+                        : {}),
+                });
+            };
+            if (response.body === null || !(wireHooks.hasWireCommunicationSubscribers?.() ?? true)) {
+                emitResponse();
+                return response;
+            }
+            const [observerBody, sdkBody] = response.body.tee();
+            void observeResponseBody({
+                body: observerBody,
+                providerHint: wireHooks.getProviderHint?.(),
+                contentType: response.headers.get('content-type'),
+                requestSignal: finalInit.signal ?? undefined,
+                disposeSignal: wireHooks.disposeSignal,
+                clock,
+                onComplete: emitResponse,
+            }).catch(() => undefined);
+            return new Response(sdkBody, response);
         }
         catch (error) {
             wireHooks.emitWireCommunication({
@@ -310,6 +336,7 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
                 timestamp: clock.now(),
                 model,
                 status: 0,
+                correlationId,
                 error: error instanceof Error ? error : new Error(String(error)),
                 totalDurationMs: Math.round(performance.now() - requestStart),
             });
@@ -318,6 +345,141 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
     };
 }
 const TRACE_BODY_BYTE_BUDGET = 256 * 1024;
+/**
+ * Observes only the owned tee branch. Cancellation intentionally does not await
+ * `reader.cancel()`: WHATWG tee cancellation may wait for the provider SDK's
+ * unread branch and must never let telemetry hang a fetch.
+ */
+async function observeResponseBody(options) {
+    const reader = options.body.getReader();
+    const decoder = new TextDecoder();
+    const startedAt = options.clock.now();
+    const text = [];
+    let textBytes = 0;
+    let rawBytes = 0;
+    let firstTokenAt;
+    let sawOutputText = false;
+    let sseBuffer = '';
+    let cancelled = false;
+    let resolveCancelled;
+    const cancellation = new Promise((resolve) => {
+        resolveCancelled = resolve;
+    });
+    const cancel = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        void reader.cancel().catch(() => undefined);
+        try {
+            reader.releaseLock();
+        }
+        catch (error) {
+            String(error);
+        }
+        resolveCancelled?.();
+    };
+    const abort = () => cancel();
+    options.requestSignal?.addEventListener('abort', abort, { once: true });
+    options.disposeSignal?.addEventListener('abort', abort, { once: true });
+    if (options.requestSignal?.aborted || options.disposeSignal?.aborted)
+        cancel();
+    try {
+        while (!cancelled) {
+            const read = reader.read();
+            void read.catch(() => undefined);
+            const next = await Promise.race([read, cancellation.then(() => undefined)]);
+            if (cancelled || next === undefined || next.done)
+                break;
+            if (firstTokenAt === undefined)
+                firstTokenAt = options.clock.now().getTime() - startedAt.getTime();
+            if (rawBytes + next.value.byteLength > TRACE_BODY_BYTE_BUDGET) {
+                cancel();
+                break;
+            }
+            rawBytes += next.value.byteLength;
+            sseBuffer += decoder.decode(next.value, { stream: true });
+            const parsed = takeSseEvents(sseBuffer);
+            sseBuffer = parsed.remaining;
+            for (const event of parsed.events) {
+                const delta = outputTextDelta(options.providerHint, options.contentType, event);
+                if (delta === undefined)
+                    continue;
+                const deltaBytes = Buffer.byteLength(delta, 'utf8');
+                if (textBytes + deltaBytes > TRACE_BODY_BYTE_BUDGET) {
+                    cancel();
+                    break;
+                }
+                sawOutputText = true;
+                text.push(delta);
+                textBytes += deltaBytes;
+            }
+        }
+    }
+    catch {
+        sawOutputText = false;
+    }
+    finally {
+        options.requestSignal?.removeEventListener('abort', abort);
+        options.disposeSignal?.removeEventListener('abort', abort);
+        if (!cancelled) {
+            try {
+                reader.releaseLock();
+            }
+            catch (error) {
+                String(error);
+            }
+        }
+        options.onComplete({
+            ...(sawOutputText ? { responseText: text.join('') } : {}),
+            ...(firstTokenAt !== undefined ? { timeToFirstTokenMs: firstTokenAt } : {}),
+        });
+    }
+}
+function takeSseEvents(buffer) {
+    const complete = buffer.lastIndexOf('\n');
+    if (complete === -1)
+        return { events: [], remaining: buffer };
+    const events = [];
+    for (const line of buffer.slice(0, complete).split(/\r?\n/)) {
+        if (!line.startsWith('data:'))
+            continue;
+        const data = line.slice('data:'.length).trim();
+        if (data.length === 0 || data === '[DONE]')
+            continue;
+        try {
+            events.push(JSON.parse(data));
+        }
+        catch {
+            // Unknown framing is deliberately not captured as text.
+        }
+    }
+    return { events, remaining: buffer.slice(complete + 1) };
+}
+/** Extract only the documented assistant output-text delta for each supported wire shape. */
+function outputTextDelta(providerHint, contentType, event) {
+    if (!contentType?.toLowerCase().includes('text/event-stream') || typeof event !== 'object' || event === null) {
+        return undefined;
+    }
+    const candidate = event;
+    if (providerHint === 'anthropic' || providerHint === 'bedrock-anthropic') {
+        const delta = candidate.delta;
+        return candidate.type === 'content_block_delta' &&
+            delta?.type === 'text_delta' &&
+            typeof delta.text === 'string'
+            ? delta.text
+            : undefined;
+    }
+    if (providerHint === 'openai' || providerHint === 'openai-responses') {
+        return candidate.type === 'response.output_text.delta' && typeof candidate.delta === 'string'
+            ? candidate.delta
+            : undefined;
+    }
+    if (providerHint === 'openai-compatible') {
+        const content = candidate.choices?.[0]?.delta?.content;
+        return typeof content === 'string' ? content : undefined;
+    }
+    return undefined;
+}
 function tryDecodeBody(body) {
     if (body === undefined || body === null)
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -41,12 +41,12 @@
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.39.0"
+    "@salesforce/sfdx-agent-sdk": "0.41.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.39.0",
+    "@salesforce/sfdx-agent-sdk": "0.41.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.22",