@salesforce/sfdx-agent-harness-mastra 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 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.22.0] - 2026-06-22
+
+### Features
+- **agentic-common,harnesses**: route HTTPS_PROXY via injectable undici Dispatcher @W-23121596 ([#610](https://github.com/forcedotcom/agentic-dx/pull/610))
+
 ## [0.21.0] - 2026-06-19
 
 ### Features

package/README.md

@@ -54,6 +54,17 @@ Connectivity (model + provider auth) is supplied by the SDK's `AgentConnectivity
 direct-provider / LLMG Express api-key endpoints — both ship from `@salesforce/sfdx-agent-sdk`. The harness dispatches
 on `ModelConnectivityInfo.providerHint` internally to pick the right pass-through builder for each provider.
 
+#### HTTPS proxy routing
+
+The harness honors `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` (either casing) via
+`@salesforce/agentic-common`'s `resolveProxyDispatcher()`. When either proxy var is set at factory `create()` time, the
+harness wraps every in-process `fetch` call site (LLM gateway language-model builders + MCP remote transports) with an
+undici-backed routing function — no `globalThis` mutation. When no proxy env is set, `fetch` runs unwrapped (zero
+overhead).
+
+**Snapshot timing.** `HTTPS_PROXY` / `HTTP_PROXY` are captured at `create()` time and pinned for the harness's lifetime;
+`NO_PROXY` is re-evaluated per request. Set the proxy env vars before constructing the factory's first harness.
+
 ### Extension surface
 
 These types let consumers reach Mastra-specific features through the SDK's typed `extensions` slot. The SDK infers

package/dist/mastra-harness-factory.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { createProxyAwareFetch, resolveProxyDispatcher } from '@salesforce/agentic-common';
 import { MastraHarness } from './mastra-harness.js';
 const DEFAULT_TOOL_APPROVAL_TIMEOUT_MS = 600_000;
 /** Mastra-backed factory for creating AgentHarness instances. */
@@ -20,8 +21,10 @@ export class MastraHarnessFactory {
         this.config = config;
     }
     async create(storageRootFolder) {
+        const innerFetch = createProxyAwareFetch(resolveProxyDispatcher());
         return new MastraHarness(storageRootFolder, {
             toolApprovalTimeoutMs: this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS,
+            innerFetch,
         });
     }
 }

package/dist/mastra-harness.d.ts

@@ -197,6 +197,15 @@ export interface MastraHarnessOptions {
     clock?: Clock;
     idGenerator?: UniqueIDGenerator;
     toolApprovalTimeoutMs?: number;
+    /**
+     * Inner fetch the harness threads into every in-process HTTP call site
+     * (LLM gateway language-model builders + MCP remote transports). Defaults
+     * to `globalThis.fetch` when omitted. The harness factory builds a
+     * proxy-aware fetch via `createProxyAwareFetch(dispatcher)` once per
+     * `create()` and passes it here, so `HTTPS_PROXY` routing happens without
+     * any `globalThis` mutation.
+     */
+    innerFetch?: typeof fetch;
 }
 export declare class MastraHarness implements MastraAgentHarness {
     private readonly storageRootFolder;
@@ -229,6 +238,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly clock;
     private readonly idGenerator;
     private readonly toolApprovalTimeoutMs;
+    private readonly innerFetch;
     constructor(storageRootFolder: string, opts?: MastraHarnessOptions);
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -376,11 +376,13 @@ export class MastraHarness {
     clock;
     idGenerator;
     toolApprovalTimeoutMs;
+    innerFetch;
     constructor(storageRootFolder, opts = {}) {
         this.storageRootFolder = storageRootFolder;
         this.clock = opts.clock ?? new RealClock();
         this.idGenerator = opts.idGenerator ?? new UUIDGenerator();
         this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs ?? 600_000;
+        this.innerFetch = opts.innerFetch ?? globalThis.fetch;
         this.storage = new LibSQLStore({
             id: 'mastra-storage',
             url: `file:${this.storageRootFolder}/mastra.db`,
@@ -467,7 +469,7 @@ export class MastraHarness {
         const mcpServerStates = new Map();
         if (hasEnabledServers(config.mcpServers)) {
             options?.abortSignal?.throwIfAborted();
-            const enabledServers = mapToMastraMCPServers(config.mcpServers, config.orgJwt);
+            const enabledServers = mapToMastraMCPServers(config.mcpServers, config.orgJwt, this.innerFetch);
             for (const [serverName, serverDef] of Object.entries(enabledServers)) {
                 const client = new MCPClient({
                     id: `${agentId}:${serverName}`,
@@ -909,7 +911,7 @@ export class MastraHarness {
         const nextConfig = config.mcpServers ?? {};
         const allNames = new Set([...Object.keys(prevConfig), ...Object.keys(nextConfig)]);
         const nextEnabledServers = hasEnabledServers(nextConfig)
-            ? mapToMastraMCPServers(nextConfig, config.orgJwt)
+            ? mapToMastraMCPServers(nextConfig, config.orgJwt, this.innerFetch)
             : {};
         for (const name of allNames) {
             const prev = prevConfig[name];
@@ -1245,25 +1247,26 @@ export class MastraHarness {
                     throw err;
             }
         };
+        const innerFetch = this.innerFetch;
         switch (initial.providerHint) {
             case 'bedrock-anthropic':
                 // Salesforce LLM Gateway's `/invoke-with-response-stream` (Bedrock pass-through).
-                return buildAnthropicLanguageModel({ getInfo, logBus, emitWireCommunication });
+                return buildAnthropicLanguageModel({ getInfo, logBus, emitWireCommunication, 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 });
+                return buildAnthropicDirectLanguageModel({ getInfo, logBus, emitWireCommunication, 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 });
+                return buildOpenAILanguageModel({ getInfo, logBus, emitWireCommunication, 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 });
+                return buildOpenAIChatCompletionsLanguageModel({ getInfo, logBus, emitWireCommunication, innerFetch });
             default:
                 // Defensive — manager-side G8 should have caught this before
                 // we got here. Make the error typed so consumers can branch

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

@@ -24,4 +24,11 @@ export declare function hasEnabledServers(config: MCPConfiguration | undefined):
  * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
  *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
  */
-export declare function mapToMastraMCPServers(config: MCPConfiguration, orgJwt?: JSONWebToken): Record<string, MastraMCPServerDefinition>;
+export declare function mapToMastraMCPServers(config: MCPConfiguration, orgJwt?: JSONWebToken, 
+/**
+ * Inner fetch routed through the harness's `Dispatcher`. Defaults to
+ * `globalThis.fetch`; the harness factory threads a proxy-aware fetch
+ * here so MCP remote transports honor `HTTPS_PROXY` without `globalThis`
+ * mutation. Stdio transports ignore it (they're child processes).
+ */
+innerFetch?: typeof fetch): Record<string, MastraMCPServerDefinition>;

package/dist/mcp-config-mapper.js

@@ -44,7 +44,14 @@ const DEFAULT_RECONNECTION_OPTIONS = {
  * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
  *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
  */
-export function mapToMastraMCPServers(config, orgJwt) {
+export function mapToMastraMCPServers(config, orgJwt, 
+/**
+ * Inner fetch routed through the harness's `Dispatcher`. Defaults to
+ * `globalThis.fetch`; the harness factory threads a proxy-aware fetch
+ * here so MCP remote transports honor `HTTPS_PROXY` without `globalThis`
+ * mutation. Stdio transports ignore it (they're child processes).
+ */
+innerFetch = globalThis.fetch) {
     const result = {};
     for (const [name, serverConfig] of Object.entries(config)) {
         if (serverConfig.enabled === false) {
@@ -73,7 +80,7 @@ export function mapToMastraMCPServers(config, orgJwt) {
                 ...(serverConfig.headers !== undefined && {
                     requestInit: { headers: serverConfig.headers },
                 }),
-                ...(orgJwt && { fetch: createAuthFetch(serverConfig.url, orgJwt, serverConfig.headers) }),
+                ...(orgJwt && { fetch: createAuthFetch(serverConfig.url, orgJwt, innerFetch, serverConfig.headers) }),
                 ...(serverConfig.timeout !== undefined && {
                     timeout: serverConfig.timeout,
                     connectTimeout: serverConfig.timeout,
@@ -99,14 +106,14 @@ export function mapToMastraMCPServers(config, orgJwt) {
     }
     return result;
 }
-function createAuthFetch(serverUrl, orgJwt, existingHeaders) {
+function createAuthFetch(serverUrl, orgJwt, innerFetch, existingHeaders) {
     return async (url, init) => {
         const authHeaders = await resolveMcpServerHeaders(serverUrl, orgJwt, existingHeaders);
         const merged = new Headers(init?.headers);
         for (const [key, value] of Object.entries(authHeaders)) {
             merged.set(key, value);
         }
-        return globalThis.fetch(url, { ...init, headers: merged });
+        return innerFetch(url, { ...init, headers: merged });
     };
 }
 //# sourceMappingURL=mcp-config-mapper.js.map

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

@@ -20,6 +20,13 @@ export declare function buildAnthropicLanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    /**
+     * Inner fetch routed through the harness's `Dispatcher` (built from
+     * `HTTPS_PROXY` / `HTTP_PROXY` or a consumer-supplied one). Defaults to
+     * `globalThis.fetch` so unit tests that don't care about proxy routing
+     * don't need to thread it.
+     */
+    innerFetch?: typeof fetch;
 }): LanguageModelV3;
 /**
  * Builds the in-process `LanguageModelV3` impl for direct-Anthropic API access
@@ -44,6 +51,8 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    /** See {@link buildAnthropicLanguageModel} `innerFetch`. */
+    innerFetch?: typeof fetch;
 }): LanguageModelV3;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into Anthropic's Messages API shape

package/dist/pass-through-anthropic.js

@@ -20,7 +20,7 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, mapAnthropicFinish
  * the next request.
  */
 export function buildAnthropicLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication } = opts;
+    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
     const initialInfo = getInfo();
     const ctx = {
         getInfo,
@@ -32,7 +32,7 @@ export function buildAnthropicLanguageModel(opts) {
             // 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)),
+            fetch: createGatewayFetch(() => info.getHeaders(), buildWireHooks(ctx), innerFetch),
         }),
     };
     return {
@@ -68,7 +68,7 @@ export function buildAnthropicLanguageModel(opts) {
  * language model.
  */
 export function buildAnthropicDirectLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication } = opts;
+    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
     const initialInfo = getInfo();
     const ctx = {
         getInfo,
@@ -85,7 +85,7 @@ export function buildAnthropicDirectLanguageModel(opts) {
         new Anthropic({
             apiKey: 'anthropic-direct-resolver-managed',
             baseURL: info.baseUrl,
-            fetch: createGatewayFetch(() => translateBearerToXApiKey(info), buildWireHooks(ctx)),
+            fetch: createGatewayFetch(() => translateBearerToXApiKey(info), buildWireHooks(ctx), innerFetch),
         }),
     };
     return {

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

@@ -26,6 +26,8 @@ export declare function buildOpenAIChatCompletionsLanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    /** See `buildAnthropicLanguageModel` `innerFetch`. */
+    innerFetch?: typeof fetch;
 }): LanguageModelV3;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into the OpenAI Chat Completions

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

@@ -25,15 +25,16 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, mapOpenAIUsage, to
  * without rebuilding the language model.
  */
 export function buildOpenAIChatCompletionsLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication } = opts;
+    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
     const initialInfo = getInfo();
+    const ctx = { getInfo, logBus, emitWireCommunication, innerFetch };
     return {
         specificationVersion: 'v3',
         provider: 'openai-compatible-chat-completions-pass-through',
         modelId: initialInfo.nativeModelId,
         supportedUrls: {},
-        doGenerate: (options) => doGenerate({ getInfo, logBus, emitWireCommunication }, options),
-        doStream: (options) => doStream({ getInfo, logBus, emitWireCommunication }, options),
+        doGenerate: (options) => doGenerate(ctx, options),
+        doStream: (options) => doStream(ctx, options),
     };
 }
 /**
@@ -53,7 +54,7 @@ async function buildRequest(ctx, options) {
         // request. The SDK still wants a non-empty `apiKey` at construction;
         // an opaque sentinel keeps it from reading `process.env['OPENAI_API_KEY']`.
         apiKey: 'openai-compatible-resolver-managed',
-        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks),
+        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks, ctx.innerFetch),
     });
     const messages = translatePromptToChatCompletions(options.prompt);
     const tools = translateToolsToChatCompletions(options);

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

@@ -18,6 +18,8 @@ export declare function buildOpenAILanguageModel(opts: {
     getInfo: () => ModelConnectivityInfo;
     logBus?: LogBus;
     emitWireCommunication?: (event: WireCommunicationEvent) => void;
+    /** See `buildAnthropicLanguageModel` `innerFetch`. */
+    innerFetch?: typeof fetch;
 }): LanguageModelV3;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into OpenAI's Responses input shape:

package/dist/pass-through-openai.js

@@ -17,8 +17,9 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, mapOpenAIFinishRea
  * next request.
  */
 export function buildOpenAILanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication } = opts;
+    const { getInfo, logBus, emitWireCommunication, innerFetch } = opts;
     const initialInfo = getInfo();
+    const ctx = { getInfo, logBus, emitWireCommunication, innerFetch };
     return {
         specificationVersion: 'v3',
         provider: 'salesforce-llm-gateway-pass-through-openai',
@@ -27,8 +28,8 @@ export function buildOpenAILanguageModel(opts) {
         // bag inside `commonParams.model`.
         modelId: initialInfo.nativeModelId,
         supportedUrls: {},
-        doGenerate: (options) => doGenerate({ getInfo, logBus, emitWireCommunication }, options),
-        doStream: (options) => doStream({ getInfo, logBus, emitWireCommunication }, options),
+        doGenerate: (options) => doGenerate(ctx, options),
+        doStream: (options) => doStream(ctx, options),
     };
 }
 /**
@@ -53,7 +54,7 @@ async function buildOpenAIRequest(ctx, options) {
         // Re-evaluates `getHeaders()` per outbound call so JWT rotation /
         // premium-rate-limit gate flips / BYOK provider rotation land on the
         // next request without rebuilding this bridge.
-        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks),
+        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks, ctx.innerFetch),
     });
     const { input, instructions } = translatePromptToOpenAI(options.prompt);
     const tools = translateToolsToOpenAI(options);

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

@@ -182,11 +182,17 @@ export type GatewayFetchWireHooks = {
     clock?: Clock;
 };
 /**
- * Wraps `globalThis.fetch` with a per-request header merger. The `getHeaders`
- * argument may be sync or async — `ModelConnectivityInfo.getHeaders` returns a
- * `Promise<Record<string, string>>` so JWT freshness, premium-rate-limit gate
- * flips, and per-call rotating credentials all land on the next outbound call
- * without rebuilding the fetch wrapper.
+ * Wraps an `innerFetch` (defaults to `globalThis.fetch`) with a per-request
+ * header merger. The `getHeaders` argument may be sync or async —
+ * `ModelConnectivityInfo.getHeaders` returns a `Promise<Record<string, string>>`
+ * so JWT freshness, premium-rate-limit gate flips, and per-call rotating
+ * credentials all land on the next outbound call without rebuilding the
+ * fetch wrapper.
+ *
+ * The `innerFetch` arg is what makes proxy support compose: the harness
+ * factory builds a proxy-aware fetch via `createProxyAwareFetch(dispatcher)`
+ * once per `create()` and passes it through, so this wrapper inherits the
+ * dispatcher without any `globalThis` mutation.
  *
  * When `wireHooks` is supplied, every outbound call emits one
  * `WireCommunicationEvent` `request` event and one `response` event onto the
@@ -197,7 +203,7 @@ export type GatewayFetchWireHooks = {
  * <n> }` so wire-communication captures don't blow the consumer's log file
  * budget.
  */
-export declare function createGatewayFetch(getHeaders: () => Record<string, string> | Promise<Record<string, string>>, wireHooks?: GatewayFetchWireHooks): typeof fetch;
+export declare function createGatewayFetch(getHeaders: () => Record<string, string> | Promise<Record<string, string>>, wireHooks?: GatewayFetchWireHooks, innerFetch?: typeof fetch): typeof fetch;
 /**
  * The `WireCommunicationEvent` shape from `@salesforce/sfdx-agent-sdk` minus the
  * harness-injected fields. Kept structural so this module doesn't import

package/dist/v3-stream-mapping.js

@@ -223,11 +223,17 @@ export function mapOpenAIUsage(usage) {
     };
 }
 /**
- * Wraps `globalThis.fetch` with a per-request header merger. The `getHeaders`
- * argument may be sync or async — `ModelConnectivityInfo.getHeaders` returns a
- * `Promise<Record<string, string>>` so JWT freshness, premium-rate-limit gate
- * flips, and per-call rotating credentials all land on the next outbound call
- * without rebuilding the fetch wrapper.
+ * Wraps an `innerFetch` (defaults to `globalThis.fetch`) with a per-request
+ * header merger. The `getHeaders` argument may be sync or async —
+ * `ModelConnectivityInfo.getHeaders` returns a `Promise<Record<string, string>>`
+ * so JWT freshness, premium-rate-limit gate flips, and per-call rotating
+ * credentials all land on the next outbound call without rebuilding the
+ * fetch wrapper.
+ *
+ * The `innerFetch` arg is what makes proxy support compose: the harness
+ * factory builds a proxy-aware fetch via `createProxyAwareFetch(dispatcher)`
+ * once per `create()` and passes it through, so this wrapper inherits the
+ * dispatcher without any `globalThis` mutation.
  *
  * When `wireHooks` is supplied, every outbound call emits one
  * `WireCommunicationEvent` `request` event and one `response` event onto the
@@ -238,7 +244,7 @@ export function mapOpenAIUsage(usage) {
  * <n> }` so wire-communication captures don't blow the consumer's log file
  * budget.
  */
-export function createGatewayFetch(getHeaders, wireHooks) {
+export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThis.fetch) {
     return async (input, init) => {
         const resolved = await getHeaders();
         // Per WHATWG Fetch, `init.headers` is `HeadersInit = Headers | Record<string, string> | [string, string][]`.
@@ -253,7 +259,7 @@ export function createGatewayFetch(getHeaders, wireHooks) {
         }
         const finalInit = { ...init, headers: finalHeaders };
         if (!wireHooks) {
-            return globalThis.fetch(input, finalInit);
+            return innerFetch(input, finalInit);
         }
         const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
         const method = (finalInit.method ?? 'GET').toUpperCase();
@@ -270,7 +276,7 @@ export function createGatewayFetch(getHeaders, wireHooks) {
             body: tryDecodeBody(finalInit.body),
         });
         try {
-            const response = await globalThis.fetch(input, finalInit);
+            const response = await innerFetch(input, finalInit);
             wireHooks.emitWireCommunication({
                 type: 'llm-response',
                 timestamp: clock.now(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -36,15 +36,15 @@
     "@mastra/mcp": "^1.10.0",
     "@mastra/memory": "^1.20.3",
     "@mastra/schema-compat": "^1.2.11",
-    "@salesforce/agentic-common": "0.11.0",
+    "@salesforce/agentic-common": "0.12.0",
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.22.0"
+    "@salesforce/sfdx-agent-sdk": "0.23.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.22.0",
+    "@salesforce/sfdx-agent-sdk": "0.23.0",
     "@types/node": "^22.19.21",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.20",