@salesforce/sfdx-agent-sdk 0.15.0 → 0.17.0

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

@@ -4,6 +4,7 @@ import type { ChatStreamResult } from '../types/events.js';
 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 { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
@@ -105,10 +106,24 @@ export interface AgentHarness {
      * @param projectRoot - Project folder the agent is allowed to manipulate files from.
      * @param llmGatewayClient - Pre-configured LLM gateway client for this agent.
      * @param config - Engine-facing agent configuration (org resolution omitted).
-     * @param options - Optional execution options, including abort signals.
+     * @param options - Optional execution options.
+     *   - `abortSignal` — caller-side cancellation; harnesses thread it
+     *     through long-running install work (rules load, MCP discovery, …).
+     *   - `hooks` — per-agent {@link AgentHooks} bag, resolved by the SDK
+     *     from `createAgentManager`'s `hooksForAgent` callback. The bag is
+     *     opaque to the SDK; harnesses MUST store it on per-agent state and
+     *     route each recognized hook to their native seam (Claude
+     *     `PostToolUse`, Mastra `processInputStep`). Harnesses MUST IGNORE
+     *     hook fields they do not recognize (forward-compat). Harnesses
+     *     MUST NOT swallow hook throws — exceptions MUST propagate on the
+     *     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.
      */
     createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
     }): Promise<void>;
     /**
      * Destroy an agent and release its resources (MCP connections, workspace, memory).
@@ -122,6 +137,81 @@ export interface AgentHarness {
      * @returns `true` after a real removal.
      */
     destroyAgent(agentId: string): Promise<boolean>;
+    /**
+     * Apply a new configuration to a registered agent without recycling MCP
+     * clients whose `MCPServerConfig` is structurally equal to the
+     * currently-applied one.
+     *
+     * This is the load-bearing primitive behind `Agent.updateAgentConfig`'s
+     * "don't blow up live MCP clients on a model-only / instructions-only /
+     * org-connect change" contract. Pre-#541 the SDK called
+     * `destroyAgent` + `createAgent` here, which closed every MCP client and
+     * forced the model to wait through the discovery wave again. With
+     * `updateAgent` the SDK calls one method and the harness preserves
+     * unchanged servers in place.
+     *
+     * Implementors MUST:
+     *
+     * - throw `AgentSDKError(AGENT_NOT_FOUND)` on unknown `agentId`,
+     *   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.
+     * - disconnect any server present in the currently-applied config but
+     *   absent from the next config, removing it from
+     *   `getMcpServerInfo()`'s output.
+     * - connect any server present in the next config but absent from the
+     *   currently-applied one, running discovery the same way `createAgent`
+     *   would (background, non-blocking; failures land on
+     *   `McpServerState.error`, not as a thrown rejection).
+     * - apply non-MCP changes — `instructions`, `model`, `tools`, `skills`,
+     *   `rules`, harness-specific extra-config fields surviving via
+     *   `toHarnessConfig`'s spread — atomically with the MCP diff. After
+     *   this resolves, the agent's effective config is the one passed in.
+     * - be idempotent on a no-op call at the MCP layer: when the next
+     *   config's `mcpServers` is deep-equal (per `mcpServerConfigEqual`) to
+     *   the currently-applied one, no server is cycled, no `tools/list` is
+     *   re-run, and no per-server discovery telemetry fires. Implementors
+     *   MAY rebuild non-MCP state (e.g. Mastra reconstructs its `Agent`
+     *   unconditionally) — that work is local and cheap; correct no-op
+     *   detection across `orgJwt` rotation, hook-bag closures, and
+     *   harness-specific extra-config fields is not.
+     * - write per-server state incrementally so a subsequent `updateAgent`
+     *   call (e.g. SDK rollback against `previousConfig`) sees the harness's
+     *   current truth, not a snapshot from the start of the failed update.
+     *
+     * Implementors MUST NOT:
+     *
+     * - touch persisted thread / session state. Sessions are config-
+     *   independent — `Agent.updateAgentConfig` does not invalidate them.
+     * - dispose in-flight stream coordinators. In-flight turns continue
+     *   executing against the agent state captured at stream-start; the
+     *   next `stream()` after this resolves uses the new state.
+     * - mutate `AgentConfig` or persist anything to disk. Persistence is
+     *   the SDK's responsibility (`AgentIdentityStore.write` is gated by
+     *   `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 config - Engine-facing agent configuration to apply.
+     * @param options - Optional execution options.
+     *   - `abortSignal` — caller-side cancellation; harnesses thread it
+     *     through long-running update work (rules load, MCP discovery, …).
+     *   - `hooks` — per-agent {@link AgentHooks} bag, resolved by the SDK
+     *     from `createAgentManager`'s `hooksForAgent` callback against the
+     *     incoming `nextConfig`. Same semantics as `createAgent.options.hooks`:
+     *     opaque to the SDK; harnesses store it on per-agent state and
+     *     re-route each recognized hook to its native seam. The bag is
+     *     re-resolved on every `updateAgent` so consumers can vary hooks by
+     *     config (and so a rollback `updateAgent(previousConfig)` restores
+     *     the prior hook bag too).
+     */
+    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
+    }): Promise<void>;
     /**
      * List the IDs of all currently registered agents.
      */
