@salesforce/sfdx-agent-sdk 0.51.0 → 0.53.0

package/dist/agent.js

@@ -3,10 +3,22 @@
  * See LICENSE.txt for license terms.
  */
 import { LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
-import { toHarnessConfig } from './harness/harness-config.js';
+import { toHarnessConfig, } from './harness/harness-config.js';
+import { normalizeMcpAuthProviders } from './mcp-auth.js';
 import { DefaultChatSession } from './chat-session.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { createTelemetryBus } from './types/telemetry-events.js';
+/**
+ * Resolves the next consumer-metadata value from the current value and an optional mutation. `replace` deep-clones the
+ * incoming value so the stored copy is isolated from later caller mutation; `clear` yields `undefined`; an absent
+ * mutation leaves the current value untouched.
+ */
+function applyConsumerMetadataMutation(current, mutation) {
+    if (mutation === undefined) {
+        return current;
+    }
+    return mutation.action === 'replace' ? structuredClone(mutation.value) : undefined;
+}
 /**
  * Default implementation of {@link Agent} that delegates
  * agent and thread operations to an {@link AgentHarness}.
@@ -16,12 +28,13 @@ export class DefaultAgent {
     agentId;
     projectRoot;
     config;
+    consumerMetadata;
     modelConnectivityInfo;
     orgConnection;
     orgJwt;
     agentConnectivityResolver;
     harnessSupportedProviderHints;
-    hooksForAgent;
+    resolvers;
     identityStore;
     sessions = new Map();
     sessionSliceUnregisters = new Map();
@@ -40,33 +53,37 @@ 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 consumerMetadata - Initial SDK-owned opaque consumer metadata (or `undefined`). Persisted beside
+     *     `config`; never forwarded to the harness. Mutated via `updateAgentState`.
      * @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.
-     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
-     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
-     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
-     *     the consumer didn't pass a `hooksForAgent`.
+     * @param resolvers - Per-agent runtime resolvers ({@link AgentRuntimeResolvers}: `hooksForAgent`,
+     *     `mcpAuthProviderResolver`) supplied by the SDK consumer at `createAgentManager` time. The agent re-invokes
+     *     them on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the rollback path)
+     *     so what the harness sees always reflects the current persisted config. Each member is `undefined` when the
+     *     consumer didn't pass it.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @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, modelConnectivityInfo, orgConnection, orgJwt, agentConnectivityResolver, harnessSupportedProviderHints, hooksForAgent, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, projectRoot, config, consumerMetadata, modelConnectivityInfo, orgConnection, orgJwt, agentConnectivityResolver, harnessSupportedProviderHints, resolvers, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.projectRoot = projectRoot;
         this.config = config;
+        this.consumerMetadata = consumerMetadata;
         this.modelConnectivityInfo = modelConnectivityInfo;
         this.orgConnection = orgConnection;
         this.orgJwt = orgJwt;
         this.agentConnectivityResolver = agentConnectivityResolver;
         this.harnessSupportedProviderHints = harnessSupportedProviderHints;
-        this.hooksForAgent = hooksForAgent;
+        this.resolvers = resolvers;
         this.identityStore = identityStore;
         this.router = router;
         this.clock = clock;
@@ -101,6 +118,15 @@ export class DefaultAgent {
         this.assertNotDisposed();
         return { ...this.config };
     }
+    /**
+     * @requirements
+     * - MUST return a deep copy so a caller cannot mutate the agent's persisted consumer metadata in place.
+     * - MUST return `undefined` when no metadata has been set.
+     */
+    getConsumerMetadata() {
+        this.assertNotDisposed();
+        return this.consumerMetadata === undefined ? undefined : structuredClone(this.consumerMetadata);
+    }
     getMcpServerInfo() {
         this.assertNotDisposed();
         return this.harness.getMcpServerInfo(this.agentId);
@@ -126,11 +152,41 @@ export class DefaultAgent {
      *   against its current (possibly partially-updated) state and reverts only the actual deltas.
      */
     async updateAgentConfig(config = {}, options) {
+        return this.updateAgentState({ config }, options);
+    }
+    /**
+     * @requirements
+     * - MUST merge `update.config` (when present) with the internal `config` object; `agentId` stays unchanged.
+     * - MUST apply the merged config to the harness via `this.harness.updateAgent(...)` ONLY when `update.config`
+     *   is present. A metadata-only update MUST NOT call the harness at all (no server cycling, no resolver run).
+     * - MUST compute the next consumer metadata from `update.consumerMetadata`: `replace` stores a deep copy of the
+     *   value; `clear` removes it; an absent mutation leaves it unchanged.
+     * - MUST persist config + metadata together in ONE `this.identityStore.write(...)` after any `harness.updateAgent`
+     *   succeeds and before the in-memory swaps, so a write failure rolls back through the same catch path.
+     * - MUST preserve BOTH the previous config AND the previous metadata if `updateAgent` or persistence fails.
+     */
+    async updateAgentState(update, options) {
         this.assertNotDisposed();
+        const { config, consumerMetadata: metadataMutation } = update;
         const previousConfig = { ...this.config };
+        const previousConsumerMetadata = this.consumerMetadata;
         const previousModelConnectivityInfo = this.modelConnectivityInfo;
         const previousOrgJwt = this.orgJwt;
-        const nextConfig = { ...this.config, ...config };
+        const nextConfig = config === undefined ? this.config : { ...this.config, ...config };
+        const nextConsumerMetadata = applyConsumerMetadataMutation(this.consumerMetadata, metadataMutation);
+        // A metadata-only update never touches the harness, the resolver, or the connectivity bag — it just
+        // rewrites the persisted record and swaps the in-memory metadata.
+        if (config === undefined) {
+            try {
+                await this.writeIdentity(nextConfig, nextConsumerMetadata);
+                this.consumerMetadata = nextConsumerMetadata;
+            }
+            catch (error) {
+                this.consumerMetadata = previousConsumerMetadata;
+                throw error;
+            }
+            return;
+        }
         const orgAliasRequested = Object.prototype.hasOwnProperty.call(config, 'orgAlias');
         const modelIdRequested = Object.prototype.hasOwnProperty.call(config, 'modelId');
         let nextModelConnectivityInfo = previousModelConnectivityInfo;
@@ -157,16 +213,19 @@ export class DefaultAgent {
             nextOrgJwt = runtime.orgJwt;
         }
         try {
-            const nextHooks = this.hooksForAgent?.(this.agentId, nextConfig) ?? {};
+            const nextHooks = this.resolvers.hooksForAgent?.(this.agentId, nextConfig) ?? {};
+            const nextMcpAuthProviders = normalizeMcpAuthProviders(nextConfig.mcpServers, this.resolvers.mcpAuthProviderResolver?.(this.agentId, nextConfig));
             await this.harness.updateAgent(this.agentId, nextModelConnectivityInfo, toHarnessConfig(nextConfig, nextOrgJwt), {
                 ...(options?.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
                 hooks: nextHooks,
+                mcpAuthProviders: nextMcpAuthProviders,
             });
             // Persist before the in-memory swaps so a write failure flows through the same
             // catch block as an updateAgent failure: the rollback re-runs updateAgent against
             // previousConfig and disk state remains the pre-update record.
-            await this.identityStore.write(this.agentId, this.projectRoot, nextConfig);
+            await this.writeIdentity(nextConfig, nextConsumerMetadata);
             this.config = nextConfig;
+            this.consumerMetadata = nextConsumerMetadata;
             this.modelConnectivityInfo = nextModelConnectivityInfo;
             this.orgConnection = nextConnection;
             this.orgJwt = nextOrgJwt;
@@ -177,8 +236,9 @@ export class DefaultAgent {
             // against its current state — if updateAgent partially applied (e.g. some MCP
             // servers were already cycled), reverting via updateAgent restores them too.
             try {
-                const previousHooks = this.hooksForAgent?.(this.agentId, previousConfig) ?? {};
-                await this.harness.updateAgent(this.agentId, previousModelConnectivityInfo, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks });
+                const previousHooks = this.resolvers.hooksForAgent?.(this.agentId, previousConfig) ?? {};
+                const previousMcpAuthProviders = normalizeMcpAuthProviders(previousConfig.mcpServers, this.resolvers.mcpAuthProviderResolver?.(this.agentId, previousConfig));
+                await this.harness.updateAgent(this.agentId, previousModelConnectivityInfo, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks, mcpAuthProviders: previousMcpAuthProviders });
             }
             catch {
                 // Ignore restoration errors; rethrow the original failure.
@@ -186,6 +246,19 @@ export class DefaultAgent {
             throw error;
         }
     }
+    /**
+     * Writes the identity record, calling `identityStore.write` with a 4th argument only when consumer metadata is
+     * present. Omitting the argument (rather than passing `undefined`) keeps a config-only write byte-identical to the
+     * pre-metadata call shape and clears any previously-persisted metadata.
+     */
+    async writeIdentity(config, consumerMetadata) {
+        if (consumerMetadata === undefined) {
+            await this.identityStore.write(this.agentId, this.projectRoot, config);
+        }
+        else {
+            await this.identityStore.write(this.agentId, this.projectRoot, config, consumerMetadata);
+        }
+    }
     /**
      * @requirements
      * - MUST delegate to `this.harness.createThread(this.config.agentId)` to generate a new thread ID.

package/dist/errors.d.ts

@@ -4,6 +4,7 @@ export declare const AgentSDKErrorType: {
     readonly COMPACTION_FAILED: 'COMPACTION_FAILED';
     readonly DISPOSED: 'DISPOSED';
     readonly INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS';
+    readonly INVALID_MCP_AUTH_CONFIG: 'INVALID_MCP_AUTH_CONFIG';
     readonly INVALID_MESSAGE_CONTENT: 'INVALID_MESSAGE_CONTENT';
     readonly MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED';
     readonly MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND';

package/dist/errors.js

@@ -8,6 +8,7 @@ export const AgentSDKErrorType = {
     COMPACTION_FAILED: 'COMPACTION_FAILED',
     DISPOSED: 'DISPOSED',
     INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
+    INVALID_MCP_AUTH_CONFIG: 'INVALID_MCP_AUTH_CONFIG',
     INVALID_MESSAGE_CONTENT: 'INVALID_MESSAGE_CONTENT',
     MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED',
     MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND',

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

@@ -1,5 +1,5 @@
 import type { LogRecord, Unsubscribe } from '@salesforce/agentic-common';
-import type { McpServerInfo } from '../mcp-config.js';
+import type { McpServerInfo, McpAuthProviders } from '../mcp-config.js';
 import type { ChatStreamResult } from '../types/events.js';
 import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
@@ -142,11 +142,20 @@ export interface AgentHarness {
      *     native error path so the original tool output never leaks to the
      *     model. The SDK does not own fail-closed semantics; consumers
      *     wrap their hook bodies in `try`/`catch` themselves when they
-     *     want a richer fail-closed substitute.
+     *   want a richer fail-closed substitute.
+     *   - `mcpAuthProviders` — per-agent OAuth provider map (remote MCP server
+     *     name → {@link McpOAuthClientProvider}), resolved by the SDK from
+     *     `createAgentManager`'s `mcpAuthProviderResolver` and already normalized
+     *     (Salesforce URLs / stdio / disabled / missing servers dropped, static-
+     *     Authorization conflicts rejected — see `normalizeMcpAuthProviders`).
+     *     Providers are runtime bindings, NEVER part of `HarnessAgentConfig`;
+     *     harnesses store the map on per-agent state and forward `providers[name]`
+     *     into the remote transport for that server.
      */
     createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
+        mcpAuthProviders?: McpAuthProviders;
     }): Promise<void>;
     /**
      * Destroy an agent and release its resources (MCP connections, workspace, memory).
@@ -179,9 +188,12 @@ export interface AgentHarness {
      *   matching the rest of the cross-harness contract.
      * - preserve the in-memory MCP client (and its discovered tool catalog)
      *   for any server name whose config is `mcpServerConfigEqual` to the
-     *   currently-applied one. No transport teardown, no `tools/list`
-     *   re-run, no per-server discovery telemetry.
-     * - cycle (disconnect-then-reconnect) any server whose config differs.
+     *   currently-applied one AND whose applied OAuth provider reference (from
+     *   `options.mcpAuthProviders`) is unchanged. No transport teardown, no
+     *   `tools/list` re-run, no per-server discovery telemetry.
+     * - cycle (disconnect-then-reconnect) any server whose config differs OR
+     *   whose applied provider reference changed (a swapped provider instance
+     *   must cycle the server so the new one owns auth).
      * - disconnect any server present in the currently-applied config but
      *   absent from the next config, removing it from
      *   `getMcpServerInfo()`'s output.
@@ -233,10 +245,15 @@ export interface AgentHarness {
      *     re-resolved on every `updateAgent` so consumers can vary hooks by
      *     config (and so a rollback `updateAgent(previousConfig)` restores
      *     the prior hook bag too).
+     *   - `mcpAuthProviders` — per-agent normalized OAuth provider map, re-resolved
+     *     on every `updateAgent` (so a provider swap cycles its server, and a
+     *     rollback `updateAgent(previousConfig)` restores the prior providers).
+     *     Same runtime-only semantics as `createAgent.options.mcpAuthProviders`.
      */
     updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
+        mcpAuthProviders?: McpAuthProviders;
     }): Promise<void>;
     /**
      * List the IDs of all currently registered agents.

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

@@ -1,7 +1,8 @@
 import type { Decision, ToolDefinition, ToolPolicyRule } from '../types/tools.js';
-import type { MCPConfiguration } from '../mcp-config.js';
+import type { MCPConfiguration, McpAuthProviders } from '../mcp-config.js';
 import type { JSONWebToken } from '@salesforce/agentic-common';
 import type { Model, ModelName } from '../models/index.js';
+import type { JsonValue } from '../types/session-context.js';
 /**
  * Configuration for an agent's behavior and capabilities.
  * This excludes identity; `agentId` is handled separately.
@@ -88,6 +89,25 @@ export type AgentConfig = {
      */
     defaultToolDecision?: Decision;
 };
