@salesforce/sfdx-agent-harness-mastra 0.49.0 → 0.51.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.51.0] - 2026-08-24
+
+### Features
+- **agent-sdk,harness-claude,harness-mastra,harness-openai**: support OAuth authProvider on remote MCP servers @W-23939243@ ([#757](https://github.com/forcedotcom/agentic-dx/pull/757))
+
+## [0.50.0] - 2026-08-18
+
+### Chores
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#754](https://github.com/forcedotcom/agentic-dx/pull/754))
+- **deps-dev**: bump the dev-dependencies group with 2 updates ([#753](https://github.com/forcedotcom/agentic-dx/pull/753))
+
 ## [0.49.0] - 2026-08-17
 
 ### Features

package/dist/mastra-harness.d.ts

@@ -1,7 +1,7 @@
 import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { MCPClient } from '@mastra/mcp';
-import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
+import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type McpAuthProviders, type ModelConnectivityInfo, type SessionContext, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import type { MastraLanguageModelBuilderContext } from './index.js';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
@@ -108,6 +108,7 @@ interface MastraAgentState {
     mcpServers: Map<string, McpServerState>;
     /** Original MCP configuration, retained so getMcpServerInfo can report disabled servers. */
     mcpConfig?: MCPConfiguration;
+    mcpAuthProviders: Map<string, McpAuthProviders[string]>;
     /** Mastra Workspace providing built-in file tools to the agent. */
     mastraWorkspace?: Workspace;
     /**
@@ -319,6 +320,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
+        mcpAuthProviders?: McpAuthProviders;
     }): Promise<void>;
     /**
      * @requirements
@@ -366,6 +368,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
+        mcpAuthProviders?: McpAuthProviders;
     }): Promise<void>;
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -510,13 +510,14 @@ export class MastraHarness {
         const composedInstructions = await composeInstructionsWithRules(config.instructions, config.rules);
         // ── MCP setup (non-blocking, per-server) ──────────────────────────
         const mcpServerStates = new Map();
+        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);
+            const enabledServers = mapToMastraMCPServers(config.mcpServers, config.orgJwt, this.innerFetch, httpErrorCaptures, options?.mcpAuthProviders);
             for (const [serverName, serverDef] of Object.entries(enabledServers)) {
                 const client = new MCPClient({
                     id: `${agentId}:${serverName}`,
@@ -694,6 +695,7 @@ export class MastraHarness {
                 validateFiles,
                 mcpServers: mcpServerStates,
                 mcpConfig: config.mcpServers,
+                mcpAuthProviders,
                 mastraWorkspace,
                 coordinators: new Map(),
                 consumerToolNames,
@@ -866,7 +868,13 @@ export class MastraHarness {
             // error `@mastra/mcp` rethrows on a fallback-eligible connect
             // failure (W-23231658); same recovery as the discovery catch.
             const captured = serverState.httpErrorCapture?.latest;
-            const effectiveError = captured ? synthesizeHttpTransportError(captured.status, captured.body, err) : err;
+            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);
             serverState.error = message;
@@ -982,16 +990,23 @@ export class MastraHarness {
         // ── Phase 1: MCP diff against state.mcpConfig ─────────────────────
         const prevConfig = state.mcpConfig ?? {};
         const nextConfig = config.mcpServers ?? {};
-        const allNames = new Set([...Object.keys(prevConfig), ...Object.keys(nextConfig)]);
+        const nextProviders = options?.mcpAuthProviders ?? {};
+        const allNames = new Set([
+            ...Object.keys(prevConfig),
+            ...Object.keys(nextConfig),
+            ...state.mcpAuthProviders.keys(),
+            ...Object.keys(nextProviders),
+        ]);
         const nextHttpErrorCaptures = new Map();
         const nextEnabledServers = hasEnabledServers(nextConfig)
-            ? mapToMastraMCPServers(nextConfig, config.orgJwt, this.innerFetch, nextHttpErrorCaptures)
+            ? mapToMastraMCPServers(nextConfig, config.orgJwt, this.innerFetch, nextHttpErrorCaptures, nextProviders)
             : {};
         for (const name of allNames) {
             const prev = prevConfig[name];
             const next = nextConfig[name];
-            if (mcpServerConfigEqual(prev, next))
+            if (mcpServerConfigEqual(prev, next) && state.mcpAuthProviders.get(name) === nextProviders[name])
                 continue;
+            const nextProvider = nextProviders[name];
             // Tear down whatever was previously attached for this name. Both
             // "removed" and "changed" go through this branch; "added" hits no
             // previous entry so the disconnect is a no-op.
@@ -1001,6 +1016,7 @@ export class MastraHarness {
                 await prevEntry.ready.catch(() => undefined);
                 await prevEntry.client.disconnect().catch(() => undefined);
             }
+            state.mcpAuthProviders.delete(name);
             // Connect the new one if the next config has it enabled.
             if (next && next.enabled !== false) {
                 const serverDef = nextEnabledServers[name];
@@ -1020,6 +1036,9 @@ export class MastraHarness {
                         httpErrorCapture: nextHttpErrorCaptures.get(name),
                     };
                     state.mcpServers.set(name, entry);
+                    if (nextProvider !== undefined) {
+                        state.mcpAuthProviders.set(name, nextProvider);
+                    }
                     entry.ready = this.runMcpDiscovery(agentId, name, client, state.mcpServers, 0, options?.abortSignal);
                     // Issue #591: same MCP-progress wiring as createAgent path.
                     this.registerMcpProgressListener(agentId, name, client);
@@ -2042,9 +2061,13 @@ export class MastraHarness {
                 // the original `err` rides along as `cause` so its stack is
                 // preserved on the failed event.
                 const captured = s.httpErrorCapture?.latest;
-                const effectiveError = captured
-                    ? synthesizeHttpTransportError(captured.status, captured.body, err)
-                    : err;
+                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);
                 s.error = errorMessage;

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

@@ -1,6 +1,6 @@
 import type { MastraMCPServerDefinition } from '@mastra/mcp';
 import type { JSONWebToken } from '@salesforce/agentic-common';
-import { type MCPConfiguration } from '@salesforce/sfdx-agent-sdk';
+import { type McpAuthProviders, type MCPConfiguration } from '@salesforce/sfdx-agent-sdk';
 /**
  * Returns `true` if `config` contains at least one server that is not explicitly disabled.
  * A server is considered enabled when its `enabled` property is `true` or absent.
@@ -38,8 +38,8 @@ export type HttpErrorCapture = {
  *   (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.
- * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
- *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
+ * - A supplied runtime OAuth provider is forwarded to the remote transport with the
+ *   proxy-aware `innerFetch`; without one, `orgJwt` provides the existing JWT fetch.
  */
 export declare function mapToMastraMCPServers(config: MCPConfiguration, orgJwt?: JSONWebToken, 
 /**
@@ -57,4 +57,4 @@ innerFetch?: typeof fetch,
  * (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>): Record<string, MastraMCPServerDefinition>;
+captures?: Map<string, HttpErrorCapture>, providers?: McpAuthProviders): Record<string, MastraMCPServerDefinition>;

package/dist/mcp-config-mapper.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { resolveMcpServerHeaders } from '@salesforce/sfdx-agent-sdk';
+import { resolveMcpServerHeaders, } from '@salesforce/sfdx-agent-sdk';
 /**
  * Returns `true` if `config` contains at least one server that is not explicitly disabled.
  * A server is considered enabled when its `enabled` property is `true` or absent.
@@ -48,8 +48,8 @@ const DEFAULT_RECONNECTION_OPTIONS = {
  *   (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.
- * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
- *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
+ * - A supplied runtime OAuth provider is forwarded to the remote transport with the
+ *   proxy-aware `innerFetch`; without one, `orgJwt` provides the existing JWT fetch.
  */
 export function mapToMastraMCPServers(config, orgJwt, 
 /**
@@ -67,7 +67,7 @@ innerFetch = globalThis.fetch,
  * (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) {
+captures, providers = {}) {
     const result = {};
     for (const [name, serverConfig] of Object.entries(config)) {
         if (serverConfig.enabled === false) {
@@ -91,9 +91,8 @@ captures) {
         }
         else if (serverConfig.type === 'remote') {
             const url = serverConfig.url instanceof URL ? serverConfig.url : new URL(serverConfig.url);
-            // Base transport fetch: auth-injecting when an orgJwt is present,
-            // otherwise the bare inner (proxy-aware) fetch.
-            const baseFetch = orgJwt
+            const provider = providers[name];
+            const baseFetch = provider === undefined && orgJwt
                 ? createAuthFetch(serverConfig.url, orgJwt, innerFetch, serverConfig.headers)
                 : innerFetch;
             // Wrap with HTTP-error capture when the harness asked for it, so a
@@ -111,13 +110,14 @@ captures) {
                 transportFetch = wrapFetchWithErrorCapture(baseFetch, capture);
             }
             else {
-                transportFetch = orgJwt ? baseFetch : undefined;
+                transportFetch = orgJwt || provider !== undefined ? baseFetch : undefined;
             }
             const def = {
                 url,
                 ...(serverConfig.headers !== undefined && {
                     requestInit: { headers: serverConfig.headers },
                 }),
+                ...(provider !== undefined && { authProvider: provider }),
                 ...(transportFetch && { fetch: transportFetch }),
                 ...(serverConfig.timeout !== undefined && {
                     timeout: serverConfig.timeout,

package/dist/mcp-error-classifier.d.ts

@@ -17,11 +17,13 @@ export declare function sanitizeMcpErrorMessage(err: unknown): string;
  *
  *  1. `DOMException` `AbortError` and Node's `code === 'ABORT_ERR'` map to
  *     `'aborted'` regardless of the `.message`.
- *  2. MCP-shaped errors (an `Error` carrying a numeric `code`, see
+ *  2. MCP SDK `UnauthorizedError` maps to `'oauth-required'` so the host can
+ *     complete consumer-owned authorization before reconnecting.
+ *  3. MCP-shaped errors (an `Error` carrying a numeric `code`, see
  *     {@link isMcpErrorLike}) match by code: a positive code in `[100, 599]` is
  *     an HTTP status (see {@link categoryForHttpStatus}); a negative code is a
  *     JSON-RPC 2.0 error (`-32001` etc.).
- *  3. Free-form `.message` text is matched against substrings the underlying
+ *  4. Free-form `.message` text is matched against substrings the underlying
  *     transports surface (`401`, `403`, `5xx`, `ECONNREFUSED`, etc.). This is
  *     intentionally a small lookup — categories are stable, message shapes
  *     are not, so the heuristic stays narrow and falls back to `'unknown'`.

package/dist/mcp-error-classifier.js

@@ -23,6 +23,9 @@ import { getErrorMessage, isAbortError } from '@salesforce/agentic-common';
 function isMcpErrorLike(err) {
     return err instanceof Error && typeof err.code === 'number';
 }
+function isOAuthRequiredError(err) {
+    return err instanceof Error && err.constructor.name === 'UnauthorizedError';
+}
 /**
  * Strip V8 stack frames ("    at <frame>") and any framing that arrived inside
  * the message string. The result is a single, human-readable summary line safe
@@ -74,11 +77,13 @@ function categoryForHttpStatus(status) {
  *
  *  1. `DOMException` `AbortError` and Node's `code === 'ABORT_ERR'` map to
  *     `'aborted'` regardless of the `.message`.
- *  2. MCP-shaped errors (an `Error` carrying a numeric `code`, see
+ *  2. MCP SDK `UnauthorizedError` maps to `'oauth-required'` so the host can
+ *     complete consumer-owned authorization before reconnecting.
+ *  3. MCP-shaped errors (an `Error` carrying a numeric `code`, see
  *     {@link isMcpErrorLike}) match by code: a positive code in `[100, 599]` is
  *     an HTTP status (see {@link categoryForHttpStatus}); a negative code is a
  *     JSON-RPC 2.0 error (`-32001` etc.).
- *  3. Free-form `.message` text is matched against substrings the underlying
+ *  4. Free-form `.message` text is matched against substrings the underlying
  *     transports surface (`401`, `403`, `5xx`, `ECONNREFUSED`, etc.). This is
  *     intentionally a small lookup — categories are stable, message shapes
  *     are not, so the heuristic stays narrow and falls back to `'unknown'`.
@@ -86,6 +91,8 @@ function categoryForHttpStatus(status) {
 export function classifyMcpError(err) {
     if (isAbortError(err))
         return 'aborted';
+    if (isOAuthRequiredError(err))
+        return 'oauth-required';
     if (isMcpErrorLike(err)) {
         // HTTP status (positive, 100–599) before the JSON-RPC switch — the two
         // code spaces are disjoint (JSON-RPC codes are negative), so an HTTP
@@ -125,8 +132,8 @@ export function classifyMcpError(err) {
 }
 /**
  * Whether the SDK considers the failure transient (worth a retry via
- * `Agent.reconnectMcpServer` / `Agent.refreshMcpAuth`). Aborted operations and
- * permanent protocol violations are non-retriable; everything else is retriable
+ * `Agent.reconnectMcpServer`). Aborted operations and
+ * permanent protocol violations and interactive OAuth requirements are non-retriable; everything else is retriable
  * by default — failing-open here is correct because the consumer always has
  * the option to ignore the hint.
  */
@@ -135,6 +142,7 @@ function isCategoryRetriable(category) {
         case 'aborted':
         case 'protocol-error':
         case 'config-error':
+        case 'oauth-required':
             return false;
         default:
             return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -42,27 +42,27 @@
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.50.0"
+    "@salesforce/sfdx-agent-sdk": "0.52.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.50.0",
+    "@salesforce/sfdx-agent-sdk": "0.52.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.26",
-    "eslint": "^10.8.0",
+    "eslint": "^10.8.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-n": "^18.2.2",
+    "eslint-plugin-n": "^18.3.0",
     "globals": "^17.9.0",
     "lint-staged": "^17.3.0",
     "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "tsx": "^4.23.5",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
-    "typescript-eslint": "^8.66.0",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.8"
   },
   "engines": {