@salesforce/sfdx-agent-sdk 0.15.0 → 0.17.0

package/dist/mcp-config.js

@@ -17,4 +17,102 @@ export var McpServerStatus;
      */
     McpServerStatus["Reconnecting"] = "reconnecting";
 })(McpServerStatus || (McpServerStatus = {}));
+/**
+ * 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 function mcpServerConfigEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.type !== b.type)
+        return false;
+    if ((a.enabled ?? true) !== (b.enabled ?? true))
+        return false;
+    if (a.timeout !== b.timeout)
+        return false;
+    if (a.type === 'stdio' && b.type === 'stdio') {
+        if (a.command !== b.command)
+            return false;
+        if (!arraysEqual(a.args, b.args))
+            return false;
+        if (!recordsEqual(a.env, b.env))
+            return false;
+        return true;
+    }
+    if (a.type === 'remote' && b.type === 'remote') {
+        if (String(a.url) !== String(b.url))
+            return false;
+        if (!recordsEqual(a.headers, b.headers))
+            return false;
+        if (!reconnectionOptionsEqual(a.reconnectionOptions, b.reconnectionOptions))
+            return false;
+        return true;
+    }
+    return false;
+}
+function arraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return (a?.length ?? 0) === (b?.length ?? 0);
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function recordsEqual(a, b) {
+    if (a === b)
+        return true;
+    const aKeys = a ? Object.keys(a) : [];
+    const bKeys = b ? Object.keys(b) : [];
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(b ?? {}, k))
+            return false;
+        if (a[k] !== b[k])
+            return false;
+    }
+    return true;
+}
+function reconnectionOptionsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return !a && !b;
+    return (a.maxRetries === b.maxRetries &&
+        a.initialReconnectionDelay === b.initialReconnectionDelay &&
+        a.maxReconnectionDelay === b.maxReconnectionDelay &&
+        a.reconnectionDelayGrowFactor === b.reconnectionDelayGrowFactor);
+}
 //# sourceMappingURL=mcp-config.js.map

package/dist/types/redaction.d.ts

@@ -0,0 +1,171 @@
+import type { AgentConfig } from '../harness/harness-config.js';
+/**
+ * Sync-or-async callback the harness invokes for every tool result before it
+ * enters the model's context. The redactor inspects the upstream output and
+ * either replaces it (returning `{ output }`) or passes it through unchanged
+ * (returning `undefined`).
+ *
+ * Wired per-agent via {@link HooksForAgent} on `createAgentManager`; the SDK
+ * surfaces it inside the harness through {@link AgentHooks.onToolResult} on
+ * `AgentHarness.createAgent`'s `options.hooks` bag. A single registration
+ * covers built-in tools (`Bash`, `Read`, `Edit`, …), MCP tools, and
+ * consumer-executed tools declared via {@link AgentConfig.tools}.
+ *
+ * ### Why this lives in the harness layer
+ *
+ * Once a tool result reaches the SDK boundary the model has already seen it —
+ * any value can then be echoed in the reply, routed into a later tool call
+ * (`Bash` arg, file write), or sent to provider logs. Redaction has to fire
+ * INSIDE the engine, before the result is folded into the model's next
+ * request. The SDK exposes a harness-agnostic shape; each harness wires its
+ * native seam (Claude Agent SDK `PostToolUse` hook,
+ * Mastra `processInputStep`).
+ *
+ * ### Audit / preserving the original
+ *
+ * The redactor sees the unmodified `output` at the call site. Consumers that
+ * need an audit trail of the original value MUST log it themselves before
+ * returning the redaction. The SDK does not put the original on its telemetry
+ * bus or persist it anywhere — that would defeat the point.
+ *
+ * ### Throw policy is the consumer's
+ *
+ * The SDK does not own fail-closed semantics. If the redactor throws, the
+ * harness re-throws on its native error path: Claude routes through the
+ * Claude Agent SDK's `PostToolUse` hook-error path (which synthesizes a
+ * `tool_result(is_error=true)`); Mastra propagates from `processInputStep`
+ * and surfaces as an `error` ChatEvent on the consumer's eventStream.
+ * Consumers requiring a richer fail-closed substitute wrap their redactor's
+ * body in `try`/`catch` themselves — see the SDK README's
+ * "Tool-Result Redaction" section for the recommended boilerplate.
+ *
+ * ### Tool-shape constraints
+ *
+ * The harness does NOT validate that the replacement `output` has the same
+ * shape as the original — the redactor knows what tool it is redacting and
+ * is responsible for honoring that tool's expected return shape. Notable
+ * cases:
+ *
+ * - **Claude built-in `Bash`** — the replacement MUST keep the
+ *   `{ stdout, stderr, interrupted }` shape. A bare-string return is rejected
+ *   by the Claude Agent SDK and the original leaks.
+ * - **MCP tools** — the replacement MUST be a valid MCP `CallToolResult`
+ *   shape (`{ content: [...], isError? }`).
+ * - **Consumer-executed tools** — replacement passes through unchanged to
+ *   `submitToolResult`, so any shape the consumer accepts is fine.
+ *
+ * ### Performance
+ *
+ * Both harnesses skip their per-result hook entirely when
+ * `hooks.onToolResult` is undefined, so the no-op overhead is exactly zero.
+ * When set, both engines await the redactor (sync redactors collapse to a
+ * microtask).
+ *
+ * @example
+ * ```ts
+ * const redactor: ToolResultRedactor = ({ toolName, output, isError }) => {
+ *     // Caller-side audit (consumer's responsibility — SDK does not log originals).
+ *     auditLog.write({ toolName, originalLength: JSON.stringify(output).length });
+ *
+ *     // Bash needs its native shape preserved.
+ *     if (toolName === 'Bash') {
+ *         const bash = output as { stdout: string; stderr: string; interrupted: boolean };
+ *         return { output: { ...bash, stdout: scrub(bash.stdout), stderr: scrub(bash.stderr) } };
+ *     }
+ *
+ *     // Other tools: walk the structured output and scrub field-by-field.
+ *     return { output: scrubDeep(output) };
+ * };
+ *
+ * const manager = await createAgentManager(storage, factory, {
+ *     hooksForAgent: () => ({ onToolResult: redactor }),
+ * });
+ * ```
+ */
+export type ToolResultRedactor = (input: ToolResultRedactionInput) => ToolResultRedactionResult | Promise<ToolResultRedactionResult>;
+/**
+ * Inputs the harness hands the {@link ToolResultRedactor} for each tool
+ * result. Carries enough identity for the redactor to decide what (if
+ * anything) to redact and to attribute audit log entries.
+ */
+export type ToolResultRedactionInput = {
+    /** Agent that produced the tool result. */
+    agentId: string;
+    /** Conversation thread the result belongs to. */
+    threadId: string;
+    /** Stable id linking this result to the originating `tool-call` event. */
+    toolCallId: string;
+    /** Tool name the model invoked. Built-in / consumer / namespaced MCP form depends on the harness. */
+    toolName: string;
+    /**
+     * Originating MCP server when the tool came from an MCP catalog.
+     * `undefined` for built-ins, consumer-executed tools, and Mastra workspace
+     * tools. Mirrors the enrichment on {@link ToolResultEvent.serverName}.
+     */
+    serverName?: string;
+    /**
+     * Raw upstream output, exactly as the engine received it. The redactor
+     * MUST treat this as input only — mutating it is undefined behavior.
+     */
+    output: unknown;
+    /** `true` when the tool execution failed (engine flagged the result as an error). */
+    isError: boolean;
+};
+/**
+ * Return value from a {@link ToolResultRedactor} invocation.
+ *
+ * - `{ output }` — replace the original with this value.
+ * - `undefined` — pass the original through unchanged.
+ *
+ * The function signature already permits "no return" (an arrow body that
+ * doesn't `return` resolves to `undefined`), so a separate `void` variant
+ * isn't needed in the value-type union.
+ *
+ * The replacement shape MUST match what the originating tool produces. See
+ * the tool-shape notes on {@link ToolResultRedactor} for the harness-specific
+ * constraints (notably the Claude `Bash` `{ stdout, stderr, interrupted }`
+ * requirement).
+ */
+export type ToolResultRedactionResult = {
+    output: unknown;
+} | undefined;
+/**
+ * Per-agent hook bag the SDK resolves once per agent install / update via
+ * {@link HooksForAgent} and threads through to the harness on
+ * `AgentHarness.createAgent`'s `options.hooks`. Today the bag carries one
+ * field; the shape is open so future hooks (e.g. `onToolCall`, `onStep`)
+ * can be added without churning `*HarnessFactoryConfig`s.
+ *
+ * Harnesses MUST treat this object as opaque: store it on per-agent state,
+ * route the hooks they recognize to their native seam, and IGNORE unknown
+ * fields (forward-compat). Harnesses MUST NOT swallow hook throws — an
+ * exception from a hook MUST propagate on the harness's native error path
+ * so the original value never leaks to the model.
+ *
+ * The SDK never reads, persists, or surfaces this bag on its telemetry bus.
+ */
+export type AgentHooks = {
+    /**
+     * Optional redactor invoked for every tool result before it enters the
+     * model's context. See {@link ToolResultRedactor}. Each harness routes
+     * this to its native seam (Claude `PostToolUse`, Mastra
+     * `processInputStep`); the SDK does not enforce fail-closed semantics.
+     */
+    onToolResult?: ToolResultRedactor;
+};
+/**
+ * Resolves a per-agent {@link AgentHooks} bag from the agent's id and the
+ * config the SDK currently has on file for that agent. Invoked by
+ * `AgentManager` once per agent install (`createAgent`, boot-time restore,
+ * `Agent.updateAgentConfig`); the resolved bag is handed to
+ * `AgentHarness.createAgent`'s `options.hooks`.
+ *
+ * The callback is sync — the SDK does not await. Consumers needing async
+ * setup (e.g. remote feature flags) pre-resolve before constructing the
+ * manager.
+ *
+ * Consumers with one global policy ignore both arguments and return the
+ * same bag every time; consumers wanting per-agent variation branch on
+ * `agentId` or fields of `config`.
+ */
+export type HooksForAgent = (agentId: string, config: AgentConfig) => AgentHooks;

package/dist/types/redaction.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=redaction.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./harness": {
+      "types": "./dist/harness/public.d.ts",
+      "default": "./dist/harness/public.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -32,31 +36,32 @@
     "dist",
     "!dist/**/*.map",
     "!dist/test",
+    "CHANGELOG.md",
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.7.0",
-    "@salesforce/llm-gateway-sdk": "0.11.0"
+    "@salesforce/agentic-common": "0.9.0",
+    "@salesforce/llm-gateway-sdk": "0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.11.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.14.0",
-    "@types/node": "^22.19.17",
-    "@vitest/coverage-istanbul": "^4.1.7",
-    "@vitest/eslint-plugin": "^1.6.17",
-    "eslint": "^10.4.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.13.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.16.0",
+    "@types/node": "^22.19.19",
+    "@vitest/coverage-istanbul": "^4.1.8",
+    "@vitest/eslint-plugin": "^1.6.19",
+    "eslint": "^10.4.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.0.1",
     "globals": "^17.6.0",
-    "lint-staged": "^17.0.5",
+    "lint-staged": "^17.0.7",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4",
+    "typescript-eslint": "^8.60.1",
     "vitest": "^4.1.7"
   },
   "engines": {