+/**
+ * Resolves the per-agent OAuth {@link McpAuthProviders} map (remote MCP server
+ * name → provider) from the agent's id and the config the SDK has on file.
+ * Invoked by `AgentManager` once per agent install (`createAgent`, boot-time
+ * restore) and by `Agent.updateAgentConfig`; the resolved map is normalized by
+ * the SDK (see `normalizeMcpAuthProviders`) and threaded to the harness via
+ * `AgentHarness.createAgent` / `updateAgent`'s `options.mcpAuthProviders`.
+ *
+ * This is the seam that keeps credential-bearing provider objects OFF the
+ * persisted {@link AgentConfig}: providers are supplied here at runtime, never
+ * serialized. Mirrors `HooksForAgent`.
+ *
+ * The callback is sync — the SDK does not await. Return **stable, pre-constructed**
+ * provider instances: returning a NEW provider object for a server on each call
+ * intentionally cycles that server on every update (reference identity is how a
+ * provider swap is detected). Consumers needing async provider setup pre-construct
+ * before returning.
+ */
+export type McpAuthProviderResolver = (agentId: string, config: AgentConfig) => McpAuthProviders | undefined;
 /**
  * Harness-facing configuration for creating/updating an agent.
  *
@@ -121,6 +141,42 @@ export type HarnessAgentConfig = Omit<AgentConfig, 'orgAlias'> & {
  * `test/harness/harness-config.test.ts` that asserts unknown fields survive.
  */
 export declare function toHarnessConfig(config: AgentConfig, orgJwt?: JSONWebToken): HarnessAgentConfig;