@@ -238,49 +328,56 @@ export interface AgentHarness {
     stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
     /**
      * Feed the result of a **consumer-executed (client-side) tool** back into the
-     * conversation and resume stream generation. Implements the consumer-facing
+     * conversation. Implements the consumer-facing
      * {@link ChatSession.submitToolResult} contract: see that JSDoc for the
      * full consumer-level semantics.
      *
      * Called only for tools declared in {@link HarnessAgentConfig.tools} (no
      * `execute` function). Tools provided via `mcpServers` are executed by the
-     * harness directly and never reach this method. The harness resumes the
-     * suspended agentic loop from the most recent `stream()` call on the given
-     * thread, feeds `toolResult` into the loop, and returns a continuation
-     * stream the consumer iterates for the model's next turn.
+     * harness directly and never reach this method.
+     *
+     * Returns `Promise<void>` once the harness has accepted the tool result
+     * (the parked bridge handler resolved). Post-resume events
+     * (`tool-result`, model follow-up text, terminal `finish`) flow through
+     * the SAME `ChatStreamResult.eventStream` returned by the most recent
+     * {@link stream} call on the thread — the consumer is still iterating
+     * that stream and sees the events arrive.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolResult - The completed tool execution result; `toolCallId`
      *   matches the id from the originating `tool-call` event.
      */
-    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<void>;
     /**
      * Approve a pending tool call, allowing the harness to execute it.
      * Called after receiving a `tool-approval-request` event.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * executes the approved tool, generates the model's follow-up response, and
-     * streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the approval
+     * (the parked PreToolUse hook resolved on Claude; the resume call was
+     * dispatched on Mastra). Post-resume events flow through the SAME
+     * `ChatStreamResult.eventStream` returned by the most recent
+     * {@link stream} call on the thread.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread (needed for harness-internal state lookup).
      * @param toolCallId - ID of the tool call to approve.
      */
-    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
     /**
-     * Decline a pending tool call. The harness resumes the stream with the
-     * model acknowledging the decline and potentially suggesting alternatives.
+     * Decline a pending tool call. The harness resumes the agentic loop with
+     * the model acknowledging the decline and potentially suggesting
+     * alternatives.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * cancels the pending tool call, generates the model's acknowledgement response,
-     * and streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the decline.
+     * Post-resume events flow through the SAME `ChatStreamResult.eventStream`
+     * returned by the most recent {@link stream} call on the thread.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolCallId - ID of the tool call to decline.
      */
-    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
     /**
      * Retrieve message history for a thread.
      *

package/dist/harness/always-active.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tool-exposure policy entry shape consumed by both
+ * {@link MastraAgentConfig.toolSearch.alwaysActive} and
+ * {@link ClaudeAgentConfig.toolSearch.alwaysActive}.
+ *
+ * One entry covers three matching patterns:
+ *
+ * | Entry shape | Matches |
+ * | --- | --- |
+ * | `{ serverName: 'X' }` | every tool advertised by server `X` (post-discovery expansion) |
+ * | `{ serverName: 'X', toolName: 'Y' }` | exactly tool `Y` on server `X` |
+ * | `{ toolName: 'Y' }` | any tool named `Y`, **regardless of source** — built-ins, workspace tools, consumer-declared tools, AND any MCP server's tool surface |
+ *
+ * The `{ toolName }` pattern is intentionally broad — it's the consumer's
+ * escape hatch for "I want this tool always-active and I don't care where it
+ * comes from." The `{ serverName, toolName }` form is the precise version for
+ * when ambiguity matters.
+ *
+ * **Validation rule:** at least one of `serverName` or `toolName` must be
+ * present. An empty `{}` is rejected at config time via
+ * {@link validateAlwaysActiveEntry} — a typo should fail loud, not silently
+ * match nothing (and definitely not silently match everything).
+ *
+ * Lives on the harness public surface (`@salesforce/sfdx-agent-sdk/harness`)
+ * because it's harness-implementation shape that both production harnesses
+ * share. Ready to graduate to `AgentConfig.toolSearch` on the SDK contract
+ * surface once a third harness exercises it — same graduation pattern PR
+ * #563 established for `skillSearch`.
+ */
+export type AlwaysActiveEntry = {
+    serverName: string;
+    toolName?: string;
+} | {
+    serverName?: undefined;
+    toolName: string;
+};
+/**
+ * Throws on an entry whose `serverName` AND `toolName` are both absent. Both
+ * harness boundaries call this on every entry before reading it so a typo
+ * (`{}` / `{ severName: 'X' }` with a misspelled key) fails loud at config
+ * time rather than silently dropping the entry — or worse, silently matching
+ * nothing while looking like it should match everything.
+ */
+export declare function validateAlwaysActiveEntry(entry: AlwaysActiveEntry): void;
+/**
+ * Returns `true` when `(serverName, toolName)` matches at least one entry in
+ * `entries`. Pure / deterministic; harnesses call it per-tool when building
+ * their tool catalogs.
+ *
+ * - `{ serverName: 'X' }` matches every tool from server X.
+ * - `{ serverName: 'X', toolName: 'Y' }` matches only `Y` on `X`.
+ * - `{ toolName: 'Y' }` matches `Y` from any source (built-ins, workspace,
+ *   consumer-declared tools, every connected MCP server).
+ *
+ * For tools without a server (built-ins, in-process workspace), pass
+ * `serverName: undefined`. The `{ toolName }`-only entries match those;
+ * `{ serverName: 'X' }` and `{ serverName: 'X', toolName: ... }` entries do
+ * not.
+ */
+export declare function matchesAlwaysActive(entries: readonly AlwaysActiveEntry[] | undefined, serverName: string | undefined, toolName: string): boolean;

package/dist/harness/always-active.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Throws on an entry whose `serverName` AND `toolName` are both absent. Both
+ * harness boundaries call this on every entry before reading it so a typo
+ * (`{}` / `{ severName: 'X' }` with a misspelled key) fails loud at config
+ * time rather than silently dropping the entry — or worse, silently matching
+ * nothing while looking like it should match everything.
+ */
+export function validateAlwaysActiveEntry(entry) {
+    const serverName = entry.serverName;
+    const toolName = entry.toolName;
+    if ((typeof serverName !== 'string' || serverName.length === 0) &&
+        (typeof toolName !== 'string' || toolName.length === 0)) {
+        throw new Error('AlwaysActiveEntry must declare at least one of `serverName` or `toolName` (received: ' +
+            JSON.stringify(entry) +
+            ')');
+    }
+}
+/**
+ * Returns `true` when `(serverName, toolName)` matches at least one entry in
+ * `entries`. Pure / deterministic; harnesses call it per-tool when building
+ * their tool catalogs.
+ *
+ * - `{ serverName: 'X' }` matches every tool from server X.
+ * - `{ serverName: 'X', toolName: 'Y' }` matches only `Y` on `X`.
+ * - `{ toolName: 'Y' }` matches `Y` from any source (built-ins, workspace,
+ *   consumer-declared tools, every connected MCP server).
+ *
+ * For tools without a server (built-ins, in-process workspace), pass
+ * `serverName: undefined`. The `{ toolName }`-only entries match those;
+ * `{ serverName: 'X' }` and `{ serverName: 'X', toolName: ... }` entries do
+ * not.
+ */
+export function matchesAlwaysActive(entries, serverName, toolName) {
+    if (!entries || entries.length === 0)
+        return false;
+    for (const entry of entries) {
+        const entryServer = entry.serverName;
+        const entryTool = entry.toolName;
+        if (entryServer !== undefined) {
+            if (entryServer !== serverName)
+                continue;
+            if (entryTool === undefined)
+                return true; // server-wide
+            if (entryTool === toolName)
+                return true; // exact server+tool
+            continue;
+        }
+        // entryServer === undefined ⇒ entryTool MUST be defined (validated upstream)
+        if (entryTool === toolName)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=always-active.js.map

package/dist/harness/gen-sink.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Buffered async-generator wrapper used by `AgentHarness` implementations to
+ * deliver `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
+ *
+ * The buffer holds events pushed before the consumer starts iterating, so the
+ * harness can begin populating the sink eagerly without coordinating with the
+ * consumer's `for await` loop. Events pushed after iteration starts unblock
+ * the awaiting consumer via an internal Promise waiter.
+ *
+ * # Single-iteration invariant
+ *
+ * `generator()` may be called **at most once** per sink. Sinks are stateful
+ * (single waiter slot, single buffer); two iterators on the same sink race on
+ * both, so two iterators is always a bug. Calling `generator()` a second time
+ * throws — the alternative (silently allowing the second call to share the
+ * buffer / waiter with the first) produced the deadlock-class bug catalogued
+ * in [issue #529](https://github.com/forcedotcom/agentic-dx/issues/529)
+ * Finding 4. Surface failures at construction-time, not at deadlock-time.
+ *
+ * # `isEnded()`
+ *
+ * Exposes the closed state for routing logic that needs to skip pushes onto
+ * a sink that's already been retired. Routing for a closed sink should
+ * silently no-op with a debug log rather than throw — the late event is
+ * upstream noise, not a programmer error.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness`
+ * implementations in sibling packages can reuse it.
+ */
+export declare class GenSink<T> {
+    private readonly buffered;
+    private ended;
+    private waiter;
+    private generated;
+    push(event: T): void;
+    end(): void;
+    isEnded(): boolean;
+    generator(): AsyncGenerator<T, void>;
+    private iterate;
+    private wake;
+}

package/dist/harness/gen-sink.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Buffered async-generator wrapper used by `AgentHarness` implementations to
+ * deliver `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
+ *
+ * The buffer holds events pushed before the consumer starts iterating, so the
+ * harness can begin populating the sink eagerly without coordinating with the
+ * consumer's `for await` loop. Events pushed after iteration starts unblock
+ * the awaiting consumer via an internal Promise waiter.
+ *
+ * # Single-iteration invariant
+ *
+ * `generator()` may be called **at most once** per sink. Sinks are stateful
+ * (single waiter slot, single buffer); two iterators on the same sink race on
+ * both, so two iterators is always a bug. Calling `generator()` a second time
+ * throws — the alternative (silently allowing the second call to share the
+ * buffer / waiter with the first) produced the deadlock-class bug catalogued
+ * in [issue #529](https://github.com/forcedotcom/agentic-dx/issues/529)
+ * Finding 4. Surface failures at construction-time, not at deadlock-time.
+ *
+ * # `isEnded()`
+ *
+ * Exposes the closed state for routing logic that needs to skip pushes onto
+ * a sink that's already been retired. Routing for a closed sink should
+ * silently no-op with a debug log rather than throw — the late event is
+ * upstream noise, not a programmer error.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness`
+ * implementations in sibling packages can reuse it.
+ */
+export class GenSink {
+    buffered = [];
+    ended = false;
+    waiter = null;
+    generated = false;
+    push(event) {
+        if (this.ended)
+            return;
+        this.buffered.push(event);
+        this.wake();
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.wake();
+    }
+    isEnded() {
+        return this.ended;
+    }
+    generator() {
+        // Synchronous guard. Must live outside the async generator body —
+        // async generators are lazy (the body does not execute until the
+        // first `next()`), so a `throw` inside the body would not surface
+        // at the second `generator()` call site as expected.
+        if (this.generated) {
+            throw new Error('GenSink.generator(): sinks are single-iteration. ' +
+                'Two iterators on one sink race on the buffer and waiter slot. ' +
+                'See https://github.com/forcedotcom/agentic-dx/issues/529 (Finding 4).');
+        }
+        this.generated = true;
+        return this.iterate();
+    }
+    async *iterate() {
+        while (true) {
+            if (this.buffered.length > 0) {
+                yield this.buffered.shift();
+                continue;
+            }
+            if (this.ended)
+                return;
+            await new Promise((resolve) => {
+                this.waiter = { resolve };
+            });
+        }
+    }
+    wake() {
+        const w = this.waiter;
+        if (w) {
+            this.waiter = null;
+            w.resolve();
+        }
+    }
+}
+//# sourceMappingURL=gen-sink.js.map

package/dist/harness/index.d.ts

@@ -2,3 +2,4 @@ export type { AgentHarness, WithAgentConfig, ConfigOf } from './agent-harness.js
 export type { HarnessFactory } from './harness-factory.js';
 export type { AgentConfig, StreamOptions } from './harness-config.js';
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+export { GenSink } from './gen-sink.js';

package/dist/harness/index.js

@@ -3,4 +3,5 @@
  * See LICENSE.txt for license terms.
  */
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+export { GenSink } from './gen-sink.js';
 //# sourceMappingURL=index.js.map

package/dist/harness/public.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Harness-implementation public surface.
+ *
+ * This module is reachable as `@salesforce/sfdx-agent-sdk/harness` —
+ * **never** import directly from `dist/` or via deep relative paths.
+ *
+ * # When to import from here
+ *
+ * Use this surface when implementing an `AgentHarness` (e.g.
+ * `@salesforce/sfdx-agent-harness-claude`,
+ * `@salesforce/sfdx-agent-harness-mastra`). It re-exports both the
+ * harness contract types (`AgentHarness`, `HarnessFactory`) and the
+ * harness-implementation helpers consumer applications must not touch
+ * (`HarnessBusOwner`, `GenSink`, `lowerStreamInput`,
+ * `SUPPORTED_PROTOCOL_VERSIONS`).
+ *
+ * # Why this is a separate subpath
+ *
+ * Consumer applications (anything that calls `createAgentManager` and
+ * iterates `ChatStreamResult`) import from the bare specifier:
+ *
+ *     import { createAgentManager, Agent } from '@salesforce/sfdx-agent-sdk';
+ *
+ * Harness implementations import from the subpath:
+ *
+ *     import { HarnessBusOwner, GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+ *
+ * The split makes the boundary mechanical: a consumer who tries to import
+ * `HarnessBusOwner` from the bare specifier gets an immediate
+ * "not exported" error from the bundler / TS resolver, instead of
+ * accidentally reaching for a primitive they shouldn't be using.
+ *
+ * Type-only references to the contract interface (`AgentHarness`,
+ * `HarnessFactory`) ALSO appear on the bare specifier so consumer code
+ * that needs `AgentManager<H extends AgentHarness>` typing still works
+ * without a subpath import — but their runtime / constructible
+ * counterparts live only here.
+ *
+ * Symbols that consumers and harnesses both need (`AgentConfig`,
+ * `StreamOptions`, `DEFAULT_MAX_STEPS`, `resolveToolApprovalMode`,
+ * `ChatEvent` types, `Message` types, `MCPConfiguration`, etc.) stay on
+ * the bare specifier. The split is "harness-only" vs. "consumer-AND-harness",
+ * not "harness vs. consumer."
+ */
+export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './index.js';
+export type { AgentHooks } from '../types/redaction.js';
+export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+export { mcpServerConfigEqual } 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';
+export { matchesAlwaysActive, validateAlwaysActiveEntry, type AlwaysActiveEntry } from './always-active.js';

package/dist/harness/public.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+export { mcpServerConfigEqual } from '../mcp-config.js';
+// ── Harness-implementation helpers ──────────────────────────────────
+export { HarnessBusOwner } from './harness-bus-owner.js';
+export { lowerStreamInput } from './stream-input.js';
+export { GenSink } from './gen-sink.js';
+export { matchesAlwaysActive, validateAlwaysActiveEntry } from './always-active.js';
+//# sourceMappingURL=public.js.map

package/dist/index.d.ts

@@ -2,10 +2,11 @@ export type { Message, MessagePart, ImagePart, FilePart } from './types/messages
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
 export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools.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, ToolApprovalMode } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
-export { McpServerStatus } from './mcp-config.js';
+export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel } from '@salesforce/llm-gateway-sdk';
 export type { ClaudeModelOverrides } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
@@ -14,9 +15,6 @@ export { type Agent } from './agent.js';
 export { type ChatSession, type ChatOptions } from './chat-session.js';
 export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-connectivity-resolver.js';
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
-export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
-export { HarnessBusOwner } from './harness/harness-bus-owner.js';
-export { lowerStreamInput, type InputMessagePart } from './harness/stream-input.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';

package/dist/index.js

@@ -3,16 +3,13 @@
  * See LICENSE.txt for license terms.
  */
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
-export { McpServerStatus } from './mcp-config.js';
+export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 // ── Agent Layer ─────────────────────────────────────────────────────
 export { createAgentManager } from './agent-manager.js';
 export {} from './agent.js';
 export {} from './chat-session.js';
-export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
-export { HarnessBusOwner } from './harness/harness-bus-owner.js';
-export { lowerStreamInput } from './harness/stream-input.js';
 // ── Errors ───────────────────────────────────────────────────────────
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 // ── MCP Auth ────────────────────────────────────────────────────────

package/dist/mcp-config.d.ts

@@ -34,25 +34,6 @@ export type MCPStdioServerConfig = {
     enabled?: boolean;
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
-    /**
-     * Opt the server's tool surface out of the active runtime's tool-search
-     * deferral. When `true`, every tool advertised by this server is
-     * registered with the model up-front instead of sitting behind a
-     * search/load round-trip. Useful for small, discovery-critical surfaces
-     * (e.g. ≤ 10 tools the model needs to find without prompting). Default
-     * (`undefined` / `false`): tools may be deferred when the active runtime
-     * enables tool search.
-     *
-     * **Harness behavior:**
-     * - **Claude harness** — sets `_meta['anthropic/alwaysLoad'] = true` on
-     *   each tool the bridge forwards, equivalent to
-     *   `defer_loading: false` on the API. Skill-bridge and consumer-tool
-     *   tools are always-load regardless of this flag (see
-     *   `@salesforce/sfdx-agent-harness-claude` ARCHITECTURE.md).
-     * - **Mastra harness** — no-op; Mastra eager-loads MCP tools at every
-     *   turn already, so there's no deferral to opt out of.
-     */
-    alwaysLoad?: boolean;
 };
 /** MCP server accessible over HTTP/SSE at a remote URL. */
 export type MCPRemoteServerConfig = {
@@ -91,11 +72,6 @@ export type MCPRemoteServerConfig = {
         /** Factor by which the reconnection delay grows after each attempt. Default `1.5`. */
         reconnectionDelayGrowFactor?: number;
     };
-    /**
-     * Opt the server's tool surface out of the active runtime's tool-search
-     * deferral. See {@link MCPStdioServerConfig.alwaysLoad}.
-     */
-    alwaysLoad?: boolean;
 };
 /** Connection status of a single MCP server. */
 export declare enum McpServerStatus {
@@ -260,6 +236,36 @@ export type McpServerErrorDetail = {
      */
     retriable: boolean;
 };
+/**
+ * Structural deep-equality predicate over {@link MCPServerConfig}. Returns
+ * `true` when two configs would behave identically at the harness layer —
+ * meaning a harness handed `b` while currently bound to `a` MUST be free to
+ * preserve its existing transport, client instance, and discovered tool
+ * catalog without cycling.
+ *
+ * Used by harnesses inside `AgentHarness.updateAgent` to decide which MCP
+ * servers to preserve vs. cycle when an agent's config changes. Exported so
+ * both production harnesses use the same equality and a third harness can
+ * adopt it without duplicating the rules.
+ *
+ * **Equality rules:**
+ * - Both `undefined` ⇒ `true`. Exactly one `undefined` ⇒ `false`.
+ * - `type` mismatch ⇒ `false` (the discriminated union splits stdio vs remote).
+ * - `enabled: undefined` and `enabled: true` compare equal — both type docs
+ *   declare `true` as the default.
+ * - Stdio: structural compare on `command`, `args` (order-sensitive),
+ *   `env` (key-order-insensitive), `timeout`.
+ * - Remote: `url` is compared via `String(url)` so `URL` instances and
+ *   strings round-trip; `headers` (key-order-insensitive); `timeout`,
+ *   `reconnectionOptions` (field-wise).
+ *
+ * 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
+ * state. Use `Agent.reconnectMcpServer(name)` to force a per-server cycle in
+ * that case.
+ */
+export declare function mcpServerConfigEqual(a: MCPServerConfig | undefined, b: MCPServerConfig | undefined): boolean;
 /** Runtime status of a configured MCP server, including its discovered tools. */
 export type McpServerInfo = {
     name: string;