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

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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
+- **BREAKING** Major refactor to Unify Connectivity via ModelConnectivityInfo @W-22782317 ([#607](https://github.com/forcedotcom/agentic-dx/pull/607))
+
+### Chores
+- **deps-dev**: bump @vitest/eslint-plugin from 1.6.19 to 1.6.20 in the vitest group across 1 directory ([#601](https://github.com/forcedotcom/agentic-dx/pull/601))
+- **deps-dev**: bump eslint from 10.4.1 to 10.5.0 in the eslint group across 1 directory ([#600](https://github.com/forcedotcom/agentic-dx/pull/600))
+- **deps**: bump the mastra group across 1 directory with 4 updates ([#602](https://github.com/forcedotcom/agentic-dx/pull/602))
+- **deps-dev**: bump @types/node from 22.19.20 to 22.19.21 in the dev-dependencies group ([#599](https://github.com/forcedotcom/agentic-dx/pull/599))
+
 ## [0.20.0] - 2026-06-15
 
 ### Fixes

package/README.md

@@ -44,15 +44,26 @@ Linux and macOS release the handle eagerly; the retry options are no-ops on thos
 
 ### Core
 
-| Export                                | Kind      | Description                                                                                                                                                                            |
-| ------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                                                 |
-| `MastraHarnessFactoryConfig`          | interface | Configuration for `MastraHarnessFactory` (`modelConfigFactory?`, `toolApprovalTimeoutMs?`).                                                                                            |
-| `MastraModelConfigFactory`            | interface | Strategy for creating model configurations; injected into `MastraHarnessFactory`.                                                                                                      |
-| `ResolvedModelConfig`                 | type      | Return type of `MastraModelConfigFactory.create()` — a `MastraModelConfig` plus a `validateFiles(files)` hook the harness calls for pre-flight multimodal (`image`/`file`) validation. |
-| `DefaultMastraModelConfigFactory`     | class     | Default factory using the Salesforce LLM Gateway (`SalesforceMastraModelGateway`).                                                                                                     |
-| `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).                                                                                                   |
-| `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`).                                                                                              |
+| Export                       | Kind      | Description                                                                            |
+| ---------------------------- | --------- | -------------------------------------------------------------------------------------- |
+| `MastraHarnessFactory`       | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root. |
+| `MastraHarnessFactoryConfig` | interface | Configuration for `MastraHarnessFactory` (`toolApprovalTimeoutMs?`).                   |
+
+Connectivity (model + provider auth) is supplied by the SDK's `AgentConnectivityResolver`. Use the bundled
+`DefaultAgentConnectivityResolver` for the standard Salesforce LLM Gateway path, or `ApiKeyConnectivityResolver` for
+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
 
@@ -236,19 +247,20 @@ contract.
 
 ### Using LLM Gateway Express
 
+LLMG Express, Anthropic-direct, OpenAI-direct, and any other api-key endpoint flow through the SDK's
+`ApiKeyConnectivityResolver` (no harness-specific factory needed):
+
 ```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { MastraHarnessFactory, LLMGExpressMastraModelConfigFactory } from '@salesforce/sfdx-agent-harness-mastra';
+import { ApiKeyConnectivityResolver, createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
 
-const harnessFactory = new MastraHarnessFactory({
-  modelConfigFactory: new LLMGExpressMastraModelConfigFactory({
-    apiKey: process.env.LLMG_EXPRESS_API_KEY!,
+const manager = await createAgentManager('/path/to/storage', new MastraHarnessFactory(), {
+  connectivityResolver: new ApiKeyConnectivityResolver({
+    getApiKey: () => process.env.LLMG_EXPRESS_API_KEY!,
     baseUrl: process.env.LLMG_EXPRESS_BASE_URL!,
-    modelId: 'claude-sonnet-4-20250514',
+    providerHint: 'openai-compatible',
   }),
 });
-
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
 ```
 
 ## Development

package/dist/index.d.ts

@@ -1,6 +1,3 @@
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
 export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
-export type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
-export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
-export { LLMGExpressMastraModelConfigFactory, type LLMGExpressConfig } from './llmg-express-model-config-factory.js';

package/dist/index.js

@@ -4,6 +4,11 @@
  */
 export { MastraHarnessFactory } from './mastra-harness-factory.js';
 export {} from './tool-search.js';
-export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
-export { LLMGExpressMastraModelConfigFactory } from './llmg-express-model-config-factory.js';
+// Mastra drives requests through provider-native pass-through endpoints —
+// Bedrock-Anthropic, direct Anthropic Messages API, OpenAI Responses, and
+// OpenAI Chat Completions (LLMG Express / openai-compatible) — dispatched on
+// the connectivity resolver's `ModelConnectivityInfo.providerHint`. There's
+// no consumer-facing knob for switching the wire path; the resolver drives
+// it. For BYOK / direct-Anthropic / LLMG-Express deployments use
+// `ApiKeyConnectivityResolver` from `@salesforce/sfdx-agent-sdk`.
 //# sourceMappingURL=index.js.map

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

@@ -1,13 +1,6 @@
-import type { HarnessFactory } from '@salesforce/sfdx-agent-sdk';
+import type { HarnessFactory, ProviderHint } from '@salesforce/sfdx-agent-sdk';
 import { type MastraAgentHarness } from './mastra-harness.js';
-import type { MastraModelConfigFactory } from './model-config-factory.js';
 export interface MastraHarnessFactoryConfig {
-    /**
-     * Strategy for resolving the Mastra model configuration. Defaults to
-     * `DefaultMastraModelConfigFactory`, which targets the standard LLM
-     * Gateway path.
-     */
-    modelConfigFactory?: MastraModelConfigFactory;
     /**
      * How long to wait for a `requireToolApproval` consumer to call
      * `approveToolCall` / `declineToolCall` before auto-denying via
@@ -23,6 +16,7 @@ export declare class MastraHarnessFactory implements HarnessFactory<MastraAgentH
     private readonly config;
     readonly harnessId = "mastra";
     readonly protocolVersion = 1;
+    readonly supportedProviderHints: readonly ProviderHint[];
     constructor(config?: MastraHarnessFactoryConfig);
     create(storageRootFolder: string): Promise<MastraAgentHarness>;
 }

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. */
@@ -9,13 +10,21 @@ export class MastraHarnessFactory {
     config;
     harnessId = 'mastra';
     protocolVersion = 1;
+    supportedProviderHints = [
+        'anthropic',
+        'bedrock-anthropic',
+        'openai',
+        'openai-responses',
+        'openai-compatible',
+    ];
     constructor(config = {}) {
         this.config = config;
     }
     async create(storageRootFolder) {
+        const innerFetch = createProxyAwareFetch(resolveProxyDispatcher());
         return new MastraHarness(storageRootFolder, {
-            modelConfigFactory: this.config.modelConfigFactory,
             toolApprovalTimeoutMs: this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS,
+            innerFetch,
         });
     }
 }

package/dist/mastra-harness.d.ts

@@ -1,12 +1,11 @@
 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 StreamOptions, type TelemetryEventCallback, type ToolResultInfo } 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 ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
-import type { MastraModelConfigFactory } from './model-config-factory.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
-import { type LLMGatewayClient, type MultimodalFile } from '@salesforce/llm-gateway-sdk';
+import { type MultimodalFile } from '@salesforce/sfdx-agent-sdk';
 import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
@@ -77,9 +76,12 @@ interface MastraAgentState {
     composedInstructions: string;
     /**
      * Pre-flight multimodal validation for this agent's model configuration.
-     * Captured from {@link ResolvedModelConfig.validateFiles} at `createAgent`
-     * time. Called by `toMastraStreamInput` before every stream that carries
-     * `image` or `file` parts. Throws `LLMGClientError` on violation.
+     * Wraps `validateMultimodalFiles(files, model)` against the agent's
+     * currently-bound `ModelConnectivityInfo.model` at call time, so within-
+     * shape model swaps (Claude 4.5 → 4.6) pick up the updated caps without
+     * rebuilding the closure. Called by `toMastraStreamInput` before every
+     * stream that carries `image` or `file` parts. Throws
+     * `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)` on violation.
      */
     validateFiles: (files: readonly MultimodalFile[]) => void;
     /** Per-server MCP state, keyed by server name. Empty map when no MCP servers are configured. */
@@ -192,10 +194,18 @@ export type MastraAgentHarness = WithAgentConfig<AgentHarness & {
  * directly.
  */
 export interface MastraHarnessOptions {
-    modelConfigFactory?: MastraModelConfigFactory;
     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;
@@ -216,10 +226,19 @@ export declare class MastraHarness implements MastraAgentHarness {
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
      */
     readonly extensions: MastraAgentHarness['extensions'];
-    private readonly modelConfigFactory;
+    /**
+     * Live `ModelConnectivityInfo` per agent. The pass-through builders close
+     * over a getter that reads from this map, so within-shape `modelId` swaps,
+     * JWT rotations, and BYOK provider swaps land on the next outbound call
+     * without rebuilding the Mastra `Agent`. The map is replaced on every
+     * `updateAgent`; the language model's fetch wrapper picks up the new bag
+     * via the closure.
+     */
+    private readonly modelConnectivityByAgent;
     private readonly clock;
     private readonly idGenerator;
     private readonly toolApprovalTimeoutMs;
+    private readonly innerFetch;
     constructor(storageRootFolder: string, opts?: MastraHarnessOptions);
     /**
      * @requirements
@@ -233,6 +252,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     shutdown(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
     /**
      * @requirements
      * - MUST throw an error if the harness has not been initialized.
@@ -251,7 +271,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      *   `mapToolDefinitionsToMastraTools()` and merge with namespaced MCP-discovered tools.
      * - MUST store the original `MCPConfiguration` so getMcpServerInfo can report disabled servers.
      */
-    createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;
@@ -298,7 +318,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      * `previousConfig`) sees the harness's current truth and reverts only the
      * actual deltas.
      */
-    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;
@@ -359,6 +379,18 @@ export declare class MastraHarness implements MastraAgentHarness {
      * still observable. Used by `compactThread` on both the empty-source and
      * non-empty paths.
      */
+    /**
+     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV3` 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
+     * rebuilding this language model.
+     *
+     * The manager validates `providerHint` against `MastraHarnessFactory.supportedProviderHints`
+     * via G8 before any harness work runs (`AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS`),
+     * so a hint not handled here is a programming error worth surfacing eagerly.
+     */
+    private buildLanguageModel;
     private destroyThreadBestEffort;
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -19,9 +19,11 @@ import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/sc
 import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
 import { hasEnabledServers, mapToMastraMCPServers } from './mcp-config-mapper.js';
 import { buildMcpErrorDetail, sanitizeMcpErrorMessage } from './mcp-error-classifier.js';
-import { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
 import { partitionPool, resolveAlwaysActive, } from './tool-search.js';
-import {} from '@salesforce/llm-gateway-sdk';
+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 { ToolResultRedactionProcessor } from './mastra-tool-result-redaction-processor.js';
 import { backfillCreatedAt, buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
 import { makeAbortable } from './utils.js';
@@ -362,16 +364,25 @@ export class MastraHarness {
             formatMcpToolName: (serverName, toolName) => `${serverName}_${toolName}`,
         },
     };
-    modelConfigFactory;
+    /**
+     * Live `ModelConnectivityInfo` per agent. The pass-through builders close
+     * over a getter that reads from this map, so within-shape `modelId` swaps,
+     * JWT rotations, and BYOK provider swaps land on the next outbound call
+     * without rebuilding the Mastra `Agent`. The map is replaced on every
+     * `updateAgent`; the language model's fetch wrapper picks up the new bag
+     * via the closure.
+     */
+    modelConnectivityByAgent = new Map();
     clock;
     idGenerator;
     toolApprovalTimeoutMs;
+    innerFetch;
     constructor(storageRootFolder, opts = {}) {
         this.storageRootFolder = storageRootFolder;
-        this.modelConfigFactory = opts.modelConfigFactory ?? new DefaultMastraModelConfigFactory();
         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`,
@@ -414,6 +425,7 @@ export class MastraHarness {
             state.skillSearchProcessor?.dispose();
         }));
         this.activeAgents.clear();
+        this.modelConnectivityByAgent.clear();
         await this.mastra?.shutdown();
         this.buses.dispose();
     }
@@ -423,6 +435,9 @@ export class MastraHarness {
     onLog(callback) {
         return this.buses.onLog(callback);
     }
+    onWireCommunication(callback) {
+        return this.buses.onWireCommunication(callback);
+    }
     // ── Agent Lifecycle ──────────────────────────────────────────────
     /**
      * @requirements
@@ -442,17 +457,19 @@ export class MastraHarness {
      *   `mapToolDefinitionsToMastraTools()` and merge with namespaced MCP-discovered tools.
      * - MUST store the original `MCPConfiguration` so getMcpServerInfo can report disabled servers.
      */
-    async createAgent(agentId, projectRoot, llmGatewayClient, config = {}, options) {
+    async createAgent(agentId, projectRoot, modelConnectivityInfo, config = {}, options) {
         if (this.activeAgents.has(agentId)) {
             throw new Error(`Agent with id "${agentId}" is already registered`);
         }
+        // Store the bag first so the language-model getter has it on construct.
+        this.modelConnectivityByAgent.set(agentId, modelConnectivityInfo);
         // Run rule load before MCP setup so a bad rule path can't leak constructed clients.
         const composedInstructions = await composeInstructionsWithRules(config.instructions, config.rules);
         // ── MCP setup (non-blocking, per-server) ──────────────────────────
         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}`,
@@ -487,7 +504,22 @@ export class MastraHarness {
         const consumerToolNames = new Set((config.tools ?? []).map((t) => t.name));
         const parkerLookup = (threadId) => this.activeAgents.get(agentId)?.coordinators.get(threadId)?.parkConsumerToolCall;
         const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools, parkerLookup) : {};
-        const { model: resolvedModel, validateFiles } = this.modelConfigFactory.create(llmGatewayClient, this.buses.getLogBus());
+        // Build the language model from the live ModelConnectivityInfo bag. The
+        // builder closes over `() => this.modelConnectivityByAgent.get(agentId)!`
+        // so within-shape `modelId` swaps and JWT rotations land on the next
+        // outbound call without rebuilding the Mastra `Agent` (cross-shape
+        // swaps rebuild via `updateAgent` below). `validateFiles` reads `model`
+        // from the bag so multimodal pre-flight stays in lockstep with the
+        // model the harness is actually about to talk to.
+        const getInfoForAgent = () => {
+            const info = this.modelConnectivityByAgent.get(agentId);
+            if (!info) {
+                throw new AgentSDKError(`No connectivity info registered for agentId "${agentId}".`, AgentSDKErrorType.AGENT_NOT_FOUND);
+            }
+            return info;
+        };
+        const resolvedModel = this.buildLanguageModel(getInfoForAgent);
+        const validateFiles = (files) => validateMultimodalFiles(files, getInfoForAgent().model);
         let mastraWorkspace;
         let agent;
         let mastraAgentAdded = false;
@@ -630,6 +662,11 @@ export class MastraHarness {
             skillSearchProcessor?.dispose();
             await mastraWorkspace?.destroy().catch(() => undefined);
             await Promise.allSettled(Array.from(mcpServerStates.values()).map((s) => s.client.disconnect().catch(() => undefined)));
+            // The bag was registered eagerly at the top of createAgent so the
+            // language-model getter could read it. On failure we never made
+            // it to activeAgents.set, so the registration is orphaned —
+            // clear it for symmetry with destroyAgent.
+            this.modelConnectivityByAgent.delete(agentId);
             throw error;
         }
     }
@@ -652,6 +689,7 @@ export class MastraHarness {
         state.skillSearchProcessor?.dispose();
         await state.mastraWorkspace?.destroy();
         this.mastra.removeAgent(agentId);
+        this.modelConnectivityByAgent.delete(agentId);
         return this.activeAgents.delete(agentId);
     }
     /**
@@ -820,9 +858,21 @@ export class MastraHarness {
      * `previousConfig`) sees the harness's current truth and reverts only the
      * actual deltas.
      */
-    async updateAgent(agentId, llmGatewayClient, config = {}, options) {
+    async updateAgent(agentId, modelConnectivityInfo, config = {}, options) {
         const state = this.getAgentStateOrThrow(agentId);
         options?.abortSignal?.throwIfAborted();
+        // Swap the connectivity bag in the per-agent map BEFORE any rebuild
+        // logic runs. Within-shape model swaps (Claude 4.5 → 4.6) flow through
+        // the existing language model's getter on the next outbound call;
+        // cross-shape swaps trigger an `Agent` rebuild below. JWT rotation
+        // and rate-limit gate flips also land here — no separate swap path.
+        // Cross-shape swaps could in principle skip the Agent rebuild below
+        // — only a `providerHint` change requires a new `mastra.removeAgent`
+        // round trip — but Mastra always rebuilds the `Agent` on
+        // `updateAgent` regardless, so that optimization isn't load-bearing
+        // today; the previous-hint capture is left out so this site doesn't
+        // accumulate dead state.
+        this.modelConnectivityByAgent.set(agentId, modelConnectivityInfo);
         // ── Phase 0: validate non-MCP inputs before any MCP client is touched.
         //            A bad rule path or skill path rejects updateAgent here so
         //            half-applied state from non-MCP failures is impossible.
@@ -861,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];
@@ -905,7 +955,24 @@ export class MastraHarness {
         const consumerToolNames = new Set((config.tools ?? []).map((t) => t.name));
         const parkerLookup = (threadId) => this.activeAgents.get(agentId)?.coordinators.get(threadId)?.parkConsumerToolCall;
         const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools, parkerLookup) : {};
-        const { model: resolvedModel, validateFiles } = this.modelConfigFactory.create(llmGatewayClient, this.buses.getLogBus());
+        // Same shape as createAgent's getter — reads the live bag on every call so
+        // the next-built `Agent`'s language model picks up future bag swaps.
+        const getInfoForAgent = () => {
+            const info = this.modelConnectivityByAgent.get(agentId);
+            if (!info) {
+                throw new AgentSDKError(`No connectivity info registered for agentId "${agentId}".`, AgentSDKErrorType.AGENT_NOT_FOUND);
+            }
+            return info;
+        };
+        // Cross-shape swap (e.g. Claude → GPT) requires a different language
+        // model class because the provider SDK underneath differs. Within-shape
+        // swaps could reuse the existing language model — its getter reads the
+        // refreshed bag on the next outbound call — but Mastra reconstructs the
+        // `Agent` unconditionally on every `updateAgent` (instructions, tools,
+        // processors all flow through), so we always rebuild the language model
+        // here too. Allocation cost is negligible compared to the Agent rebuild.
+        const resolvedModel = this.buildLanguageModel(getInfoForAgent);
+        const validateFiles = (files) => validateMultimodalFiles(files, getInfoForAgent().model);
         // Capture the live mcpServers map by reference — the new Agent's
         // tools() closure will read it on every step, so preserved clients'
         // discovered tools stay visible without a re-listing.
@@ -1153,6 +1220,60 @@ export class MastraHarness {
      * still observable. Used by `compactThread` on both the empty-source and
      * non-empty paths.
      */
+    /**
+     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV3` 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
+     * rebuilding this language model.
+     *
+     * The manager validates `providerHint` against `MastraHarnessFactory.supportedProviderHints`
+     * via G8 before any harness work runs (`AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS`),
+     * so a hint not handled here is a programming error worth surfacing eagerly.
+     */
+    buildLanguageModel(getInfo) {
+        const initial = getInfo();
+        const logBus = this.buses.getLogBus();
+        // The fetch wrapper emits one WireCommunicationEvent pair per HTTP call. Forward
+        // each event to the harness bus; if the bus has been disposed (a late
+        // emit during shutdown), swallow the typed DISPOSED error so trace
+        // hooks never fail the underlying fetch.
+        const emitWireCommunication = (event) => {
+            try {
+                this.buses.emitWireCommunication(event);
+            }
+            catch (err) {
+                if (!isDisposedError(err))
+                    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, 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 });
+            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 });
+            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 });
+            default:
+                // Defensive — manager-side G8 should have caught this before
+                // we got here. Make the error typed so consumers can branch
+                // on `err.type` instead of regexing the message.
+                throw new AgentSDKError(`Mastra harness has no language-model builder for providerHint "${initial.providerHint}".`, AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS);
+        }
+    }
     async destroyThreadBestEffort(agentId, threadId) {
         try {
             await this.destroyThread(agentId, threadId);

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

@@ -1,5 +1,5 @@
 import type { MastraMCPServerDefinition } from '@mastra/mcp';
-import type { JSONWebToken } from '@salesforce/llm-gateway-sdk';
+import type { JSONWebToken } from '@salesforce/agentic-common';
 import { type MCPConfiguration } from '@salesforce/sfdx-agent-sdk';
 /**
  * Returns `true` if `config` contains at least one server that is not explicitly disabled.
@@ -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