+/**
+ * A mutation applied to an agent's persisted consumer metadata by
+ * {@link AgentStateUpdate}. Two explicit actions rather than a bare value so
+ * "set it to this" is distinguishable from "delete it": `undefined` reads as
+ * "field omitted / leave unchanged" and `null` is a legal JSON value a
+ * consumer may legitimately want to store, so neither can double as a clear
+ * signal.
+ *
+ * - `replace` — set the metadata to `value` (stored as an opaque deep copy).
+ * - `clear` — remove the metadata entirely (a subsequent
+ *   {@link Agent.getConsumerMetadata} returns `undefined`).
+ */
+export type ConsumerMetadataMutation = {
+    action: 'replace';
+    value: JsonValue;
+} | {
+    action: 'clear';
+};
+/**
+ * A single atomic update to an agent's persisted state, applied by
+ * {@link Agent.updateAgentState}. Either or both members may be present:
+ *
+ * - `config` — a partial {@link AgentConfig} merged into the live config and
+ *   applied to the harness (identical semantics to {@link Agent.updateAgentConfig}).
+ * - `consumerMetadata` — a {@link ConsumerMetadataMutation} on the agent's
+ *   opaque consumer metadata. This metadata is SDK-owned persistence only: it
+ *   is never placed on {@link AgentConfig}, never passed through
+ *   {@link toHarnessConfig}, and never forwarded to the harness.
+ *
+ * When both are present the SDK commits them in one persistence write, so a
+ * failed update leaves config and metadata at their previous values together.
+ */
+export type AgentStateUpdate = {
+    config?: AgentConfig;
+    consumerMetadata?: ConsumerMetadataMutation;
+};
 /**
  * Per-call options controlling streaming behavior.
  */

