@salesforce/sfdx-agent-harness-mastra 0.20.0 → 0.21.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.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,15 @@ 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.
 
 ### Extension surface
 
@@ -236,19 +236,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

@@ -9,12 +9,18 @@ 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) {
         return new MastraHarness(storageRootFolder, {
-            modelConfigFactory: this.config.modelConfigFactory,
             toolApprovalTimeoutMs: this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS,
         });
     }

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,7 +194,6 @@ export type MastraAgentHarness = WithAgentConfig<AgentHarness & {
  * directly.
  */
 export interface MastraHarnessOptions {
-    modelConfigFactory?: MastraModelConfigFactory;
     clock?: Clock;
     idGenerator?: UniqueIDGenerator;
     toolApprovalTimeoutMs?: number;
@@ -216,7 +217,15 @@ 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;
@@ -233,6 +242,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 +261,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 +308,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 +369,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,13 +364,20 @@ 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;
     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;
@@ -414,6 +423,7 @@ export class MastraHarness {
             state.skillSearchProcessor?.dispose();
         }));
         this.activeAgents.clear();
+        this.modelConnectivityByAgent.clear();
         await this.mastra?.shutdown();
         this.buses.dispose();
     }
@@ -423,6 +433,9 @@ export class MastraHarness {
     onLog(callback) {
         return this.buses.onLog(callback);
     }
+    onWireCommunication(callback) {
+        return this.buses.onWireCommunication(callback);
+    }
     // ── Agent Lifecycle ──────────────────────────────────────────────
     /**
      * @requirements
@@ -442,10 +455,12 @@ 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) ──────────────────────────
@@ -487,7 +502,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 +660,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 +687,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 +856,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.
@@ -905,7 +953,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 +1218,59 @@ 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;
+            }
+        };
+        switch (initial.providerHint) {
+            case 'bedrock-anthropic':
+                // Salesforce LLM Gateway's `/invoke-with-response-stream` (Bedrock pass-through).
+                return buildAnthropicLanguageModel({ getInfo, logBus, emitWireCommunication });
+            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 });
+            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 });
+            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 });
+            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.

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

@@ -0,0 +1,66 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Prompt } from '@ai-sdk/provider';
+import type { LogBus } from '@salesforce/agentic-common';
+import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
+ * `/invoke-with-response-stream` (Bedrock-Anthropic pass-through) endpoint.
+ * Drives `@anthropic-ai/bedrock-sdk` with `skipAuth: true` so the connectivity
+ * resolver's headers (Salesforce JWT, tenant key, etc.) are the single source
+ * of auth.
+ *
+ * Each `doStream` / `doGenerate` call reads the live `ModelConnectivityInfo`
+ * via the supplied `getInfo` getter — allowing the harness to swap the bag
+ * (within-shape `modelId` change, JWT rotation, premium-rate-limit gate flip)
+ * between turns without rebuilding this language model. The fetch wrapper
+ * calls `info.getHeaders()` per HTTP call so credential rotation lands on
+ * the next request.
+ */
+export declare function buildAnthropicLanguageModel(opts: {
+    getInfo: () => ModelConnectivityInfo;
+    logBus?: LogBus;
+    emitWireCommunication?: (event: WireCommunicationEvent) => void;
+}): LanguageModelV3;
+/**
+ * Builds the in-process `LanguageModelV3` impl for direct-Anthropic API access
+ * (`api.anthropic.com/v1/messages` or any Anthropic-shaped endpoint). Drives
+ * `@anthropic-ai/sdk` with the api-key peeled from the resolver's headers.
+ *
+ * Authentication: the connectivity resolver emits `Authorization: Bearer <key>`
+ * as its generic credential carrier. The Anthropic Messages API requires
+ * `x-api-key` instead, so this builder peels the bearer token at construction
+ * time and passes it as the SDK's `apiKey` arg. The SDK then writes
+ * `x-api-key` and `anthropic-version` itself; our fetch wrapper supplies the
+ * resolver's remaining headers (typically `Content-Type` and any
+ * `model.customHeaders`) on top, with the bearer header explicitly stripped
+ * to avoid sending both auth shapes redundantly.
+ *
+ * Same per-call freshness contract as the Bedrock builder: every HTTP call
+ * re-evaluates `getHeaders()` via the fetch wrapper so a rotating api-key
+ * source (BYOK toggle, secret-store fetch) lands without rebuilding the
+ * language model.
+ */
+export declare function buildAnthropicDirectLanguageModel(opts: {
+    getInfo: () => ModelConnectivityInfo;
+    logBus?: LogBus;
+    emitWireCommunication?: (event: WireCommunicationEvent) => void;
+}): LanguageModelV3;
+/**
+ * Translates a V3 `LanguageModelV3Prompt` into Anthropic's Messages API shape
+ * — top-level `system` string + `MessageParam[]` of role-tagged content blocks.
+ *
+ * V3 keeps system / user / assistant / tool messages flat. Anthropic combines
+ * tool results onto a synthetic user-role turn carrying `tool_result` blocks,
+ * so we collapse consecutive tool-only V3 messages into the surrounding user
+ * turn shape.
+ */
+export declare function translatePromptToAnthropic(prompt: LanguageModelV3Prompt): {
+    system?: string;
+    messages: Anthropic.Messages.MessageParam[];
+};
+/**
+ * Translates V3 function-tool definitions into Anthropic's `Tool[]` shape.
+ * Skips non-function variants (provider-defined / dynamic) — the pass-through
+ * path supports only the function-tool subset that Mastra's tool mapper produces.
+ */
+export declare function translateToolsToAnthropic(options: LanguageModelV3CallOptions): Anthropic.Messages.Tool[];