@salesforce/sfdx-agent-harness-mastra 0.100.0 → 0.102.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.102.0] - 2026-10-13
+
+### Features
+- **deps**: upgrade dependencies and move the Mastra harness to @mastra/mcp 2.x @W-24334288@ ([#877](https://github.com/forcedotcom/agentic-dx/pull/877))
+
+## [0.101.0] - 2026-10-13
+
+### Features
+- **harness-mastra**: migrate pass-throughs to LanguageModelV4 and remove chat-generations @W-24224624@ ([#876](https://github.com/forcedotcom/agentic-dx/pull/876))
+
 ## [0.100.0] - 2026-10-09
 
 ### Chores

package/README.md

@@ -59,8 +59,8 @@ Linux and macOS release the handle eagerly; the retry options are no-ops on thos
 | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `MastraHarnessFactory`              | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                                                                                                   |
 | `MastraHarnessFactoryConfig`        | interface | Configuration for `MastraHarnessFactory` (`toolApprovalTimeoutMs?`, `languageModelBuilders?`).                                                                                                                                           |
-| `MastraLanguageModelBuilderContext` | type      | Context bag the harness threads into each `LanguageModelV3` builder (`getInfo`, `logBus`, `emitWireCommunication`, `innerFetch`).                                                                                                        |
-| `MastraLanguageModelBuilder`        | type      | Factory function shape for a consumer-injected builder: `(ctx: MastraLanguageModelBuilderContext) => LanguageModelV3`.                                                                                                                   |
+| `MastraLanguageModelBuilderContext` | type      | Context bag the harness threads into each `LanguageModelV4` builder (`getInfo`, `logBus`, `emitWireCommunication`, `innerFetch`).                                                                                                        |
+| `MastraLanguageModelBuilder`        | type      | Factory function shape for a consumer-injected builder: `(ctx: MastraLanguageModelBuilderContext) => LanguageModelV4`.                                                                                                                   |
 | `MASTRA_BUILT_IN_TOOL_POLICIES`     | const     | Frozen `ReadonlyArray<ToolPolicyRule>` the harness feeds the SDK's `resolveToolApprovalPolicy` as the `tiers.harness` slice — `allow` rules for Mastra's built-in `updateWorkingMemory` / `skill` / `skill_search` / `skill_read` tools. |
 | `MASTRA_BUILT_IN_TOOL_NAMES`        | const     | The four built-in tool leaf names `MASTRA_BUILT_IN_TOOL_POLICIES` covers.                                                                                                                                                                |
 
@@ -81,20 +81,14 @@ no `globalThis` mutation. When no proxy env is set, `fetch` runs unwrapped (zero
 
 #### Injecting custom wire shapes
 
-A consumer can register a `LanguageModelV3` builder for a custom `providerHint` via
+A consumer can register a `LanguageModelV4` builder for a custom `providerHint` via
 `MastraHarnessFactoryConfig.languageModelBuilders` without editing the harness's internal switch. Each injected key
-becomes a supported provider hint and a dispatch arm. Used to inject wire shapes the harness does not ship natively
-(e.g., a temporary GovCloud `chat/generations` fallback).
+becomes a supported provider hint and a dispatch arm. Used to inject wire shapes the harness does not ship natively.
 
 ```ts
-import {
-  CHAT_GENERATIONS_PROVIDER_HINT,
-  buildChatGenerationsLanguageModel,
-} from '@salesforce/sfdx-agent-chat-generations';
-
 const factory = new MastraHarnessFactory({
   languageModelBuilders: {
-    [CHAT_GENERATIONS_PROVIDER_HINT]: buildChatGenerationsLanguageModel,
+    'my-custom-wire-shape': (ctx) => buildMyLanguageModel(ctx),
   },
 });
 ```

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
-import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { LanguageModelV4 } from '@ai-sdk/provider';
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
 export { MASTRA_BUILT_IN_TOOL_NAMES, MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
 /**
- * Context the harness threads into each `LanguageModelV3` builder — both the
+ * Context the harness threads into each `LanguageModelV4` builder — both the
  * built-in builders and any consumer-injected builders registered via
  * `MastraHarnessFactoryConfig.languageModelBuilders`. The shape mirrors what
  * `MastraHarness.buildLanguageModel` currently hands its internal builders, so an
@@ -33,10 +33,10 @@ export type MastraLanguageModelBuilderContext = {
     innerFetch: typeof fetch;
 };
 /**
- * Factory function shape for a consumer-injected `LanguageModelV3` builder.
+ * Factory function shape for a consumer-injected `LanguageModelV4` builder.
  * Registered via `MastraHarnessFactoryConfig.languageModelBuilders` keyed by a custom
  * `providerHint`, used to inject wire shapes the harness does not ship natively
- * (e.g. a temporary GovCloud `chat/generations` fallback). The builder receives the
+ * (e.g. a bespoke gateway wire format). The builder receives the
  * same context bag the harness's built-in pass-through builders get, so an injected
  * builder can emit `WireCommunicationEvent`s and honor `HTTPS_PROXY` routing without
  * duplicating the harness's own fetch wrapper / wire-monitoring plumbing. The
@@ -55,4 +55,4 @@ export type MastraLanguageModelBuilderContext = {
  * });
  * ```
  */
-export type MastraLanguageModelBuilder = (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3;
+export type MastraLanguageModelBuilder = (ctx: MastraLanguageModelBuilderContext) => LanguageModelV4;

package/dist/mastra-harness-factory.d.ts

@@ -12,10 +12,10 @@ export interface MastraHarnessFactoryConfig {
      */
     toolApprovalTimeoutMs?: number;
     /**
-     * Consumer-registered `LanguageModelV3` builders keyed by `providerHint`. Each key
+     * Consumer-registered `LanguageModelV4` builders keyed by `providerHint`. Each key
      * becomes a supported provider hint and a dispatch arm in `buildLanguageModel`. Used
-     * to inject wire shapes the harness does not ship natively (e.g. a temporary
-     * GovCloud `chat/generations` fallback path). Keys MUST NOT collide with the
+     * to inject wire shapes the harness does not ship natively (e.g. a bespoke
+     * gateway wire format). Keys MUST NOT collide with the
      * harness's built-in hints (`anthropic`, `bedrock-anthropic`, `openai`,
      * `openai-responses`, `openai-compatible`) — constructing with a colliding key
      * throws at factory construction time rather than silently shadowing the built-in.

package/dist/mastra-harness.d.ts

@@ -5,10 +5,9 @@ import { McpServerStatus, type AgentHarness, type WithAgentConfig, type HarnessS
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import type { MastraLanguageModelBuilderContext } from './index.js';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
-import { type HttpErrorCapture } from './mcp-config-mapper.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
 import { type MultimodalFile } from '@salesforce/sfdx-agent-sdk';
-import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { LanguageModelV4 } from '@ai-sdk/provider';
 import { Clock, type LogRecord, type BackoffRetryerDeps, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
@@ -67,15 +66,6 @@ interface McpServerState {
      * on (tool merging, alwaysActive expansion, MCP-tool metadata lookup).
      */
     tools: ToolsInput;
-    /**
-     * HTTP-error capture slot for remote servers (W-23231658). The remote
-     * transport fetch (built by `mapToMastraMCPServers`) writes the latest
-     * non-2xx `{ status, body }` here; the discovery / reconnect catch reads
-     * `latest` to recover the HTTP status `@mastra/mcp` discards when a
-     * fallback-eligible connect fails. `undefined` for stdio servers and for
-     * remote servers when no capture map was threaded in.
-     */
-    httpErrorCapture?: HttpErrorCapture;
 }
 /**
  * Internal state for a single agent. Holds Mastra-specific instances so the
@@ -247,13 +237,13 @@ export interface MastraHarnessOptions {
      */
     innerFetch?: typeof fetch;
     /**
-     * Consumer-registered `LanguageModelV3` builders keyed by `providerHint`.
+     * Consumer-registered `LanguageModelV4` builders keyed by `providerHint`.
      * Forwarded from `MastraHarnessFactoryConfig.languageModelBuilders`. The
      * harness consults this map in `buildLanguageModel`'s `default` arm before
      * throwing `MODEL_NOT_SUPPORTED_BY_HARNESS`, so an injected builder can
      * handle a custom hint without editing the harness's internal switch.
      */
-    languageModelBuilders?: Readonly<Record<string, (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3>>;
+    languageModelBuilders?: Readonly<Record<string, (ctx: MastraLanguageModelBuilderContext) => LanguageModelV4>>;
     /**
      * Clock / sleep / RNG for the pre-first-token LLM retry loop (W-24236393), whose policy is
      * `PRE_FIRST_TOKEN_RETRY_OPTIONS`. Tests inject a no-sleep `sleep`.
@@ -514,7 +504,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      * non-empty paths.
      */
     /**
-     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV3` that
+     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV4` that
      * speaks the provider-native pass-through endpoint. The builder closes over
      * `getInfo` so within-shape `modelId` swaps, JWT rotations, and
      * premium-rate-limit gate flips land on the next outbound call without
@@ -588,8 +578,8 @@ export declare class MastraHarness implements MastraAgentHarness {
      * `agent.stream()` accepts.
      *
      * `text` parts collapse into text content blocks; `image` / `file` parts become v5 `file`
-     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra forwards to the
-     * gateway bridge, which collects them into `ChatMessageIn.files[]`. Pre-stream validation and the
+     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra normalizes to V4
+     * `file` parts for the provider pass-through translators. Pre-stream validation and the
      * input-part guard live in the SDK's {@link lowerStreamInput}, so file caps and the
      * `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics are identical to the Claude
      * harness; this method only supplies the Mastra-specific lowering of each part.
@@ -737,6 +727,14 @@ export declare class MastraHarness implements MastraAgentHarness {
      * after `shutdown()` has disposed the buses.
      */
     private prepareMcpStatusChange;
+    /**
+     * Surface the one MCP option this harness cannot honor. `@mastra/mcp` 2.x speaks the
+     * stateless 2026-07-28 protocol, has no SSE stream to resume, and dropped
+     * `reconnectionOptions`, so the mapper does not forward it; the Claude harness still does.
+     * Without this a consumer's tuning would silently stop applying on Mastra, so warn once per
+     * server definition that is (re)built.
+     */
+    private warnIfReconnectionOptionsIgnored;
     /**
      * Issue #591: install a `progress.onUpdate(serverName, ...)` listener
      * on the MCP client. Incoming `notifications/progress` are dispatched

package/dist/mastra-harness.js

@@ -21,13 +21,13 @@ import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/sc
 import { SessionContextStore, sortJsonValue } from './session-context-store.js';
 import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
 import { hasEnabledServers, mapToMastraMCPServers } from './mcp-config-mapper.js';
-import { buildMcpErrorDetail, sanitizeMcpErrorMessage, synthesizeHttpTransportError } from './mcp-error-classifier.js';
+import { buildMcpErrorDetail, errorFromDiscoveryDetails, sanitizeMcpErrorMessage } from './mcp-error-classifier.js';
 import { partitionPool, resolveAlwaysActive, } from './tool-search.js';
 import { validateMultimodalFiles } from '@salesforce/sfdx-agent-sdk';
 import { buildAnthropicDirectLanguageModel, buildAnthropicLanguageModel } from './pass-through-anthropic.js';
 import { buildOpenAIChatCompletionsLanguageModel } from './pass-through-openai-chat-completions.js';
 import { buildOpenAILanguageModel } from './pass-through-openai.js';
-import { readToolArgsRetryScope, TOOL_ARGS_RETRY_SCOPE_AGENT_ID, TOOL_ARGS_RETRY_SCOPE_PROVIDER, TOOL_ARGS_RETRY_SCOPE_THREAD_ID, } from './v3-stream-mapping.js';
+import { readToolArgsRetryScope, TOOL_ARGS_RETRY_SCOPE_AGENT_ID, TOOL_ARGS_RETRY_SCOPE_PROVIDER, TOOL_ARGS_RETRY_SCOPE_THREAD_ID, } from './stream-mapping.js';
 import { ToolResultRedactionProcessor } from './mastra-tool-result-redaction-processor.js';
 import { backfillCreatedAt, buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
 import { withPreFirstTokenRetry } from './retry-pre-first-token.js';
@@ -192,6 +192,33 @@ const DEFAULT_MCP_TIMEOUT_MS = 600_000;
  * factory/consumer knob — same posture as `resumeRpcTimeoutMs`, 6c).
  */
 const DEFAULT_IDLE_READ_TIMEOUT_MS = 120_000;
+// Issue #529 step 2c: the pre-#529 `ActiveRun` interface has been collapsed
+// into `MastraApprovalCoordinator`. The coordinator owns the per-turn pump
+// loop, the multi-source `fullStream` rotation, the per-tool-callId approval
+// timeouts, and the consumer-tool parker — all of which previously lived on
+// `ActiveRun` + `MastraStreamBroker` as two parallel state machines for the
+// same `(agentId, threadId)`. See `mastra-approval-coordinator.ts`.
+/**
+ * Resolve a failed MCP connect (the discovery catch and the `reconnectServer` catch share this) into what the
+ * harness records and emits: the error to report, its sanitized one-line message, and the structured
+ * {@link McpServerErrorDetail}. A server `@mastra/mcp` reports as `needs-auth` is surfaced as an OAuth
+ * requirement (`oauth-required`, non-retriable) regardless of the transport error it produced.
+ *
+ * The telemetry / log / status-change emits around the call differ between the two sites and stay at the
+ * call sites on purpose.
+ */
+function resolveMcpFailure(client, serverName, err) {
+    const oauthRequired = client.getServerAuthState(serverName) === 'needs-auth';
+    const effectiveError = oauthRequired
+        ? new (class UnauthorizedError extends Error {
+        })(sanitizeMcpErrorMessage(err))
+        : err;
+    return {
+        effectiveError,
+        message: sanitizeMcpErrorMessage(effectiveError),
+        errorDetail: buildMcpErrorDetail(effectiveError),
+    };
+}
 /**
  * Build the `Map<namespacedName, ToolSource>` index `resolveAlwaysActive`
  * needs to match `{ serverName }` / `{ serverName, toolName }` / `{ toolName }`
@@ -618,12 +645,9 @@ export class MastraHarness {
         const mcpAuthProviders = new Map(Object.entries(options?.mcpAuthProviders ?? {}).filter(([name]) => config.mcpServers?.[name]?.enabled !== false));
         if (hasEnabledServers(config.mcpServers)) {
             options?.abortSignal?.throwIfAborted();
-            // Empty capture map; the mapper creates a per-remote-server capture
-            // object and stores it here so we can attach each to its
-            // McpServerState below (W-23231658).
-            const httpErrorCaptures = new Map();
-            const enabledServers = mapToMastraMCPServers(config.mcpServers, config.orgJwt, this.innerFetch, httpErrorCaptures, options?.mcpAuthProviders, config.name);
+            const enabledServers = mapToMastraMCPServers(config.mcpServers, config.orgJwt, this.innerFetch, options?.mcpAuthProviders, config.name);
             for (const [serverName, serverDef] of Object.entries(enabledServers)) {
+                this.warnIfReconnectionOptionsIgnored(agentId, serverName, config.mcpServers[serverName]);
                 const client = new MCPClient({
                     id: `${agentId}:${serverName}`,
                     servers: { [serverName]: serverDef },
@@ -640,7 +664,6 @@ export class MastraHarness {
                     ready: Promise.resolve(),
                     settled: false,
                     tools: {},
-                    httpErrorCapture: httpErrorCaptures.get(serverName),
                 };
                 mcpServerStates.set(serverName, entry);
                 entry.ready = this.runMcpDiscovery(agentId, serverName, client, mcpServerStates, 0, options?.abortSignal);
@@ -955,11 +978,6 @@ export class MastraHarness {
             agentId,
             serverName,
         });
-        // W-23231658: clear any stale HTTP-error capture so a prior failure's
-        // status can't be mistaken for this reconnect's. The wrapper repopulates
-        // `latest` only if this reconnect's connect sees a non-2xx response.
-        if (serverState.httpErrorCapture)
-            serverState.httpErrorCapture.latest = undefined;
         // Transport-level reconnect can throw (stdio spawn failure, remote handshake
         // failure). Record on serverState and emit only `failed` (not started+failed
         // — `started` already fired above). This keeps the public contract
@@ -971,19 +989,12 @@ export class MastraHarness {
             // Drop telemetry + state writes if a newer epoch has superseded us.
             if (state.mcpServers.get(serverName)?.epoch !== epoch)
                 return;
-            // Prefer the captured HTTP status + body over the bodyless generic
-            // error `@mastra/mcp` rethrows on a fallback-eligible connect
-            // failure (W-23231658); same recovery as the discovery catch.
-            const captured = serverState.httpErrorCapture?.latest;
-            const oauthRequired = serverState.client.getServerAuthState(serverName) === 'needs-auth';
-            const effectiveError = oauthRequired
-                ? new (class UnauthorizedError extends Error {
-                })(sanitizeMcpErrorMessage(err))
-                : captured
-                    ? synthesizeHttpTransportError(captured.status, captured.body, err)
-                    : err;
-            const message = sanitizeMcpErrorMessage(effectiveError);
-            const errorDetail = buildMcpErrorDetail(effectiveError);
+            // `reconnectServer` rethrows the live error: the raw `SdkHttpError` /
+            // `SdkError` for a connected client, or a `MastraError` wrapping it once a
+            // prior connect failed. Either way the HTTP status / error code is on the
+            // error or its `cause` chain (W-23231658), which `buildMcpErrorDetail`
+            // reads directly.
+            const { effectiveError, message, errorDetail } = resolveMcpFailure(serverState.client, serverName, err);
             serverState.error = message;
             serverState.errorDetail = errorDetail;
             serverState.settled = true;
@@ -1104,9 +1115,8 @@ export class MastraHarness {
             ...state.mcpAuthProviders.keys(),
             ...Object.keys(nextProviders),
         ]);
-        const nextHttpErrorCaptures = new Map();
         const nextEnabledServers = hasEnabledServers(nextConfig)
-            ? mapToMastraMCPServers(nextConfig, config.orgJwt, this.innerFetch, nextHttpErrorCaptures, nextProviders, config.name)
+            ? mapToMastraMCPServers(nextConfig, config.orgJwt, this.innerFetch, nextProviders, config.name)
             : {};
         for (const name of allNames) {
             const prev = prevConfig[name];
@@ -1128,6 +1138,7 @@ export class MastraHarness {
             if (next && next.enabled !== false) {
                 const serverDef = nextEnabledServers[name];
                 if (serverDef) {
+                    this.warnIfReconnectionOptionsIgnored(agentId, name, next);
                     const client = new MCPClient({
                         id: `${agentId}:${name}`,
                         servers: { [name]: serverDef },
@@ -1140,7 +1151,6 @@ export class MastraHarness {
                         ready: Promise.resolve(),
                         settled: false,
                         tools: {},
-                        httpErrorCapture: nextHttpErrorCaptures.get(name),
                     };
                     state.mcpServers.set(name, entry);
                     if (nextProvider !== undefined) {
@@ -1550,7 +1560,7 @@ export class MastraHarness {
      * non-empty paths.
      */
     /**
-     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV3` that
+     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV4` that
      * speaks the provider-native pass-through endpoint. The builder closes over
      * `getInfo` so within-shape `modelId` swaps, JWT rotations, and
      * premium-rate-limit gate flips land on the next outbound call without
@@ -1671,9 +1681,9 @@ export class MastraHarness {
                 }));
             default: {
                 // Consult the injected builders map before throwing. This is the
-                // extension point for consumer-registered wire shapes (e.g. a temporary
-                // GovCloud chat/generations fallback, W-23560954). The builder receives
-                // the same context bag the built-in builders get.
+                // extension point for consumer-registered wire shapes (e.g. a bespoke
+                // gateway wire format). The builder receives the same context bag the
+                // built-in builders get.
                 const custom = this.languageModelBuilders?.[initial.providerHint];
                 if (custom) {
                     return this.wrapLanguageModel(custom({ getInfo, logBus, emitWireCommunication, innerFetch }));
@@ -1773,8 +1783,8 @@ export class MastraHarness {
      * `agent.stream()` accepts.
      *
      * `text` parts collapse into text content blocks; `image` / `file` parts become v5 `file`
-     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra forwards to the
-     * gateway bridge, which collects them into `ChatMessageIn.files[]`. Pre-stream validation and the
+     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra normalizes to V4
+     * `file` parts for the provider pass-through translators. Pre-stream validation and the
      * input-part guard live in the SDK's {@link lowerStreamInput}, so file caps and the
      * `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics are identical to the Claude
      * harness; this method only supplies the Mastra-specific lowering of each part.
@@ -2295,6 +2305,28 @@ export class MastraHarness {
             }
         };
     }
+    /**
+     * Surface the one MCP option this harness cannot honor. `@mastra/mcp` 2.x speaks the
+     * stateless 2026-07-28 protocol, has no SSE stream to resume, and dropped
+     * `reconnectionOptions`, so the mapper does not forward it; the Claude harness still does.
+     * Without this a consumer's tuning would silently stop applying on Mastra, so warn once per
+     * server definition that is (re)built.
+     */
+    warnIfReconnectionOptionsIgnored(agentId, serverName, serverConfig) {
+        if (serverConfig?.type !== 'remote' || serverConfig.reconnectionOptions === undefined)
+            return;
+        this.buses.emitLog({
+            level: 'warn',
+            message: `MCP server "${serverName}": reconnectionOptions is ignored by the Mastra harness`,
+            timestamp: this.clock.now(),
+            context: {
+                event_type: 'mcp-reconnection-options-ignored',
+                agentId,
+                serverName,
+                reason: '@mastra/mcp 2.x is stateless and has no reconnection options; only the Claude harness honors them',
+            },
+        });
+    }
     /**
      * Issue #591: install a `progress.onUpdate(serverName, ...)` listener
      * on the MCP client. Incoming `notifications/progress` are dispatched
@@ -2384,18 +2416,14 @@ export class MastraHarness {
             const s = serverStates.get(serverName);
             return s && s.epoch === epoch ? s : undefined;
         };
-        // W-23231658: clear any HTTP-error capture left from a prior discovery
-        // run on this (reused) client/capture so a stale status can't bleed into
-        // this run's failure classification. The wrapper repopulates `latest`
-        // only if a non-2xx response actually occurs during this connect.
-        const captureSlot = serverStates.get(serverName)?.httpErrorCapture;
-        if (captureSlot)
-            captureSlot.latest = undefined;
         return makeAbortable(client.listToolsetsWithErrors(), abortSignal)
-            .then(({ toolsets, errors }) => {
+            .then(({ toolsets, errors, errorDetails }) => {
             const serverError = errors[serverName];
             if (serverError) {
-                throw new Error(serverError);
+                // `errorDetails` keeps the HTTP status and deepest error code that the
+                // legacy per-server string drops (W-23231658); stubs without it fall
+                // back to the bare message.
+                throw errorFromDiscoveryDetails(errorDetails?.[serverName] ?? { message: serverError });
             }
             const tools = toolsets[serverName] ?? {};
             const namespacedTools = {};
@@ -2461,23 +2489,7 @@ export class MastraHarness {
                 // terminal telemetry — see the matching comment in the
                 // success path above (issue #373).
                 //
-                // W-23231658: when the remote transport captured a non-2xx
-                // HTTP response, prefer it over the bodyless generic error
-                // `@mastra/mcp` rethrows. The capture is only ever populated
-                // when a real HTTP error occurred on this server's transport,
-                // so by construction it IS the (or a) cause of this failure;
-                // the original `err` rides along as `cause` so its stack is
-                // preserved on the failed event.
-                const captured = s.httpErrorCapture?.latest;
-                const oauthRequired = s.client.getServerAuthState(serverName) === 'needs-auth';
-                const effectiveError = oauthRequired
-                    ? new (class UnauthorizedError extends Error {
-                    })(sanitizeMcpErrorMessage(err))
-                    : captured
-                        ? synthesizeHttpTransportError(captured.status, captured.body, err)
-                        : err;
-                const errorMessage = sanitizeMcpErrorMessage(effectiveError);
-                const errorDetail = buildMcpErrorDetail(effectiveError);
+                const { effectiveError, message: errorMessage, errorDetail, } = resolveMcpFailure(s.client, serverName, err);
                 s.error = errorMessage;
                 s.errorDetail = errorDetail;
                 s.settled = true;

package/dist/mcp-config-mapper.d.ts

@@ -6,23 +6,6 @@ import { type McpAuthProviders, type MCPConfiguration } from '@salesforce/sfdx-a
  * A server is considered enabled when its `enabled` property is `true` or absent.
  */
 export declare function hasEnabledServers(config: MCPConfiguration | undefined): config is MCPConfiguration;
-/** A captured non-2xx HTTP response from a remote MCP transport request. */
-export type CapturedHttpError = {
-    status: number;
-    body: string;
-};
-/**
- * Per-server mutable slot the remote-MCP fetch wrapper writes the latest
- * non-2xx response into. The harness reads `latest` in its discovery /
- * reconnect catch blocks to recover the HTTP status + body that
- * `@mastra/mcp`'s `connectHttp` discards when a fallback-eligible status
- * (`400` / `404` / `405`) triggers the SSE fallback and both transports fail —
- * the thrown `Error("Could not connect to server with any available HTTP
- * transport")` carries no status, no body, and no `cause` (W-23231658, #617).
- */
-export type HttpErrorCapture = {
-    latest?: CapturedHttpError;
-};
 /**
  * Converts our {@link MCPConfiguration} into the `servers` map expected by Mastra's `MCPClient`.
  *
@@ -34,10 +17,13 @@ export type HttpErrorCapture = {
  *   Mastra's `timeout` (post-connect request lifetime) and `connectTimeout` (initial transport
  *   handshake) so the configured value covers both phases — Mastra's hardcoded 3s
  *   `connectTimeout` default would otherwise abort cold-start handshakes before `timeout` applied.
- * - Per-server `reconnectionOptions` is forwarded to Mastra's `HttpServerDefinition.reconnectionOptions`
- *   (typed as `StreamableHTTPClientTransportOptions['reconnectionOptions']`). Unspecified fields
- *   are filled from {@link DEFAULT_RECONNECTION_OPTIONS} so partial overrides leave the rest at
- *   the MCP SDK's built-in defaults.
+ * - Every definition carries `clientInfo.name` from {@link resolveMcpClientName} (agent name, else
+ *   JWT feature id, else the SDK default — never the server-map key `@mastra/mcp` would default
+ *   to). Mastra sends it on `server/discover`, on every modern-era request, and on a legacy
+ *   `initialize`, for stdio and remote servers alike.
+ * - `MCPRemoteServerConfig.reconnectionOptions` is deliberately NOT forwarded: `@mastra/mcp` 2.x
+ *   speaks the stateless 2026-07-28 protocol, has no SSE stream to resume, and dropped the option.
+ *   The Claude harness still honors it. See the compile-time guard below.
  * - A supplied runtime OAuth provider is forwarded to the remote transport with the
  *   proxy-aware `innerFetch`; without one, `orgJwt` provides the existing JWT fetch.
  */
@@ -48,15 +34,6 @@ export declare function mapToMastraMCPServers(config: MCPConfiguration, orgJwt?:
  * here so MCP remote transports honor `HTTPS_PROXY` without `globalThis`
  * mutation. Stdio transports ignore it (they're child processes).
  */
-innerFetch?: typeof fetch, 
-/**
- * Optional per-server HTTP-error capture map. When supplied, every remote
- * server's transport fetch is wrapped so the latest non-2xx `{ status, body }`
- * is recorded into `captures.get(serverName)`. The harness reads this in its
- * discovery / reconnect catch to recover the status `@mastra/mcp` discards
- * (W-23231658). Stdio servers contribute no entry. Omitted in call sites
- * that don't need recovery (e.g. unit tests of the mapping shape).
- */
-captures?: Map<string, HttpErrorCapture>, providers?: McpAuthProviders, 
+innerFetch?: typeof fetch, providers?: McpAuthProviders, 
 /** AgentConfig.name; see {@link resolveMcpClientName}. */
 agentName?: string): Record<string, MastraMCPServerDefinition>;