package/dist/harness/public.d.ts

@@ -45,6 +45,7 @@ export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './
 export type { AgentHooks } from '../types/redaction.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
 export { mcpServerConfigEqual } from '../mcp-config.js';
+export type { McpAuthProviders, McpOAuthClientProvider } from '../mcp-config.js';
 export { HarnessBusOwner } from './harness-bus-owner.js';
 export { lowerStreamInput, type InputMessagePart } from './stream-input.js';
 export { GenSink } from './gen-sink.js';

package/dist/index.d.ts

@@ -6,9 +6,9 @@ export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMa
 export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-resolver.js';
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentHooks, HooksForAgent, ToolResultRedactor, ToolResultRedactionInput, ToolResultRedactionResult, } from './types/redaction.js';
-export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
+export type { AgentConfig, AgentStateUpdate, ConsumerMetadataMutation, HarnessAgentConfig, McpAuthProviderResolver, StreamOptions, } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
-export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
+export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpOAuthClientProvider, McpAuthProviders, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles, ACCEPTED_MODEL_WIRE_IDS, } from './models/index.js';
 export type { ClaudeModelOverrides, MultimodalFile, SupportedFileFormat, ThinkingMode } from './models/index.js';
@@ -28,7 +28,7 @@ export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent,
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 export type { EnvironmentFields } from '@salesforce/agentic-common';
 export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
