@salesforce/sfdx-agent-sdk 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.22.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-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.21.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.20.0] - 2026-06-12
 
 ### Features

package/README.md

@@ -540,17 +540,18 @@ totals, subscribe to `chat-stream-completed` telemetry instead.
 The SDK throws `AgentSDKError` for predictable not-found and compatibility conditions. Each error has a `type` property
 from `AgentSDKErrorType`:
 
-| Type                       | Thrown By                                                                                                                                                                   |
-| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENT_NOT_FOUND`          | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`                                                                                                                    |
-| `CHAT_SESSION_NOT_FOUND`   | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`                                                            |
-| `COMPACTION_FAILED`        | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.        |
-| `DISPOSED`                 | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                 |
-| `INCOMPATIBLE_HARNESS`     | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
-| `INVALID_MESSAGE_CONTENT`  | `ChatSession.chat()` / harness `stream()` when a message part is not valid as input (a `tool-call`/`tool-result` part, or non-base64-string file data)                      |
-| `MCP_SERVER_DISABLED`      | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false`                                                                                      |
-| `MCP_SERVER_NOT_FOUND`     | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config                                                                                 |
-| `MULTIMODAL_NOT_SUPPORTED` | `ChatSession.chat()` / harness `stream()` when a file fails pre-stream capability validation (unsupported format, too large, or too many files)                             |
+| Type                             | Thrown By                                                                                                                                                                                                                                                                                                                                                                               |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AGENT_NOT_FOUND`                | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`                                                                                                                                                                                                                                                                                                                                |
+| `CHAT_SESSION_NOT_FOUND`         | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`                                                                                                                                                                                                                                                                        |
+| `COMPACTION_FAILED`              | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.                                                                                                                                                                                                                    |
+| `DISPOSED`                       | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                                                                                                                                                                                                                             |
+| `INCOMPATIBLE_HARNESS`           | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's                                                                                                                                                                                                             |
+| `INVALID_MESSAGE_CONTENT`        | `ChatSession.chat()` / harness `stream()` when a message part is not valid as input (a `tool-call`/`tool-result` part, or non-base64-string file data)                                                                                                                                                                                                                                  |
+| `MCP_SERVER_DISABLED`            | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false`                                                                                                                                                                                                                                                                                                  |
+| `MCP_SERVER_NOT_FOUND`           | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config                                                                                                                                                                                                                                                                                             |
+| `MODEL_NOT_SUPPORTED_BY_HARNESS` | `AgentManager.createAgent()` / `Agent.updateAgentConfig()` (G8 pre-flight) when the resolved `ModelConnectivityInfo.providerHint` isn't in the harness's `supportedProviderHints`. Surfaces before any harness work runs (no MCP discovery, no subprocess spawn, no language-model construction) so the consumer can branch cleanly on `err.type` and recover without resource cleanup. |
+| `MULTIMODAL_NOT_SUPPORTED`       | `ChatSession.chat()` / harness `stream()` when a file fails pre-stream capability validation (unsupported format, too large, or too many files)                                                                                                                                                                                                                                         |
 
 ```typescript
 import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';

package/dist/agent-connectivity-resolver.d.ts

@@ -1,54 +1,76 @@
-import { Model, type JSONWebToken, type LLMGatewayClient, type LLMGatewayClientFactory } from '@salesforce/llm-gateway-sdk';
-import { type OrgConnection, type OrgConnectionFactory } from '@salesforce/agentic-common';
+import { Model } from './models/index.js';
+import { type JSONWebToken, type OrgConnection, type OrgConnectionFactory } from '@salesforce/agentic-common';
 import type { AgentConfig } from './harness/harness-config.js';
+import type { ModelConnectivityInfo } from './types/model-connectivity-info.js';
 /**
- * The result of resolving an agent's org connectivity: a ready-to-use authenticated
- * LLM gateway client and the underlying connection.
+ * The result of resolving an agent's connectivity.
+ *
+ * `modelConnectivityInfo` is the harness-facing bag. `orgConnection` and
+ * `orgJwt` are Salesforce-org-specific and only present when the resolver targets a
+ * Salesforce-org host; non-Salesforce hosts (MuleSoft, Commerce Vibes — see
+ * [#605](https://github.com/forcedotcom/agentic-dx/issues/605)) omit them. Downstream
+ * consumers (MCP auth, identity-derived headers) treat them as optional.
  */
 export type ResolvedConnectivity = {
-    /** Pre-configured and authenticated LLM gateway client for the resolved org. */
-    llmGatewayClient: LLMGatewayClient;
-    /** Authenticated org connection carrying identity and env inference. */
-    orgConnection: OrgConnection;
-    /** Self-refreshing JWT for the resolved org, used for MCP auth injection. */
-    orgJwt: JSONWebToken;
+    /**
+     * Connectivity facts the harness needs to make an LLM request: model, base URL,
+     * native model id, provider hint, and a per-call `getHeaders()`. See
+     * {@link ModelConnectivityInfo} for the contract.
+     */
+    modelConnectivityInfo: ModelConnectivityInfo;
+    /**
+     * Authenticated org connection carrying identity and env inference. Optional —
+     * non-Salesforce hosts (MuleSoft, Commerce Vibes) omit it.
+     */
+    orgConnection?: OrgConnection;
+    /**
+     * Self-refreshing JWT for the resolved org. Used for MCP auth injection and any
+     * other Salesforce-platform-auth need (identity, future Apex). Optional —
+     * non-Salesforce hosts (or hosts that authenticate the LLM via api-key without
+     * needing org auth for MCP) omit it.
+     */
+    orgJwt?: JSONWebToken;
 };
 /**
- * Resolves the org connectivity needed to create an agent for a given project and
+ * Resolves the connectivity needed to create an agent for a given project and
  * configuration.
  *
- * Implementations are responsible for resolving the org's authentication and constructing
- * an authenticated {@link LLMGatewayClient} and {@link OrgConnection} from an
- * {@link AgentConfig}.
+ * Implementations are responsible for producing a {@link ModelConnectivityInfo} bag
+ * the harness can use to make LLM requests. Salesforce-org hosts additionally produce
+ * an {@link OrgConnection} + {@link JSONWebToken} for MCP auth and identity; non-SF
+ * hosts omit those fields.
+ *
+ * The same `AgentConnectivityResolver` instance is invoked at `createAgent` time and
+ * at `updateAgentConfig` time when `orgAlias` or `modelId` change — implementations
+ * MUST be safe to call repeatedly with different `AgentConfig` values.
  */
 export interface AgentConnectivityResolver {
     /**
-     * Resolve the org connectivity for an agent.
+     * Resolve the connectivity for an agent.
      *
      * @param projectRoot - The root directory of the project the agent operates within.
-     *   Used to find a project-local `target-org` when no `orgAlias` is configured.
+     *   Used to find a project-local `target-org` when no `orgAlias` is configured
+     *   (Salesforce-org hosts only).
      * @param config - The agent's configuration, including optional org alias and model selection.
-     * @returns The resolved LLM gateway client and org connection metadata.
+     * @returns The resolved connectivity bag plus optional org handle / JWT.
      */
     resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
 }
 /**
  * Default implementation of {@link AgentConnectivityResolver}.
  *
- * Delegates org resolution to {@link OrgConnectionFactory} and LLM client creation to
- * {@link LLMGatewayClientFactory}. Both dependencies are injectable for testing.
+ * Targets the Salesforce LLM Gateway with a Salesforce-org JWT. Produces a
+ * `ModelConnectivityInfo` bag (the harness-facing seam). The connection
+ * factory is injectable for testing.
  */
 export declare class DefaultAgentConnectivityResolver implements AgentConnectivityResolver {
     private readonly connectionFactory;
-    private readonly gatewayClientFactory;
     /**
      * @param connectionFactory - Creates authenticated Salesforce org connections.
-     * @param gatewayClientFactory - Creates authenticated LLM gateway clients.
      */
-    constructor(connectionFactory?: OrgConnectionFactory, gatewayClientFactory?: LLMGatewayClientFactory);
+    constructor(connectionFactory?: OrgConnectionFactory);
     /**
-     * Resolves the org, constructs an authenticated LLM gateway client, and
-     * returns the underlying connection.
+     * Resolves the org and produces the harness-facing `ModelConnectivityInfo` bag.
      *
      * If `config.orgAlias` is set, resolves that alias explicitly; otherwise falls back
      * to the project-local or machine-default org via
@@ -56,7 +78,7 @@ export declare class DefaultAgentConnectivityResolver implements AgentConnectivi
      *
      * @param projectRoot - Project root for project-local org resolution.
      * @param config - Agent configuration with optional org alias and model ID.
-     * @returns The resolved LLM gateway client and connection.
+     * @returns The resolved connectivity bag, org connection, and JWT.
      */
     resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
 }

package/dist/agent-connectivity-resolver.js

@@ -2,8 +2,8 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { DefaultLLMGatewayClientFactory, Model, ModelName, Models, createClaudeModel, createJWTFromConnection, } from '@salesforce/llm-gateway-sdk';
-import { SfApiEnv, RealOrgConnectionFactory, } from '@salesforce/agentic-common';
+import { Model, ModelName, Models, createClaudeModel } from './models/index.js';
+import { createJWTFromConnection, RealOrgConnectionFactory, SfApiEnv, } from '@salesforce/agentic-common';
 // TODO(@W-22782317): Temporary workaround — only on prod orgs the LLM Gateway must
 // route requests through AgentforceVibes rather than the default VibesService. Remove once a
 // long-term feature ID configuration strategy is in place.
@@ -11,23 +11,20 @@ const PROD_ORG_FEATURE_ID = 'AgentforceVibes';
 /**
  * Default implementation of {@link AgentConnectivityResolver}.
  *
- * Delegates org resolution to {@link OrgConnectionFactory} and LLM client creation to
- * {@link LLMGatewayClientFactory}. Both dependencies are injectable for testing.
+ * Targets the Salesforce LLM Gateway with a Salesforce-org JWT. Produces a
+ * `ModelConnectivityInfo` bag (the harness-facing seam). The connection
+ * factory is injectable for testing.
  */
 export class DefaultAgentConnectivityResolver {
     connectionFactory;
-    gatewayClientFactory;
     /**
      * @param connectionFactory - Creates authenticated Salesforce org connections.
-     * @param gatewayClientFactory - Creates authenticated LLM gateway clients.
      */
-    constructor(connectionFactory = new RealOrgConnectionFactory(), gatewayClientFactory = new DefaultLLMGatewayClientFactory()) {
+    constructor(connectionFactory = new RealOrgConnectionFactory()) {
         this.connectionFactory = connectionFactory;
-        this.gatewayClientFactory = gatewayClientFactory;
     }
     /**
-     * Resolves the org, constructs an authenticated LLM gateway client, and
-     * returns the underlying connection.
+     * Resolves the org and produces the harness-facing `ModelConnectivityInfo` bag.
      *
      * If `config.orgAlias` is set, resolves that alias explicitly; otherwise falls back
      * to the project-local or machine-default org via
@@ -35,7 +32,7 @@ export class DefaultAgentConnectivityResolver {
      *
      * @param projectRoot - Project root for project-local org resolution.
      * @param config - Agent configuration with optional org alias and model ID.
-     * @returns The resolved LLM gateway client and connection.
+     * @returns The resolved connectivity bag, org connection, and JWT.
      */
     async resolve(projectRoot, config) {
         const orgConnection = config.orgAlias !== undefined
@@ -45,11 +42,91 @@ export class DefaultAgentConnectivityResolver {
         const env = orgConnection.getInferredSfApiEnv();
         const featureId = env === SfApiEnv.Prod ? PROD_ORG_FEATURE_ID : undefined;
         const orgJwt = await createJWTFromConnection(orgConnection, { featureId });
-        const llmGatewayClient = this.gatewayClientFactory.create(orgJwt, { env });
-        llmGatewayClient.setModel(resolveAgentConfigModel(config.modelId));
-        return { llmGatewayClient, orgConnection, orgJwt };
+        const model = resolveAgentConfigModel(config.modelId);
+        const modelConnectivityInfo = {
+            model,
+            baseUrl: salesforceGatewayBaseUrl(env),
+            // The Salesforce gateway accepts the canonical `llmgateway__*` model id verbatim,
+            // so `nativeModelId === model.name` for every gateway-routed call.
+            nativeModelId: model.name,
+            providerHint: pickProviderHintForGatewayModel(model),
+            getHeaders: async () => buildSalesforceGatewayHeaders(orgJwt, model),
+        };
+        return { modelConnectivityInfo, orgConnection, orgJwt };
     }
 }
+/**
+ * Maps a Salesforce gateway-routed {@link Model} to the wire shape the harness will
+ * speak. Anthropic models go to the `/invoke-with-response-stream` (Bedrock-Anthropic)
+ * pass-through endpoint; OpenAI models go to the `/responses` (OpenAI Responses)
+ * pass-through endpoint. Throws for any model whose family cannot be inferred from
+ * its `name` — a programming error worth surfacing eagerly rather than silently
+ * defaulting.
+ *
+ * **Scope:** This helper is for the Salesforce gateway path only — both
+ * `llmgateway__BedrockAnthropic*` and `llmgateway__Anthropic*` prefixes go to the
+ * gateway's Bedrock pass-through, so both collapse to `'bedrock-anthropic'`. A
+ * consumer wanting direct-Anthropic auth (`providerHint: 'anthropic'`) drives that
+ * path through {@link ApiKeyConnectivityResolver} with an explicit `providerHint`
+ * argument, not through this resolver.
+ */
+function pickProviderHintForGatewayModel(model) {
+    const name = model.name;
+    if (name.startsWith('llmgateway__BedrockAnthropic') || name.startsWith('llmgateway__Anthropic')) {
+        return 'bedrock-anthropic';
+    }
+    if (name.startsWith('llmgateway__OpenAI')) {
+        return 'openai-responses';
+    }
+    throw new Error(`Cannot infer providerHint for model "${name}". Salesforce gateway models must start with "llmgateway__BedrockAnthropic*" or "llmgateway__OpenAI*".`);
+}
+/**
+ * Returns the Salesforce LLM Gateway base URL for the given environment.
+ *
+ * Includes the `/ai/gpt/v1` API root: the pass-through endpoints
+ * (`/responses` for OpenAI Responses, `/model/<id>/invoke-with-response-stream`
+ * for Bedrock-Anthropic) live under this prefix, and provider SDKs
+ * (`@anthropic-ai/bedrock-sdk`, `openai`) construct their per-model paths by
+ * concatenation onto the base URL the consumer supplies.
+ */
+function salesforceGatewayBaseUrl(env) {
+    switch (env) {
+        case SfApiEnv.Dev:
+            return 'https://dev.api.salesforce.com/ai/gpt/v1';
+        case SfApiEnv.Perf:
+            return 'https://perf.api.salesforce.com/ai/gpt/v1';
+        case SfApiEnv.Stage:
+            return 'https://stage.api.salesforce.com/ai/gpt/v1';
+        case SfApiEnv.Test:
+            return 'https://test.api.salesforce.com/ai/gpt/v1';
+        case SfApiEnv.Prod:
+        default:
+            return 'https://api.salesforce.com/ai/gpt/v1';
+    }
+}
+/**
+ * Builds the full header set for a Salesforce LLM Gateway request, including the
+ * Authorization Bearer JWT, tenant-key, feature-id, and any model-specific custom
+ * headers. Re-evaluated on every harness call so JWT rotations land on the next
+ * request without rebuilding the bag.
+ */
+async function buildSalesforceGatewayHeaders(orgJwt, model) {
+    const [jwtValue, tenantKey] = await Promise.all([orgJwt.getValue(), orgJwt.getTenantKey()]);
+    // Order matters: spread `customHeaders` FIRST so the resolver-set auth /
+    // tenant / feature-id headers win on conflict. `customHeaders` is for
+    // vendor-specific labels (`anthropic-version`, model-tag headers, etc.) —
+    // not for auth or tenancy. A `Model` instance built with
+    // `customHeaders: { Authorization: '...' }` must NOT shadow the
+    // resolver's freshly-fetched JWT.
+    return {
+        ...(model.customHeaders ?? {}),
+        Authorization: `Bearer ${jwtValue}`,
+        'Content-Type': 'application/json;charset=utf-8',
+        'x-client-feature-id': orgJwt.getFeatureId(),
+        'x-sfdc-app-context': 'EinsteinGPT',
+        'x-sfdc-core-tenant-id': tenantKey,
+    };
+}
 /**
  * Resolves an `AgentConfig.modelId` value (which may be a {@link ModelName} enum value, a
  * pre-built {@link Model} instance, or `undefined`) to a concrete {@link Model}.
@@ -68,7 +145,7 @@ export function resolveAgentConfigModel(modelId) {
     if (modelId === undefined)
         return Models.getDefault();
     // Known limitation: `instanceof Model` is realm-scoped — a consumer that ends up with two copies
-    // of `@salesforce/llm-gateway-sdk` resolved in their dependency tree will have their `Model`
+    // of `@salesforce/sfdx-agent-sdk` resolved in their dependency tree will have their `Model`
     // instance fail this check and fall through to `rehydratePersistedModel`. That branch handles
     // it correctly for Claude variants but throws for anything else. The duplicate-package case is
     // a packaging bug at the consumer; we don't paper over it here.

package/dist/agent-manager.d.ts

@@ -5,6 +5,8 @@ import { type AgentConfig } from './harness/harness-config.js';
 import { type Agent } from './agent.js';
 import type { HooksForAgent } from './types/redaction.js';
 import type { TelemetryEventCallback } from './types/telemetry-events.js';
+import type { WireCommunicationEventCallback } from './types/wire-communication-event.js';
+import type { ProviderHint } from './types/model-connectivity-info.js';
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
 /**
  * Per-agent failure recorded during the boot-time restore pass.
@@ -104,6 +106,16 @@ export interface AgentManager<H extends AgentHarness = AgentHarness> {
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     /** Subscribe to structured log records across every managed agent. */
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * Subscribe to wire-communication events emitted by the harness across
+     * every managed agent — raw HTTP request/response captures of the LLM
+     * provider's traffic. The events may contain user prompts and PII; the
+     * channel is opt-in and not flowed to log files by default. Use
+     * {@link WireCommunicationFileWriter} to dump events to disk for
+     * debugging. Fidelity differs by harness — see
+     * `AgentHarness.onWireCommunication` for the cross-harness contract.
+     */
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
     /**
      * Returns a snapshot of the boot-time restore failures the SDK has not
      * yet been told to forget. Each entry is cleared on a successful
@@ -123,6 +135,7 @@ export interface AgentManager<H extends AgentHarness = AgentHarness> {
  */
 export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness> implements AgentManager<H> {
     private readonly harness;
+    private readonly harnessSupportedProviderHints;
     private readonly agentIdGenerator;
     private readonly agentConnectivityResolver;
     private readonly hooksForAgent;
@@ -132,7 +145,9 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
     private restoreFailures;
     private readonly telemetryBus;
     private readonly logBus;
+    private readonly wireBus;
     private readonly router;
+    private readonly wireRouter;
     private readonly unroutedUnsubs;
     private disposed;
     private constructor();
@@ -146,7 +161,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static __build<H extends AgentHarness>(harness: H, agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
+    static __build<H extends AgentHarness>(harness: H, harnessSupportedProviderHints: readonly ProviderHint[], agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
     private init;
     shutdown(): Promise<void>;
     createAgent(projectRoot: string, config?: ConfigOf<H> & {
@@ -172,6 +187,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
     destroyAgent(agentId: string): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
     getRestoreFailures(): RestoreFailure[];
     /**
      * Re-exposes `harness.extensions` typed off `H`. Read-only; the SDK never

package/dist/agent-manager.js

@@ -10,6 +10,7 @@ import { toHarnessConfig } from './harness/harness-config.js';
 import { DefaultAgent } from './agent.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { TelemetryRouter } from './internal/telemetry-router.js';
+import { WireCommunicationRouter } from './internal/wire-communication-router.js';
 import { AgentIdentityStore } from './internal/agent-identity-store.js';
 import { DefaultAgentConnectivityResolver } from './agent-connectivity-resolver.js';
 /**
@@ -23,6 +24,7 @@ import { DefaultAgentConnectivityResolver } from './agent-connectivity-resolver.
  */
 export class DefaultAgentManager {
     harness;
+    harnessSupportedProviderHints;
     agentIdGenerator;
     agentConnectivityResolver;
     hooksForAgent;
@@ -32,11 +34,14 @@ export class DefaultAgentManager {
     restoreFailures = [];
     telemetryBus = new EventBus();
     logBus;
+    wireBus = new EventBus();
     router;
+    wireRouter;
     unroutedUnsubs;
     disposed = false;
-    constructor(harness, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus) {
+    constructor(harness, harnessSupportedProviderHints, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus) {
         this.harness = harness;
+        this.harnessSupportedProviderHints = harnessSupportedProviderHints;
         this.agentConnectivityResolver = agentConnectivityResolver;
         this.hooksForAgent = hooksForAgent;
         this.identityStore = identityStore;
@@ -44,9 +49,15 @@ export class DefaultAgentManager {
         this.clock = clock;
         this.logBus = logBus;
         this.router = new TelemetryRouter(harness);
+        this.wireRouter = new WireCommunicationRouter(harness);
         this.unroutedUnsubs = [
             this.router.unrouted.telemetry.forwardTo(this.telemetryBus),
             this.router.unrouted.log.forwardTo(this.logBus),
+            // Wire-communication uses `forwardWhileSubscribed` — when no consumer subscribes to
+            // `manager.onWireCommunication`, the link stays cold all the way back to the harness bus.
+            // The Claude harness reads `wireBus.listenerCount > 0` before each subprocess spawn and
+            // skips the (expensive) `ANTHROPIC_LOG=debug` env when nobody is listening.
+            this.wireRouter.unrouted.wire.forwardWhileSubscribed(this.wireBus),
         ];
     }
     /**
@@ -59,9 +70,9 @@ export class DefaultAgentManager {
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static async __build(harness, agentConnectivityResolver, hooksForAgent, storageRootFolder, agentIdGenerator, clock, logBus) {
+    static async __build(harness, harnessSupportedProviderHints, agentConnectivityResolver, hooksForAgent, storageRootFolder, agentIdGenerator, clock, logBus) {
         const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
-        const manager = new DefaultAgentManager(harness, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus);
+        const manager = new DefaultAgentManager(harness, harnessSupportedProviderHints, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus);
         await manager.init();
         return manager;
     }
@@ -103,8 +114,10 @@ export class DefaultAgentManager {
         for (const unsub of this.unroutedUnsubs)
             unsub();
         this.router.dispose();
+        this.wireRouter.dispose();
         this.telemetryBus.dispose();
         this.logBus.dispose();
+        this.wireBus.dispose();
         this.disposed = true;
     }
     async createAgent(projectRoot, config = {}, options) {
@@ -157,17 +170,31 @@ export class DefaultAgentManager {
             throw new Error(`projectRoot is not a directory: "${projectRoot}"`);
         }
         const runtime = await this.agentConnectivityResolver.resolve(projectRoot, config);
+        // G8 validation — fail before any harness work runs. The harness's static
+        // `supportedProviderHints` is the source of truth; the resolver picks one of
+        // them. If they disagree, the consumer wired the wrong harness for the model
+        // (e.g. a Claude harness pointed at GPT-5).
+        const providerHint = runtime.modelConnectivityInfo.providerHint;
+        if (!this.harnessSupportedProviderHints.includes(providerHint)) {
+            throw new AgentSDKError(`Harness "${this.harness.harnessId}" does not support providerHint "${providerHint}". Supported: ${this.harnessSupportedProviderHints.join(', ')}.`, AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS);
+        }
         const hooks = this.hooksForAgent?.(agentId, config) ?? {};
-        await this.harness.createAgent(agentId, projectRoot, runtime.llmGatewayClient, toHarnessConfig(config, runtime.orgJwt), { ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}), hooks });
+        await this.harness.createAgent(agentId, projectRoot, runtime.modelConnectivityInfo, toHarnessConfig(config, runtime.orgJwt), { ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}), hooks });
         const agentSlice = this.router.registerAgent(agentId);
-        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
+        // Forward-compat: register the agent against the wire-communication router
+        // too. Today every WireCommunicationEvent lands on the unrouted slice (no
+        // routing fields on the event shape), but the per-agent slice is allocated
+        // symmetrically with the telemetry router so the wiring is in place if/when
+        // the event shape grows an agentId field.
+        this.wireRouter.registerAgent(agentId);
+        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.modelConnectivityInfo, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.harnessSupportedProviderHints, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
         this.telemetryBus.emit({
             type: 'agent-created',
             timestamp: this.clock.now(),
             agentId,
             projectRoot,
-            modelName: runtime.llmGatewayClient.getModel().name,
+            modelName: runtime.modelConnectivityInfo.model.name,
         });
         if (options.rehydrateThreads) {
             // If thread enumeration or session attachment fails, the restore is a full failure
@@ -195,6 +222,7 @@ export class DefaultAgentManager {
             // Swallow secondary failure; the original error (passed to caller) is what matters.
         }
         this.router.unregisterAgent(agentId);
+        this.wireRouter.unregisterAgent(agentId);
         this.agents.delete(agentId);
     }
     getAgentIds() {
@@ -219,6 +247,7 @@ export class DefaultAgentManager {
         if (agent) {
             await agent.destroy();
             this.router.unregisterAgent(agentId);
+            this.wireRouter.unregisterAgent(agentId);
             this.agents.delete(agentId);
         }
         if (failureIndex !== -1) {
@@ -234,6 +263,10 @@ export class DefaultAgentManager {
         this.assertNotDisposed();
         return this.logBus.on(callback);
     }
+    onWireCommunication(callback) {
+        this.assertNotDisposed();
+        return this.wireBus.on(callback);
+    }
     getRestoreFailures() {
         this.assertNotDisposed();
         return [...this.restoreFailures];
@@ -318,7 +351,7 @@ export async function createAgentManager(storageRootFolder, harnessFactory, opti
             `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
     }
     const agentConnectivityResolver = options?.connectivityResolver ?? new DefaultAgentConnectivityResolver();
