@salesforce/sfdx-agent-harness-mastra 0.19.0 → 0.21.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.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
+- **harness-claude,harness-mastra,agent-sdk**: idempotent settle + quiet dispose (#589) ([#598](https://github.com/forcedotcom/agentic-dx/pull/598))
+
 ## [0.19.0] - 2026-06-12
 
 ### Features

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
 
@@ -203,9 +203,12 @@ active `eventStream`:
 { type: 'finish', finishReason: 'error' }
 ```
 
-Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool throw because the
-coordinator has already auto-resolved them. The granularity is per `toolCallId` — each emitted approval arms its own
-timer; the first one to fire tears down the whole turn (since Mastra can't continue the suspended run after timeout
+Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool are silent no-ops
+(issue #589 idempotent settle) — the coordinator already auto-resolved them, so the consumer's intended outcome is
+already true and there's nothing to fail. Only a `toolCallId` the coordinator never saw at all (typo, wrong session,
+called before `tool-approval-request` ever fired) throws, and that throw is an `AgentSDKError` whose
+`type === AgentSDKErrorType.TOOL_CALL_NOT_FOUND`. The granularity is per `toolCallId` — each emitted approval arms its
+own timer; the first one to fire tears down the whole turn (since Mastra can't continue the suspended run after timeout
 anyway). To observe the timeout, keep iterating the `eventStream` past the `tool-approval-request` event so the
 synthetic terminal pair lands in your loop:
 
@@ -233,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-approval-coordinator.d.ts

@@ -128,8 +128,11 @@ export declare class MastraApprovalCoordinator {
     private readonly consumerSettled;
     /**
      * ToolCallIds the coordinator auto-resolved (timeout / abort / dispose
-     * / consumer-tool auto-approve). A subsequent settle for these ids
-     * rejects with "already auto-resolved by the coordinator".
+     * / pump-error / consumer-tool auto-approve). A subsequent settle for
+     * these ids is a silent no-op via the idempotent-settle contract
+     * (issue #589) — the lost race is unactionable from the consumer's
+     * side, and the methods are void-typed so there's no return value to
+     * communicate the no-op.
      */
     private readonly settledByCoordinator;
     /** Per-toolCallId approval-timeout timers (armed when an approval is emitted). */
@@ -181,6 +184,15 @@ export declare class MastraApprovalCoordinator {
      * parker invocation for the same id.
      */
     private readonly preSubmittedByToolCallId;
+    /**
+     * ToolCallIds the consumer has settled via {@link submitToolResult},
+     * or that the coordinator drained at teardown time. Used as the
+     * idempotent-settle ledger for the consumer-tool path (parallel to
+     * `consumerSettled` + `settledByCoordinator` on the approve/decline
+     * path). A subsequent `submitToolResult` for these ids is a silent
+     * no-op rather than throwing `TOOL_CALL_NOT_FOUND` (issue #589).
+     */
+    private readonly consumerToolSettled;
     /**
      * Callbacks invoked exactly once during teardown (`abort` or `dispose`,
      * whichever fires first, or natural pump exit).
@@ -238,13 +250,39 @@ export declare class MastraApprovalCoordinator {
     /**
      * Single teardown path for abort / dispose / approval-timeout / pump-
      * error. Drains timers, rejects pending consumer-tool parkers, marks
-     * every emitted approval as coordinator-settled, releases Mastra's
-     * suspended run, pushes the synthetic terminal pair on the sink, and
-     * fires teardown callbacks.
+     * every emitted approval and consumer-tool toolCallId as
+     * coordinator-settled, releases Mastra's suspended run, pushes the
+     * typed `error` + `finish('error')` pair on the sink, and fires
+     * teardown callbacks.
+     *
+     * Every teardown reason — including `'dispose'` — pushes both events
+     * (issue #589). Two reasons:
+     *
+     *  - **Consumers route on `error.code`, not on the *presence* of an
+     *    error event.** AFV's `chat-stream-service.ts` maps
+     *    `error.code === AgentSDKErrorType.DISPOSED` → its internal
+     *    `AGENT_CANCELLED` and reaps the turn as cancelled (rather than
+     *    completed or failed). Suppressing the dispose error event would
+     *    delete that signal and a turn that was actually torn down would
+     *    record as successful in their telemetry pipeline. The original
+     *    bug (issue #589 failure 2) was *untyped* error noise —
+     *    `error.code` is already typed as `AgentSDKErrorType.DISPOSED`,
+     *    which gives consumers a clean discriminator without
+     *    string-matching.
+     *
+     *  - **The SDK invariant requires every chat turn to end with one
+     *    terminal `FinishEvent`.** `DefaultChatSession.wrapEventStream`
+     *    only synthesizes a synthetic `finish` when an error landed on
+     *    the stream; if dispose ended the sink without an error, the
+     *    turn would end with neither a natural finish nor a synthetic
+     *    one — breaking the SDK contract pinned in
+     *    `packages/sfdx-agent-sdk/ARCHITECTURE.md` →
+     *    "Critical Invariants" → "Every chat turn ends with exactly one
+     *    terminal FinishEvent".
      *
-     * The `reason` parameter only changes the sink's terminal shape:
-     * `'dispose'` pushes error-only (matches Claude's dispose contract);
-     * everything else pushes error+finish.
+     * Mirrors the Claude coordinator's `teardown` so the abort / dispose
+     * / timeout / pump-error paths can't drift out of step on either
+     * harness — issue #589 lands the same shape on both.
      */
     private teardown;
     approve(toolCallId: string): void;

package/dist/mastra-approval-coordinator.js

@@ -64,8 +64,11 @@ export class MastraApprovalCoordinator {
     consumerSettled = new Set();
     /**
      * ToolCallIds the coordinator auto-resolved (timeout / abort / dispose
-     * / consumer-tool auto-approve). A subsequent settle for these ids
-     * rejects with "already auto-resolved by the coordinator".
+     * / pump-error / consumer-tool auto-approve). A subsequent settle for
+     * these ids is a silent no-op via the idempotent-settle contract
+     * (issue #589) — the lost race is unactionable from the consumer's
+     * side, and the methods are void-typed so there's no return value to
+     * communicate the no-op.
      */
     settledByCoordinator = new Set();
     /** Per-toolCallId approval-timeout timers (armed when an approval is emitted). */
@@ -117,6 +120,15 @@ export class MastraApprovalCoordinator {
      * parker invocation for the same id.
      */
     preSubmittedByToolCallId = new Map();
+    /**
+     * ToolCallIds the consumer has settled via {@link submitToolResult},
+     * or that the coordinator drained at teardown time. Used as the
+     * idempotent-settle ledger for the consumer-tool path (parallel to
+     * `consumerSettled` + `settledByCoordinator` on the approve/decline
+     * path). A subsequent `submitToolResult` for these ids is a silent
+     * no-op rather than throwing `TOOL_CALL_NOT_FOUND` (issue #589).
+     */
+    consumerToolSettled = new Set();
     /**
      * Callbacks invoked exactly once during teardown (`abort` or `dispose`,
      * whichever fires first, or natural pump exit).
@@ -229,18 +241,52 @@ export class MastraApprovalCoordinator {
     /**
      * Single teardown path for abort / dispose / approval-timeout / pump-
      * error. Drains timers, rejects pending consumer-tool parkers, marks
-     * every emitted approval as coordinator-settled, releases Mastra's
-     * suspended run, pushes the synthetic terminal pair on the sink, and
-     * fires teardown callbacks.
+     * every emitted approval and consumer-tool toolCallId as
+     * coordinator-settled, releases Mastra's suspended run, pushes the
+     * typed `error` + `finish('error')` pair on the sink, and fires
+     * teardown callbacks.
+     *
+     * Every teardown reason — including `'dispose'` — pushes both events
+     * (issue #589). Two reasons:
+     *
+     *  - **Consumers route on `error.code`, not on the *presence* of an
+     *    error event.** AFV's `chat-stream-service.ts` maps
+     *    `error.code === AgentSDKErrorType.DISPOSED` → its internal
+     *    `AGENT_CANCELLED` and reaps the turn as cancelled (rather than
+     *    completed or failed). Suppressing the dispose error event would
+     *    delete that signal and a turn that was actually torn down would
+     *    record as successful in their telemetry pipeline. The original
+     *    bug (issue #589 failure 2) was *untyped* error noise —
+     *    `error.code` is already typed as `AgentSDKErrorType.DISPOSED`,
+     *    which gives consumers a clean discriminator without
+     *    string-matching.
      *
-     * The `reason` parameter only changes the sink's terminal shape:
-     * `'dispose'` pushes error-only (matches Claude's dispose contract);
-     * everything else pushes error+finish.
+     *  - **The SDK invariant requires every chat turn to end with one
+     *    terminal `FinishEvent`.** `DefaultChatSession.wrapEventStream`
+     *    only synthesizes a synthetic `finish` when an error landed on
+     *    the stream; if dispose ended the sink without an error, the
+     *    turn would end with neither a natural finish nor a synthetic
+     *    one — breaking the SDK contract pinned in
+     *    `packages/sfdx-agent-sdk/ARCHITECTURE.md` →
+     *    "Critical Invariants" → "Every chat turn ends with exactly one
+     *    terminal FinishEvent".
+     *
+     * Mirrors the Claude coordinator's `teardown` so the abort / dispose
+     * / timeout / pump-error paths can't drift out of step on either
+     * harness — issue #589 lands the same shape on both.
      */
     teardown(reason, error, code) {
         this.cancelAllTimers();
         for (const id of this.emittedApprovals)
             this.settledByCoordinator.add(id);
+        // Issue #589: drain in-flight consumer-tool ids into the
+        // idempotent-settle ledger so a late `submitToolResult` after
+        // teardown is a silent no-op rather than throwing
+        // `TOOL_CALL_NOT_FOUND`. Mirrors the approve/decline drain above.
+        for (const id of this.pendingByToolCallId.keys())
+            this.consumerToolSettled.add(id);
+        for (const id of this.toolCallArgs.keys())
+            this.consumerToolSettled.add(id);
         // Reject every parked consumer-tool call so the bridge handler
         // unblocks with an error rather than waiting forever.
         for (const entry of this.pendingByToolCallId.values())
@@ -264,18 +310,9 @@ export class MastraApprovalCoordinator {
         const resolve = this.continuationResolver;
         this.continuationResolver = undefined;
         resolve?.('done');
-        if (reason === 'dispose') {
-            // Match Claude's dispose shape: error event only, no `finish`.
-            // Disposal is a consumer-triggered teardown, not a normal turn
-            // end, so a `finish` event would be misleading.
-            this.initial.push({ type: 'error', error, code });
-            this.initial.end();
-        }
-        else {
-            this.initial.push({ type: 'error', error, code });
-            this.initial.push({ type: 'finish', finishReason: 'error' });
-            this.initial.end();
-        }
+        this.initial.push({ type: 'error', error, code });
+        this.initial.push({ type: 'finish', finishReason: 'error' });
+        this.initial.end();
         this.pendingSuspendIds.clear();
         this.runTeardownCallbacks();
     }
@@ -287,14 +324,21 @@ export class MastraApprovalCoordinator {
         this.recordDecision('decline', toolCallId, { kind: 'decline' });
     }
     recordDecision(method, toolCallId, decision) {
-        if (this.settledByCoordinator.has(toolCallId)) {
-            throw new Error(`MastraApprovalCoordinator.${method}(): tool call "${toolCallId}" was already auto-resolved by the coordinator`);
-        }
-        if (this.consumerSettled.has(toolCallId)) {
-            throw new Error(`MastraApprovalCoordinator.${method}(): tool call "${toolCallId}" was already settled`);
+        // Issue #589: idempotent settle. A tool call the coordinator
+        // already auto-resolved (timeout / abort / dispose / pump-error)
+        // or the consumer already settled is a lost-race no-op rather
+        // than a throw — settle methods are void-typed, so the consumer
+        // never branches on a return value, and the outcome they wanted
+        // (id is settled) is already true.
+        if (this.settledByCoordinator.has(toolCallId) || this.consumerSettled.has(toolCallId)) {
+            return;
         }
         if (!this.emittedApprovals.has(toolCallId)) {
-            throw new Error(`MastraApprovalCoordinator.${method}(): no pending approval for tool call "${toolCallId}"`);
+            // Genuine misuse — the coordinator never saw this id (typo,
+            // wrong session, or settle called before approval-request /
+            // tool-call ever fired). Typed so consumers can branch on
+            // err.type instead of string-matching the message.
+            throw new AgentSDKError(`MastraApprovalCoordinator.${method}(): no pending approval for tool call "${toolCallId}"`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
         }
         this.consumerSettled.add(toolCallId);
         this.cancelTimer(toolCallId);
@@ -344,8 +388,18 @@ export class MastraApprovalCoordinator {
      * resolves (probe-validated, see #529 step 2c).
      */
     submitToolResult(toolCallId, result, isError) {
+        // Issue #589: idempotent settle. A submitToolResult for an id the
+        // consumer already settled, or that the coordinator drained at
+        // teardown time, is a silent no-op — the lost-race shape is
+        // unactionable from the consumer's side, and the method is
+        // void-typed. Mirrors the approve/decline path's
+        // `consumerSettled` + `settledByCoordinator` ledger.
+        if (this.consumerToolSettled.has(toolCallId)) {
+            return;
+        }
         const entry = this.pendingByToolCallId.get(toolCallId);
         if (entry) {
+            this.consumerToolSettled.add(toolCallId);
             this.pendingByToolCallId.delete(toolCallId);
             entry.resolve({ result, isError });
             return;
@@ -355,10 +409,14 @@ export class MastraApprovalCoordinator {
         // We allow this whenever the coordinator has seen a `tool-call`
         // event under that id (reachable in `toolCallArgs`); else throw.
         if (this.toolCallArgs.has(toolCallId)) {
+            this.consumerToolSettled.add(toolCallId);
             this.preSubmittedByToolCallId.set(toolCallId, { result, isError });
             return;
         }
-        throw new Error(`MastraApprovalCoordinator.submitToolResult(): no pending tool call for id "${toolCallId}"`);
+        // Issue #589: typed error — the coordinator never saw this id, so
+        // this is genuine misuse rather than the lost-race shape the
+        // idempotent-settle path collapses to a no-op.
+        throw new AgentSDKError(`MastraApprovalCoordinator.submitToolResult(): no pending tool call for id "${toolCallId}"`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
     }
     // ───────────────────────── pump loop ────────────────────────────────────
     /**

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