-export { resolveMcpServerHeaders } from './mcp-auth.js';
+export { resolveMcpServerHeaders, isSalesforcePlatformMcpUrl } from './mcp-auth.js';
 export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';
 export type { JSONWebToken, JWTOptions, RequiredJWTHeaders, RequiredJWTPayload } from '@salesforce/agentic-common';
 export { Workspace } from './workspace.js';

package/dist/index.js

@@ -23,6 +23,6 @@ export { WireCommunicationFileWriter, } from './wire-communication-file-writer.j
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
 // ── MCP Auth ────────────────────────────────────────────────────────
-export { resolveMcpServerHeaders } from './mcp-auth.js';
+export { resolveMcpServerHeaders, isSalesforcePlatformMcpUrl } from './mcp-auth.js';
 export { Workspace } from './workspace.js';
 //# sourceMappingURL=index.js.map

package/dist/internal/agent-identity-store.d.ts

@@ -1,9 +1,11 @@
 import { type LogBus } from '@salesforce/agentic-common';
 import type { AgentConfig } from '../harness/harness-config.js';
+import type { JsonValue } from '../types/session-context.js';
 export type AgentIdentityRecord = {
     agentId: string;
     projectRoot: string;
     config: AgentConfig;
+    consumerMetadata?: JsonValue;
 };
 /**
  * SDK-owned persistence for the agent-identity triple
@@ -33,7 +35,7 @@ export declare class AgentIdentityStore {
      */
     private readonly inflightWrites;
     constructor(storageRootFolder: string, harnessId: string, logBus: LogBus);