-    return DefaultAgentManager.__build(harness, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
+    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
 }
 function isSupportedProtocolVersion(version) {
     return (typeof version === 'number' &&

package/dist/agent.d.ts

@@ -1,10 +1,10 @@
-import { type Clock, LogBus, type LogRecord, type OrgConnection, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
+import { type Clock, type JSONWebToken, LogBus, type LogRecord, type OrgConnection, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import type { AgentHarness } from './harness/agent-harness.js';
 import { type AgentConfig } from './harness/harness-config.js';
 import { type ChatSession } from './chat-session.js';
 import type { McpServerInfo } from './mcp-config.js';
-import { type JSONWebToken, type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
-import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+import type { AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+import type { ModelConnectivityInfo, ProviderHint } from './types/model-connectivity-info.js';
 import type { AgentIdentityStore } from './internal/agent-identity-store.js';
 import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
 import type { HooksForAgent } from './types/redaction.js';
@@ -32,8 +32,12 @@ export interface Agent {
     getId(): string;
     /** Returns the project root folder this agent operates within. */
     getProjectRoot(): string;
-    /** Returns the authenticated org connection for the org this agent runs under. */
-    getOrgConnection(): OrgConnection;
+    /**
+     * Returns the authenticated org connection for the org this agent runs under, or
+     * `undefined` if the connectivity resolver did not produce one (non-Salesforce
+     * hosts; api-key resolvers without an `orgAlias`).
+     */
+    getOrgConnection(): OrgConnection | undefined;
     /** Returns the current agent configuration. */
     getAgentConfig(): AgentConfig;
     /**
@@ -73,10 +77,25 @@ export interface Agent {
      * to the live agent (e.g., new instructions, tools, model).
      *
      * @param config - Partial configuration to merge with the current config.
-     * @param options - Optional execution options, including abort signals.
+     * @param options - Optional execution options.
+     *   - `abortSignal` — caller-side cancellation; threaded through to the
+     *     harness's `updateAgent` call.
+     *   - `forceResolve` — when `true`, re-run the connectivity resolver even
+     *     if neither `orgAlias` nor `modelId` is in the partial. Useful when
+     *     a consumer-side state change the resolver reads (e.g. a BYOK
+     *     toggle, a feature-id flip, a rate-limit gate state) needs to land
+     *     on the next outbound call without an `orgAlias` / `modelId` flip
+     *     on the SDK surface. Without this flag, partials that don't touch
+     *     either field skip the resolver to avoid unnecessary work. Note
+     *     that **only** `orgAlias` and `modelId` automatically trigger
+     *     re-resolution when present as own properties of the partial; all
+     *     other `AgentConfig` fields (`instructions`, `tools`, `mcpServers`,
+     *     `rules`, `skills`, `name`, `description`, etc.) flow to the
+     *     harness via `updateAgent` without re-running the resolver.
      */
     updateAgentConfig(config?: AgentConfig, options?: {
         abortSignal?: AbortSignal;
+        forceResolve?: boolean;
     }): Promise<void>;
     /**
      * Create a new chat session (conversation thread) for this agent.
@@ -134,10 +153,11 @@ export declare class DefaultAgent implements Agent {
     private readonly agentId;
     private readonly projectRoot;
     private config;
-    private llmGatewayClient;
+    private modelConnectivityInfo;
     private orgConnection;
     private orgJwt;
     private readonly agentConnectivityResolver;
+    private readonly harnessSupportedProviderHints;
     private readonly hooksForAgent;
     private readonly identityStore;
     private readonly sessions;
@@ -155,7 +175,9 @@ export declare class DefaultAgent implements Agent {
      * @param agentId - Unique identifier for this agent.
      * @param projectRoot - Project folder this agent is allowed to operate within.
      * @param config - Initial agent configuration (instructions, model, tools, etc.).
-     * @param llmGatewayClient - Authenticated LLM gateway client for the resolved org.
+     * @param modelConnectivityInfo - Connectivity bag (model, baseUrl, nativeModelId,
+     *     providerHint, getHeaders) the harness uses to talk to the LLM. Replaced
+     *     on every `updateAgentConfig` re-resolve.
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
@@ -169,7 +191,7 @@ export declare class DefaultAgent implements Agent {
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, modelConnectivityInfo: ModelConnectivityInfo, orgConnection: OrgConnection | undefined, orgJwt: JSONWebToken | undefined, agentConnectivityResolver: AgentConnectivityResolver, harnessSupportedProviderHints: readonly ProviderHint[], hooksForAgent: HooksForAgent | undefined, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
     /**
      * @requirements
      * - MUST return the agent's ID.
@@ -177,7 +199,7 @@ export declare class DefaultAgent implements Agent {
     getId(): string;
     /** Returns the project root folder this agent operates within. */
     getProjectRoot(): string;
-    getOrgConnection(): OrgConnection;
+    getOrgConnection(): OrgConnection | undefined;
     /**
      * @requirements
      * - MUST return a shallow copy of the internal `config` object to prevent external mutation of the agent's state.
@@ -203,6 +225,7 @@ export declare class DefaultAgent implements Agent {
      */
     updateAgentConfig(config?: AgentConfig, options?: {
         abortSignal?: AbortSignal;
+        forceResolve?: boolean;
     }): Promise<void>;
     /**
      * @requirements