@salesforce/sfdx-agent-sdk 0.21.0 → 0.22.0

package/dist/agent.js

@@ -5,8 +5,6 @@
 import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { toHarnessConfig } from './harness/harness-config.js';
 import { DefaultChatSession } from './chat-session.js';
-import {} from '@salesforce/llm-gateway-sdk';
-import { resolveAgentConfigModel } from './agent-connectivity-resolver.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 /**
  * Default implementation of {@link Agent} that delegates
@@ -17,10 +15,11 @@ export class DefaultAgent {
     agentId;
     projectRoot;
     config;
-    llmGatewayClient;
+    modelConnectivityInfo;
     orgConnection;
     orgJwt;
     agentConnectivityResolver;
+    harnessSupportedProviderHints;
     hooksForAgent;
     identityStore;
     sessions = new Map();
@@ -38,7 +37,9 @@ export class DefaultAgent {
      * @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.
@@ -52,15 +53,16 @@ export class DefaultAgent {
      * @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, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, hooksForAgent, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, projectRoot, config, modelConnectivityInfo, orgConnection, orgJwt, agentConnectivityResolver, harnessSupportedProviderHints, hooksForAgent, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.projectRoot = projectRoot;
         this.config = config;
-        this.llmGatewayClient = llmGatewayClient;
+        this.modelConnectivityInfo = modelConnectivityInfo;
         this.orgConnection = orgConnection;
         this.orgJwt = orgJwt;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.harnessSupportedProviderHints = harnessSupportedProviderHints;
         this.hooksForAgent = hooksForAgent;
         this.identityStore = identityStore;
         this.router = router;
@@ -121,29 +123,37 @@ export class DefaultAgent {
     async updateAgentConfig(config = {}, options) {
         this.assertNotDisposed();
         const previousConfig = { ...this.config };
-        const previousClient = this.llmGatewayClient;
+        const previousModelConnectivityInfo = this.modelConnectivityInfo;
         const previousOrgJwt = this.orgJwt;
         const nextConfig = { ...this.config, ...config };
         const orgAliasRequested = Object.prototype.hasOwnProperty.call(config, 'orgAlias');
-        const previousModel = previousClient.getModel();
-        const nextModel = resolveAgentConfigModel(nextConfig.modelId);
-        let nextClient = previousClient;
+        const modelIdRequested = Object.prototype.hasOwnProperty.call(config, 'modelId');
+        let nextModelConnectivityInfo = previousModelConnectivityInfo;
         let nextConnection = this.orgConnection;
         let nextOrgJwt = this.orgJwt;
-        if (orgAliasRequested) {
+        // Any orgAlias OR modelId change re-runs the resolver so the bag
+        // (baseUrl, nativeModelId, providerHint, getHeaders) tracks the current
+        // model/org. `options.forceResolve` is the consumer escape hatch — a
+        // resolver-side state change (BYOK toggle, feature-id flip, rate-limit
+        // gate) doesn't surface as an orgAlias/modelId change but still needs
+        // the bag refreshed.
+        if (orgAliasRequested || modelIdRequested || options?.forceResolve === true) {
             const runtime = await this.agentConnectivityResolver.resolve(this.projectRoot, nextConfig);
-            nextClient = runtime.llmGatewayClient;
+            // G8 — validate the new providerHint before any harness work runs. Same
+            // shape as the manager's installAgent check; modelId changes are the only
+            // post-creation path that can flip the harness ↔ model compatibility, so
+            // catching it here avoids a half-applied state in the harness.
+            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);
+            }
+            nextModelConnectivityInfo = runtime.modelConnectivityInfo;
             nextConnection = runtime.orgConnection;
             nextOrgJwt = runtime.orgJwt;
         }
-        else if (nextModel.name !== previousModel.name) {
-            // Keep the same authenticated client, but pin the updated model.
-            // (If modelId is omitted, the resolver pinned the default at creation time.)
-            nextClient.setModel(nextModel);
-        }
         try {
             const nextHooks = this.hooksForAgent?.(this.agentId, nextConfig) ?? {};
-            await this.harness.updateAgent(this.agentId, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), {
+            await this.harness.updateAgent(this.agentId, nextModelConnectivityInfo, toHarnessConfig(nextConfig, nextOrgJwt), {
                 ...(options?.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
                 hooks: nextHooks,
             });
@@ -152,43 +162,22 @@ export class DefaultAgent {
             // previousConfig and disk state remains the pre-update record.
             await this.identityStore.write(this.agentId, this.projectRoot, nextConfig);
             this.config = nextConfig;
-            this.llmGatewayClient = nextClient;
+            this.modelConnectivityInfo = nextModelConnectivityInfo;
             this.orgConnection = nextConnection;
             this.orgJwt = nextOrgJwt;
-            // Release the old client only once the swap has succeeded. When the orgAlias is unchanged,
-            // nextClient === previousClient and we must NOT dispose.
-            if (nextClient !== previousClient) {
-                previousClient.dispose();
-            }
         }
         catch (error) {
             // Best-effort restoration to keep wrapper and harness state aligned.
+            // Re-apply the previous config through the same primitive. The harness re-diffs
+            // against its current state — if updateAgent partially applied (e.g. some MCP
+            // servers were already cycled), reverting via updateAgent restores them too.
             try {
-                // Restore client model if we mutated it in-place. We re-pin the live previousModel
-                // instance (captured above as previousClient.getModel()) rather than re-resolving from
-                // this.config.modelId, because a JSON-rehydrated config may have a plain object there
-                // that would round-trip through createClaudeModel and lose the original prototype.
-                if (nextClient === previousClient) {
-                    previousClient.setModel(previousModel);
-                }
-                // Re-apply the previous config through the same primitive. The harness re-diffs
-                // against its current state — if updateAgent partially applied (e.g. some MCP
-                // servers were already cycled), reverting via updateAgent restores them too.
                 const previousHooks = this.hooksForAgent?.(this.agentId, previousConfig) ?? {};
-                await this.harness.updateAgent(this.agentId, previousClient, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks });
+                await this.harness.updateAgent(this.agentId, previousModelConnectivityInfo, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks });
             }
             catch {
                 // Ignore restoration errors; rethrow the original failure.
             }
-            // A freshly-resolved client we never installed must be released so its auth resources don't leak.
-            if (nextClient !== previousClient) {
-                try {
-                    nextClient.dispose();
-                }
-                catch {
-                    // Ignore; the original error is the one the caller cares about.
-                }
-            }
             throw error;
         }
     }
@@ -294,7 +283,6 @@ export class DefaultAgent {
         }
         this.sessions.clear();
         await this.harness.destroyAgent(this.agentId);
-        this.llmGatewayClient.dispose();
         this.telemetryBus.emit({
             type: 'agent-destroyed',
             timestamp: this.clock.now(),
@@ -339,11 +327,11 @@ export class DefaultAgent {
         // Live getter — read at call time so getContextUsage() reflects the
         // model bound to the agent right now, not the model that was bound
         // when this session was created. updateAgentConfig() can swap the
-        // underlying LLMGatewayClient mid-life. Per the SDK's Critical
-        // Invariant on context-window reachability, every bound model
-        // exposes a usable `contextWindow`; #507's decoupling work must
-        // preserve that, so this access is contractually safe.
-        const getContextWindow = () => this.llmGatewayClient.getModel().contextWindow;
+        // ModelConnectivityInfo bag mid-life. Per the SDK's Critical Invariant
+        // on context-window reachability, every bound model exposes a usable
+        // `contextWindow`; #507's decoupling work must preserve that, so this
+        // access is contractually safe.
+        const getContextWindow = () => this.modelConnectivityInfo.model.contextWindow;
         const session = new DefaultChatSession(this.harness, this.agentId, threadId, slice, {
             telemetry: this.telemetryBus,
             log: this.logBus,

package/dist/api-key-connectivity-resolver.d.ts

@@ -0,0 +1,110 @@
+import { Model } from './models/index.js';
+import { type OrgConnectionFactory } from '@salesforce/agentic-common';
+import { type AgentConnectivityResolver, type ResolvedConnectivity } from './agent-connectivity-resolver.js';
+import type { AgentConfig } from './harness/harness-config.js';
+import type { ProviderHint } from './types/model-connectivity-info.js';
+/**
+ * Constructor configuration for {@link ApiKeyConnectivityResolver}.
+ *
+ * Covers every named api-key endpoint the SDK reaches: Anthropic-direct,
+ * OpenAI-direct, and LLM-Gateway Express. The differences between them are
+ * data, not behavior — `getApiKey`, `baseUrl`, `providerHint`, and (for the
+ * direct providers) the model-id translation rule.
+ */
+export type ApiKeyConnectivityResolverConfig = {
+    /**
+     * Returns the API key as a string (or a Promise of one). Re-evaluated on
+     * every {@link ApiKeyConnectivityResolver.resolve} call so a rotating key
+     * source (env var read at-call, secret-store fetch) lands without
+     * reconstructing the resolver.
+     */
+    getApiKey: () => string | Promise<string>;
+    /**
+     * Fully-qualified base URL the provider SDK speaks to. The SDK constructs
+     * its per-call paths by concatenation onto this value, so include any API
+     * version segment the provider requires (e.g. `https://api.openai.com/v1`,
+     * not `https://api.openai.com`).
+     */
+    baseUrl: string;
+    /**
+     * Provider hint the harness uses to dispatch onto the right pass-through
+     * builder. Must be one a harness in the consumer's setup actually
+     * supports — `HarnessFactory.supportedProviderHints` is checked
+     * pre-flight by the manager.
+     */
+    providerHint: ProviderHint;
+    /**
+     * Optional translator from canonical {@link Model.name} to the
+     * endpoint-native model id. Direct-provider endpoints want their own
+     * naming (`claude-sonnet-4-6` for Anthropic-direct,
+     * `gpt-4.1-mini-2025-04-14` for OpenAI-direct), while gateway-shaped
+     * endpoints accept the canonical `llmgateway__*` id verbatim. Defaults
+     * to `model.name` (gateway-shape).
+     */
+    nativeModelIdFor?: (model: Model) => string;
+    /**
+     * Optional connection factory. When supplied, the resolver mints an org
+     * connection + JWT alongside the api-key bag — using `config.orgAlias`
+     * if set, otherwise the project's target org via
+     * `OrgConnectionFactory.createFromTargetOrg`. This is the BYOK shape:
+     * api-key authenticates the LLM, org JWT authenticates MCP servers /
+     * identity. Without a factory, both `orgConnection` and `orgJwt` are
+     * omitted from `ResolvedConnectivity`.
+     */
+    connectionFactory?: OrgConnectionFactory;
+};
+/**
+ * Generic api-key {@link AgentConnectivityResolver}. Covers every named
+ * api-key endpoint: Anthropic-direct (`/v1/messages`), OpenAI-direct (Responses
+ * API at `/v1/responses`), and OpenAI-compatible Chat Completions
+ * (`/v1/chat/completions` — LLM Gateway Express, LiteLLM, vLLM, etc.). The
+ * provider-specific differences (URL, model-id translation) are constructor
+ * data.
+ *
+ * **Authentication model.** This resolver always emits
+ * `Authorization: Bearer <api-key>` as a generic credential carrier. The
+ * harness translates that into the provider-native auth shape at the wire:
+ * - Mastra `'bedrock-anthropic'` / `'openai-responses'` / `'openai'` /
+ *   `'openai-compatible'` paths leave `Authorization: Bearer` untouched —
+ *   their gateway / SDK accepts it.
+ * - Mastra `'anthropic'` (direct Anthropic Messages API) peels the bearer
+ *   token into `x-api-key` (the Anthropic Messages API auth shape). The
+ *   harness handles this internally; consumers don't need to write a custom
+ *   resolver to cover the direct-Anthropic case.
+ * - Claude `'bedrock-anthropic'` ships the bearer in `ANTHROPIC_CUSTOM_HEADERS`;
+ *   `'anthropic'` peels it into `ANTHROPIC_API_KEY`.
+ *
+ * Per-call freshness: `getApiKey` is invoked inside the closure on every
+ * `getHeaders()` call, so a rotating source (BYOK toggle, secret-store fetch,
+ * LLMG-Express token refresh) lands without reconstructing the resolver.
+ *
+ * @example
+ * // Anthropic Messages API direct
+ * new ApiKeyConnectivityResolver({
+ *     getApiKey: () => process.env.ANTHROPIC_API_KEY!,
+ *     baseUrl: 'https://api.anthropic.com',
+ *     providerHint: 'anthropic',
+ *     nativeModelIdFor: () => 'claude-sonnet-4-6',
+ * });
+ *
+ * // OpenAI Responses API direct
+ * new ApiKeyConnectivityResolver({
+ *     getApiKey: () => process.env.OPENAI_API_KEY!,
+ *     baseUrl: 'https://api.openai.com/v1',
+ *     providerHint: 'openai',
+ *     nativeModelIdFor: () => 'gpt-4.1-2025-04-14',
+ * });
+ *
+ * // LLM Gateway Express (OpenAI-compatible Chat Completions API)
+ * new ApiKeyConnectivityResolver({
+ *     getApiKey: () => process.env.LLMG_EXPRESS_API_KEY!,
+ *     baseUrl: 'https://express-internal/v1',
+ *     providerHint: 'openai-compatible',
+ * });
+ */
+export declare class ApiKeyConnectivityResolver implements AgentConnectivityResolver {
+    private readonly cfg;
+    constructor(cfg: ApiKeyConnectivityResolverConfig);
+    resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
+    private maybeResolveOrg;
+}

package/dist/api-key-connectivity-resolver.js

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Model } from './models/index.js';
+import { createJWTFromConnection, } from '@salesforce/agentic-common';
+import { resolveAgentConfigModel, } from './agent-connectivity-resolver.js';
+import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+/**
+ * Generic api-key {@link AgentConnectivityResolver}. Covers every named
+ * api-key endpoint: Anthropic-direct (`/v1/messages`), OpenAI-direct (Responses
+ * API at `/v1/responses`), and OpenAI-compatible Chat Completions
+ * (`/v1/chat/completions` — LLM Gateway Express, LiteLLM, vLLM, etc.). The
+ * provider-specific differences (URL, model-id translation) are constructor
+ * data.
+ *
+ * **Authentication model.** This resolver always emits
+ * `Authorization: Bearer <api-key>` as a generic credential carrier. The
+ * harness translates that into the provider-native auth shape at the wire:
+ * - Mastra `'bedrock-anthropic'` / `'openai-responses'` / `'openai'` /
+ *   `'openai-compatible'` paths leave `Authorization: Bearer` untouched —
+ *   their gateway / SDK accepts it.
+ * - Mastra `'anthropic'` (direct Anthropic Messages API) peels the bearer
+ *   token into `x-api-key` (the Anthropic Messages API auth shape). The
+ *   harness handles this internally; consumers don't need to write a custom
+ *   resolver to cover the direct-Anthropic case.
+ * - Claude `'bedrock-anthropic'` ships the bearer in `ANTHROPIC_CUSTOM_HEADERS`;
+ *   `'anthropic'` peels it into `ANTHROPIC_API_KEY`.
+ *
+ * Per-call freshness: `getApiKey` is invoked inside the closure on every
+ * `getHeaders()` call, so a rotating source (BYOK toggle, secret-store fetch,
+ * LLMG-Express token refresh) lands without reconstructing the resolver.
+ *
+ * @example
+ * // Anthropic Messages API direct
+ * new ApiKeyConnectivityResolver({
+ *     getApiKey: () => process.env.ANTHROPIC_API_KEY!,
+ *     baseUrl: 'https://api.anthropic.com',
+ *     providerHint: 'anthropic',
+ *     nativeModelIdFor: () => 'claude-sonnet-4-6',
+ * });
+ *
+ * // OpenAI Responses API direct
+ * new ApiKeyConnectivityResolver({
+ *     getApiKey: () => process.env.OPENAI_API_KEY!,
+ *     baseUrl: 'https://api.openai.com/v1',
+ *     providerHint: 'openai',
+ *     nativeModelIdFor: () => 'gpt-4.1-2025-04-14',
+ * });
+ *
+ * // LLM Gateway Express (OpenAI-compatible Chat Completions API)
+ * new ApiKeyConnectivityResolver({
+ *     getApiKey: () => process.env.LLMG_EXPRESS_API_KEY!,
+ *     baseUrl: 'https://express-internal/v1',
+ *     providerHint: 'openai-compatible',
+ * });
+ */
+export class ApiKeyConnectivityResolver {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async resolve(projectRoot, config) {
+        const model = resolveAgentConfigModel(config.modelId);
+        const { orgConnection, orgJwt } = await this.maybeResolveOrg(projectRoot, config);
+        const cfg = this.cfg;
+        // `||` (not `??`) so a buggy translator returning `''` falls back to `model.name`
+        // rather than producing an empty `nativeModelId` on the wire (which the upstream
+        // would reject as a confusing 400). All sane model ids are non-empty strings, so
+        // collapsing every falsy translator output to the canonical name is correct.
+        const nativeModelId = cfg.nativeModelIdFor?.(model) || model.name;
+        const modelConnectivityInfo = {
+            model,
+            baseUrl: cfg.baseUrl,
+            nativeModelId,
+            providerHint: cfg.providerHint,
+            getHeaders: async () => {
+                const apiKey = await cfg.getApiKey();
+                if (!apiKey) {
+                    // An empty / nullish api-key produces `Authorization: Bearer ` on the wire
+                    // and the upstream rejects with a confusing 401. Surface the misconfig
+                    // locally with a typed error so consumers see "the resolver returned an
+                    // empty key" rather than chasing a 401 through provider logs.
+                    throw new AgentSDKError('ApiKeyConnectivityResolver: getApiKey() returned an empty / nullish value. ' +
+                        'Check the consumer-supplied source.', AgentSDKErrorType.NOT_SUPPORTED);
+                }
+                // Order matters: spread `customHeaders` FIRST so resolver-set auth /
+                // content-type headers win on conflict. Without this, a `Model` instance
+                // built with `customHeaders: { Authorization: '...' }` would silently
+                // shadow the resolver's freshly-fetched key and bypass the empty-key
+                // guard above. `customHeaders` is for vendor-specific labels
+                // (`anthropic-version`, model-tag headers, etc.) — not for auth.
+                return {
+                    ...(model.customHeaders ?? {}),
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json;charset=utf-8',
+                };
+            },
+        };
+        return { modelConnectivityInfo, orgConnection, orgJwt };
+    }
+    async maybeResolveOrg(projectRoot, config) {
+        const factory = this.cfg.connectionFactory;
+        if (!factory) {
+            return {};
+        }
+        const orgConnection = config.orgAlias !== undefined
+            ? await factory.createFromOrgAliasOrUsername(config.orgAlias)
+            : await factory.createFromTargetOrg({ projectRoot });
+        const orgJwt = await createJWTFromConnection(orgConnection);
+        return { orgConnection, orgJwt };
+    }
+}
+//# sourceMappingURL=api-key-connectivity-resolver.js.map

package/dist/errors.d.ts

@@ -7,6 +7,7 @@ export declare const AgentSDKErrorType: {
     readonly INVALID_MESSAGE_CONTENT: "INVALID_MESSAGE_CONTENT";
     readonly MCP_SERVER_DISABLED: "MCP_SERVER_DISABLED";
     readonly MCP_SERVER_NOT_FOUND: "MCP_SERVER_NOT_FOUND";
+    readonly MODEL_NOT_SUPPORTED_BY_HARNESS: "MODEL_NOT_SUPPORTED_BY_HARNESS";
     readonly MULTIMODAL_NOT_SUPPORTED: "MULTIMODAL_NOT_SUPPORTED";
     readonly NOT_SUPPORTED: "NOT_SUPPORTED";
     readonly TOOL_CALL_NOT_FOUND: "TOOL_CALL_NOT_FOUND";

package/dist/errors.js

@@ -11,6 +11,7 @@ export const AgentSDKErrorType = {
     INVALID_MESSAGE_CONTENT: 'INVALID_MESSAGE_CONTENT',
     MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED',
     MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND',
+    MODEL_NOT_SUPPORTED_BY_HARNESS: 'MODEL_NOT_SUPPORTED_BY_HARNESS',
     MULTIMODAL_NOT_SUPPORTED: 'MULTIMODAL_NOT_SUPPORTED',
     NOT_SUPPORTED: 'NOT_SUPPORTED',
     TOOL_CALL_NOT_FOUND: 'TOOL_CALL_NOT_FOUND',

package/dist/harness/agent-harness.d.ts

@@ -5,8 +5,9 @@ import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
 import type { ToolResultInfo } from '../types/tools.js';
 import type { AgentHooks } from '../types/redaction.js';
+import type { WireCommunicationEventCallback } from '../types/wire-communication-event.js';
 import type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
-import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import type { ModelConnectivityInfo } from '../types/model-connectivity-info.js';
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
 /**
  * Opt-in helper that brands a harness type with the {@link AgentConfig}
@@ -91,6 +92,21 @@ export interface AgentHarness {
      * thread-scoped code path, so the SDK can route them to the correct subscriber scope.
      */
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * Subscribe to wire-communication events emitted by the harness — raw
+     * request/response captures of the LLM provider's HTTP traffic. Returns
+     * an unsubscribe function. The events may contain user prompts and PII;
+     * the channel is opt-in and not flowed to log files by default.
+     *
+     * Fidelity may differ between harnesses: the Mastra (in-process) path
+     * emits one `request` + one `response` event per outbound HTTP call,
+     * with the full body and status visible. The Claude (subprocess) path
+     * has the seam wired but does not emit yet — emission would parse
+     * `ANTHROPIC_LOG=debug` stderr from the CLI. Consumers subscribe once
+     * at the `AgentManager` layer; the SDK forwards events upward through
+     * the bus hierarchy the same way it does for telemetry and log records.
+     */
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
     /**
      * Create and register a new agent with the given configuration.
      *
@@ -104,7 +120,10 @@ export interface AgentHarness {
      *
      * @param agentId - ID to register the agent under.
      * @param projectRoot - Project folder the agent is allowed to manipulate files from.
-     * @param llmGatewayClient - Pre-configured LLM gateway client for this agent.
+     * @param modelConnectivityInfo - Connectivity bag the harness uses to talk to the
+     *   LLM (model, baseUrl, nativeModelId, providerHint, getHeaders). Harnesses MUST
+     *   call `getHeaders()` per outbound call (Mastra: per HTTP call; Claude: once
+     *   per subprocess spawn). See {@link ModelConnectivityInfo}.
      * @param config - Engine-facing agent configuration (org resolution omitted).
      * @param options - Optional execution options.
      *   - `abortSignal` — caller-side cancellation; harnesses thread it
@@ -121,7 +140,7 @@ export interface AgentHarness {
      *     wrap their hook bodies in `try`/`catch` themselves when they
      *     want a richer fail-closed substitute.
      */
-    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>;
@@ -194,7 +213,10 @@ export interface AgentHarness {
      *   `Agent.updateAgentConfig` after this method resolves).
      *
      * @param agentId - ID of the agent to update.
-     * @param llmGatewayClient - LLM gateway client bound to the next config's org / model.
+     * @param modelConnectivityInfo - Connectivity bag bound to the next config's
+     *   org / model (replaces the live bag in the harness's per-agent map; the
+     *   `getHeaders` closure may close over a fresh JWT or rate-limit gate
+     *   value). See {@link ModelConnectivityInfo}.
      * @param config - Engine-facing agent configuration to apply.
      * @param options - Optional execution options.
      *   - `abortSignal` — caller-side cancellation; harnesses thread it
@@ -208,7 +230,7 @@ export interface AgentHarness {
      *     config (and so a rollback `updateAgent(previousConfig)` restores
      *     the prior hook bag too).
      */
-    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;

package/dist/harness/harness-bus-owner.d.ts

@@ -1,5 +1,6 @@
 import { LogBus, type LogRecord, type Unsubscribe } from '@salesforce/agentic-common';
 import type { TelemetryEvent, TelemetryEventCallback } from '../types/telemetry-events.js';
+import type { WireCommunicationEvent, WireCommunicationEventCallback } from '../types/wire-communication-event.js';
 /**
  * Composition helper used by `AgentHarness` implementations to own telemetry and log buses.
  *
@@ -13,6 +14,7 @@ import type { TelemetryEvent, TelemetryEventCallback } from '../types/telemetry-
 export declare class HarnessBusOwner {
     private readonly telemetryBus;
     private readonly logBus;
+    private readonly wireBus;
     private disposed;
     /**
      * Returns the log bus so harness implementations can hand it to pure helpers (e.g. message
@@ -23,6 +25,21 @@ export declare class HarnessBusOwner {
     getLogBus(): LogBus | undefined;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
+    emitWireCommunication(event: WireCommunicationEvent): void;
+    /**
+     * Returns `true` when the wire-communication channel has at least one downstream subscriber
+     * reaching all the way to a consumer. The bus chain
+     * `harness.wireBus → router slice → manager.wireBus → consumer.onWireCommunication`
+     * is wired with `forwardWhileSubscribed`, so a consumer-less chain leaves
+     * `wireBus.listenerCount === 0` and an expensive harness-side producer (e.g. the Claude
+     * subprocess `ANTHROPIC_LOG=debug` parser) can short-circuit before paying any cost.
+     *
+     * Returns `false` after `dispose()`. Read this lazily — listener-presence transitions
+     * happen between calls (subscribe / unsubscribe) and the value reflects current state at
+     * call time only.
+     */
+    hasWireCommunicationSubscribers(): boolean;
     emitTelemetry(event: TelemetryEvent): void;
     emitLog(record: LogRecord): void;
     logDebug(message: string, context?: Record<string, unknown>): void;

package/dist/harness/harness-bus-owner.js

@@ -17,6 +17,7 @@ import { AgentSDKError, AgentSDKErrorType } from '../errors.js';
 export class HarnessBusOwner {
     telemetryBus = new EventBus();
     logBus = new LogBus();
+    wireBus = new EventBus();
     disposed = false;
     /**
      * Returns the log bus so harness implementations can hand it to pure helpers (e.g. message
@@ -37,6 +38,31 @@ export class HarnessBusOwner {
         this.assertNotDisposed();
         return this.logBus.on(callback);
     }
+    onWireCommunication(callback) {
+        this.assertNotDisposed();
+        return this.wireBus.on(callback);
+    }
+    emitWireCommunication(event) {
+        this.assertNotDisposed();
+        this.wireBus.emit(event);
+    }
+    /**
+     * Returns `true` when the wire-communication channel has at least one downstream subscriber
+     * reaching all the way to a consumer. The bus chain
+     * `harness.wireBus → router slice → manager.wireBus → consumer.onWireCommunication`
+     * is wired with `forwardWhileSubscribed`, so a consumer-less chain leaves
+     * `wireBus.listenerCount === 0` and an expensive harness-side producer (e.g. the Claude
+     * subprocess `ANTHROPIC_LOG=debug` parser) can short-circuit before paying any cost.
+     *
+     * Returns `false` after `dispose()`. Read this lazily — listener-presence transitions
+     * happen between calls (subscribe / unsubscribe) and the value reflects current state at
+     * call time only.
+     */
+    hasWireCommunicationSubscribers() {
+        if (this.disposed)
+            return false;
+        return this.wireBus.listenerCount > 0;
+    }
     emitTelemetry(event) {
         this.assertNotDisposed();
         this.telemetryBus.emit(event);
@@ -67,6 +93,7 @@ export class HarnessBusOwner {
         }
         this.telemetryBus.dispose();
         this.logBus.dispose();
+        this.wireBus.dispose();
         this.disposed = true;
     }
     assertNotDisposed() {

package/dist/harness/harness-config.d.ts

@@ -1,6 +1,7 @@
 import type { ToolDefinition } from '../types/tools.js';
 import type { MCPConfiguration } from '../mcp-config.js';
-import type { JSONWebToken, Model, ModelName } from '@salesforce/llm-gateway-sdk';
+import type { JSONWebToken } from '@salesforce/agentic-common';
+import type { Model, ModelName } from '../models/index.js';
 /**
  * Configuration for an agent's behavior and capabilities.
  * This excludes identity; `agentId` is handled separately.
@@ -20,7 +21,7 @@ export type AgentConfig = {
      * Accepts either a {@link ModelName} enum value (the typical case for in-tree models) or a
      * pre-built {@link Model} instance. The instance form lets consumers opt into a Claude
      * variant published on the gateway before the SDK has been updated — see
-     * `createClaudeModel(gatewayId, overrides)` from `@salesforce/llm-gateway-sdk`.
+     * `createClaudeModel(gatewayId, overrides)` re-exported from this package.
      */
     modelId?: ModelName | Model;
     /** Human-readable name for the agent. */

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

@@ -1,4 +1,5 @@
 import type { AgentHarness } from './agent-harness.js';
+import type { ProviderHint } from '../types/model-connectivity-info.js';
 /**
  * Constructs an {@link AgentHarness} on demand.
  *
@@ -17,5 +18,17 @@ export interface HarnessFactory<H extends AgentHarness = AgentHarness> {
     readonly harnessId: string;
     /** SDK-to-harness protocol version implemented by the harness this factory builds. */
     readonly protocolVersion: number;
+    /**
+     * Wire shapes the constructed harness can drive.
+     *
+     * The manager validates the resolved
+     * {@link import('../types/model-connectivity-info.js').ModelConnectivityInfo.providerHint}
+     * against this list at `createAgent` and `updateAgentConfig` time, throwing
+     * `AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS` before any harness
+     * work runs when no factory advertises support.
+     *
+     * Static per-class — the manager reads it without instantiating the harness.
+     */
+    readonly supportedProviderHints: readonly ProviderHint[];
     create(storageRootFolder: string): Promise<H>;
 }

package/dist/harness/stream-input.d.ts

@@ -1,4 +1,4 @@
-import { type MultimodalFile } from '@salesforce/llm-gateway-sdk';
+import type { MultimodalFile } from '../models/index.js';
 import type { FilePart, ImagePart, MessagePart, TextPart } from '../types/messages.js';
 /**
  * The subset of {@link MessagePart} that is valid as user `stream()` input: plain `text` plus the
@@ -15,8 +15,10 @@ export type InputMessagePart = TextPart | ImagePart | FilePart;
  *
  * Order of operations:
  *   1. Collect `image` / `file` parts into a {@link MultimodalFile} list and hand them to
- *      `validateFiles` (per-model + global gateway caps). An {@link LLMGClientError} is mapped to
- *      `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)`; any other throw propagates unchanged.
+ *      `validateFiles` (per-model + global gateway caps). The standard
+ *      {@link validateMultimodalFiles} helper throws
+ *      `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)` directly on a cap/format violation; any other
+ *      throw propagates unchanged.
  *   2. Lower each part via `mapPart`. A `reasoning` / `tool-call` / `tool-result` part is not valid
  *      stream input and throws `AgentSDKError(INVALID_MESSAGE_CONTENT)` before `mapPart` sees it.
  *
@@ -25,8 +27,10 @@ export type InputMessagePart = TextPart | ImagePart | FilePart;
  * failure rejects the harness's `stream()` promise pre-stream rather than mid-iteration.
  *
  * @param parts - the user message parts to validate and lower.
- * @param validateFiles - per-harness file validation (e.g. `validateMultimodalFiles(files, model)`)
- *   that throws `LLMGClientError` on a cap/format violation and no-ops for text-only input.
+ * @param validateFiles - per-harness file validation (typically
+ *   `(files) => validateMultimodalFiles(files, model)`) that throws
+ *   `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)` on a cap/format violation and no-ops for text-only
+ *   input.
  * @param mapPart - lowers one validated input part into the harness's content-block shape.
  * @returns the lowered blocks, in the original part order.
  */