-    write(agentId: string, projectRoot: string, config: AgentConfig): Promise<void>;
+    write(agentId: string, projectRoot: string, config: AgentConfig, consumerMetadata?: JsonValue): Promise<void>;
     private writeImmediate;
     remove(agentId: string): Promise<void>;
     list(): Promise<AgentIdentityRecord[]>;

package/dist/internal/agent-identity-store.js

@@ -39,11 +39,13 @@ export class AgentIdentityStore {
         this.harnessId = harnessId;
         this.logBus = logBus;
     }
-    async write(agentId, projectRoot, config) {
+    async write(agentId, projectRoot, config, consumerMetadata) {
         const previous = this.inflightWrites.get(agentId) ?? Promise.resolve();
         // `.catch(() => undefined)` so a previous failure doesn't poison the next caller's await.
         // Each caller still observes its own write's success or failure via the returned promise.
-        const next = previous.catch(() => undefined).then(() => this.writeImmediate(agentId, projectRoot, config));
+        const next = previous
+            .catch(() => undefined)
+            .then(() => this.writeImmediate(agentId, projectRoot, config, consumerMetadata));
         this.inflightWrites.set(agentId, next);
         try {
             await next;
@@ -56,7 +58,7 @@ export class AgentIdentityStore {
             }
         }
     }
-    async writeImmediate(agentId, projectRoot, config) {
+    async writeImmediate(agentId, projectRoot, config, consumerMetadata) {
         const dir = this.dir();
         await mkdir(dir, { recursive: true });
         const payload = {
@@ -65,6 +67,7 @@ export class AgentIdentityStore {
             agentId,
             projectRoot,
             config,
+            ...(consumerMetadata !== undefined ? { consumerMetadata } : {}),
         };
         const target = join(dir, `${agentId}.json`);
         const tmp = `${target}.tmp`;
@@ -130,6 +133,7 @@ export class AgentIdentityStore {
                 agentId: parsed.agentId,
                 projectRoot: parsed.projectRoot,
                 config: parsed.config,
+                ...(parsed.consumerMetadata !== undefined ? { consumerMetadata: parsed.consumerMetadata } : {}),
             });
         }
         return records;

package/dist/mcp-auth.d.ts

@@ -1,4 +1,5 @@
 import type { JSONWebToken } from '@salesforce/agentic-common';
+import type { MCPConfiguration, McpAuthProviders } from './mcp-config.js';
 /**
  * Returns true if the URL matches a Salesforce Hosted MCP Server endpoint.
  * Covers all environments (prod, dev, test, perf, stage) and all API versions
@@ -18,3 +19,22 @@ export declare function isSalesforcePlatformMcpUrl(url: string | URL): boolean;
  * @returns The resolved headers — original headers plus any injected auth.
  */
 export declare function resolveMcpServerHeaders(url: string | URL, orgJwt: JSONWebToken | undefined, headers?: Record<string, string>): Promise<Record<string, string>>;
+/**
+ * Normalizes the raw provider map returned by a consumer's
+ * `mcpAuthProviderResolver` into the map the harness may act on, enforcing the
+ * "one Authorization owner per server" rule centrally (so no harness reimplements
+ * this policy). For each provider entry, keyed by server name:
+ *
+ * - **Dropped** (provider ignored) when the named server is missing, is a stdio
+ *   server, is disabled, or is a Salesforce Platform URL. Salesforce URLs are
+ *   authenticated by the rotating org JWT, which owns auth there; forwarding a
+ *   provider alongside it would arm two competing Authorization owners.
+ * - **Rejected** (throws) when the server carries a static `Authorization`
+ *   header AND a provider — the MCP SDK transport spreads static `requestInit`
+ *   headers OVER the provider token, so the static header would silently win and
+ *   strand the provider in a 401 loop. Failing loud at resolve time beats a
+ *   silent auth failure at runtime.
+ *
+ * Returns a fresh, reference-only map (the same provider instances, never mutated).
+ */
+export declare function normalizeMcpAuthProviders(mcpServers: MCPConfiguration | undefined, resolved: McpAuthProviders | undefined): McpAuthProviders;

package/dist/mcp-auth.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 const SALESFORCE_PLATFORM_MCP_URL_REGEX = /^https:\/\/((dev|test|perf|stage)\.)?api\.salesforce\.com\/platform\/mcp\//;
 /**
  * Returns true if the URL matches a Salesforce Hosted MCP Server endpoint.
@@ -37,4 +38,40 @@ export async function resolveMcpServerHeaders(url, orgJwt, headers = {}) {
 function hasAuthorizationHeader(headers) {
     return Object.keys(headers).some((key) => key.toLowerCase() === 'authorization');
 }
+/**
+ * Normalizes the raw provider map returned by a consumer's
+ * `mcpAuthProviderResolver` into the map the harness may act on, enforcing the
+ * "one Authorization owner per server" rule centrally (so no harness reimplements
+ * this policy). For each provider entry, keyed by server name:
+ *
+ * - **Dropped** (provider ignored) when the named server is missing, is a stdio
+ *   server, is disabled, or is a Salesforce Platform URL. Salesforce URLs are
+ *   authenticated by the rotating org JWT, which owns auth there; forwarding a
+ *   provider alongside it would arm two competing Authorization owners.
+ * - **Rejected** (throws) when the server carries a static `Authorization`
+ *   header AND a provider — the MCP SDK transport spreads static `requestInit`
+ *   headers OVER the provider token, so the static header would silently win and
+ *   strand the provider in a 401 loop. Failing loud at resolve time beats a
+ *   silent auth failure at runtime.
+ *
+ * Returns a fresh, reference-only map (the same provider instances, never mutated).
+ */
+export function normalizeMcpAuthProviders(mcpServers, resolved) {
+    if (!resolved || !mcpServers)
+        return {};
+    const normalized = {};
+    for (const [name, provider] of Object.entries(resolved)) {
+        const server = mcpServers[name];
+        if (!server || server.type !== 'remote' || server.enabled === false)
+            continue;
+        if (isSalesforcePlatformMcpUrl(server.url))
+            continue;
+        if (server.headers && hasAuthorizationHeader(server.headers)) {
+            throw new AgentSDKError(`MCP server "${name}" has both a static Authorization header and an OAuth authProvider. ` +
+                `Remove the static Authorization header — the provider owns auth for this server.`, AgentSDKErrorType.INVALID_MCP_AUTH_CONFIG);
+        }
+        normalized[name] = provider;
+    }
+    return normalized;
+}
 //# sourceMappingURL=mcp-auth.js.map

package/dist/mcp-config.d.ts

@@ -35,12 +35,82 @@ export type MCPStdioServerConfig = {
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
 };
+/**
+ * Harness-neutral contract for an MCP OAuth client provider, letting an
+ * OAuth-protected remote MCP server recover the RFC 9728 `401` challenge its
+ * transport receives (the static {@link MCPRemoteServerConfig.headers} seam
+ * cannot — headers are snapshotted at publish time).
+ *
+ * This package is harness-runtime-free (a lint rule bans importing
+ * `@modelcontextprotocol/*`), so this structurally mirrors the *required* core
+ * of the MCP SDK's `OAuthClientProvider` — same pattern as {@link McpToolAnnotations}.
+ * It is bidirectionally compatible: a real provider assigns to this field, and
+ * this field assigns into the transport option with no cast. Optional upstream
+ * members are omitted (a real instance still carries them at runtime); the
+ * harness-side compile-time drift-guard pins the compatibility.
+ */
+export interface McpOAuthClientProvider {
+    /** URL the user agent is redirected to after authorization (or `undefined` for non-interactive flows). */
+    readonly redirectUrl: string | URL | undefined;
+    /** Metadata about this OAuth client. */
+    readonly clientMetadata: {
+        redirect_uris: string[];
+    };
+    /** Loads this client's registration, or `undefined` if not yet registered. */
+    clientInformation(): {
+        client_id: string;
+    } | undefined | Promise<{
+        client_id: string;
+    } | undefined>;
+    /** Persists a dynamic client registration for later {@link clientInformation} reads. */
+    saveClientInformation?(clientInformation: {
+        client_id: string;
+    }): void | Promise<void>;
+    /** Loads any existing OAuth tokens for the current session, or `undefined`. */
+    tokens(): {
+        access_token: string;
+        token_type: string;
+    } | undefined | Promise<{
+        access_token: string;
+        token_type: string;
+    } | undefined>;
+    /** Stores new OAuth tokens after a successful authorization. */
+    saveTokens(tokens: {
+        access_token: string;
+        token_type: string;
+    }): void | Promise<void>;
+    /** Redirects the user agent to the given URL to begin the authorization flow. */
+    redirectToAuthorization(authorizationUrl: URL): void | Promise<void>;
+    /** Saves a PKCE code verifier before redirecting to the authorization flow. */
+    saveCodeVerifier(codeVerifier: string): void | Promise<void>;
+    /** Loads the PKCE code verifier needed to validate the authorization result. */
+    codeVerifier(): string | Promise<string>;
+}
+/**
+ * A per-agent map of remote MCP server name → its OAuth {@link McpOAuthClientProvider}.
+ *
+ * Providers are behavioral, credential-bearing runtime objects, so they are
+ * NOT part of the persisted {@link MCPConfiguration}. They are supplied at
+ * runtime through the manager's `mcpAuthProviderResolver` and threaded to the
+ * harness via the `createAgent` / `updateAgent` options bag — never serialized
+ * to disk. A harness cycles a server when its provider reference changes.
+ */
+export type McpAuthProviders = Readonly<Record<string, McpOAuthClientProvider>>;
 /** MCP server accessible over HTTP/SSE at a remote URL. */
 export type MCPRemoteServerConfig = {
     type: 'remote';
     /** URL of the remote MCP server endpoint. */
     url: string | URL;
-    /** HTTP headers sent with requests to the server. */
+    /**
+     * HTTP headers sent with requests to the server.
+     *
+     * When an OAuth `authProvider` is supplied for this server (via the
+     * manager's `mcpAuthProviderResolver`), this must NOT carry an
+     * `Authorization` header — the MCP SDK transport spreads static
+     * `requestInit` headers OVER the provider token, so a static
+     * `Authorization` would silently win and strand the provider. The SDK
+     * rejects that combination at resolve time (see `normalizeMcpAuthProviders`).
+     */
     headers?: Record<string, string>;
     /** Whether this server is enabled. Defaults to `true`. */
     enabled?: boolean;
@@ -187,6 +257,8 @@ export type McpToolInfo = {
 export type McpServerErrorCategory = 
 /** 3s default or configured timeout exceeded. */
 'connect-timeout'
+/** OAuth needs user interaction; the host must authorize before reconnecting. */
+ | 'oauth-required'
 /** Unauthorized — JWT missing/expired. */
  | 'http-401'
 /** Forbidden — JWT valid but the principal lacks permission. */
@@ -230,7 +302,7 @@ export type McpServerErrorDetail = {
     code?: number;
     /**
      * Whether the failure is transient (worth a retry via
-     * `Agent.reconnectMcpServer` / `Agent.refreshMcpAuth`) vs fatal (consumer
+     * `Agent.reconnectMcpServer`) vs fatal (consumer
      * must fix config). Harness implementations populate this with their best
      * heuristic; consumers may override per-category.
      */
@@ -259,6 +331,12 @@ export type McpServerErrorDetail = {
  *   strings round-trip; `headers` (key-order-insensitive); `timeout`,
  *   `reconnectionOptions` (field-wise).
  *
+ * This predicate compares only the serializable {@link MCPServerConfig}. A
+ * server's OAuth `authProvider` is NOT part of the config (it is a runtime
+ * binding supplied per-agent via `mcpAuthProviderResolver`); a harness cycles
+ * a server when this predicate fails OR its applied provider reference
+ * changed. See each harness's `updateAgent` diff.
+ *
  * Two configs that pass this predicate but produce different runtime tools
  * (e.g. an upstream stdio server whose binary was overwritten on disk) are
  * NOT detected here — the predicate compares declared config, not runtime