@salesforce/sfdx-agent-harness-mastra 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@salesforce/sfdx-agent-harness-mastra` are documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.16.0] - 2026-06-09
+
+### Features
+- **release**: auto-generate per-package CHANGELOG.md on publish ([#567](https://github.com/forcedotcom/agentic-dx/pull/567))
+- unify tool-exposure policy under toolSearch.alwaysActive ([#566](https://github.com/forcedotcom/agentic-dx/pull/566))
+- add ClaudeAgentConfig.skillSearch + decouple Mastra skillSearch from toolSearch ([#563](https://github.com/forcedotcom/agentic-dx/pull/563))
+- **agent-sdk**: preserve MCP clients across updateAgentConfig ([#560](https://github.com/forcedotcom/agentic-dx/pull/560))
+- **agent-sdk,harness-claude,harness-mastra**: first-class tool-result redaction ([#546](https://github.com/forcedotcom/agentic-dx/pull/546))
+
+### Fixes
+- **harness-claude,harness-mastra**: align event/log payload shapes ([#562](https://github.com/forcedotcom/agentic-dx/pull/562))
+- **harness-mastra**: honor MCPServerConfig.alwaysLoad when toolSearch is set ([#558](https://github.com/forcedotcom/agentic-dx/pull/558))
+
+### Chores
+- **harness-claude,harness-mastra**: re-enable monorepoLintPack at four offender sites ([#561](https://github.com/forcedotcom/agentic-dx/pull/561))
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#553](https://github.com/forcedotcom/agentic-dx/pull/553))
+- **deps**: bump the mastra group across 1 directory with 3 updates ([#539](https://github.com/forcedotcom/agentic-dx/pull/539))
+- **deps-dev**: bump the dev-dependencies group across 1 directory with 4 updates ([#536](https://github.com/forcedotcom/agentic-dx/pull/536))
+- **deps-dev**: bump the vitest group across 1 directory with 3 updates ([#552](https://github.com/forcedotcom/agentic-dx/pull/552))
+

package/README.md

@@ -62,13 +62,14 @@ These types let consumers reach Mastra-specific features through the SDK's typed
 `MastraAgentHarness` from `MastraHarnessFactory.create()`, so consumers usually don't reference these types explicitly —
 they show up via inference at the call site.
 
-| Export                   | Kind | Description                                                                                                                                          |
-| ------------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MastraAgentHarness`     | type | Branded `AgentHarness` subtype; carries the Mastra-specific `extensions` namespace and the inferred config type.                                     |
-| `MastraAgentConfig`      | type | `AgentConfig` extended with Mastra-only fields (currently `toolSearch`). Inferred at `manager.createAgent` automatically — annotation rarely needed. |
-| `MastraToolSearchConfig` | type | Shape of `MastraAgentConfig.toolSearch` (`pool`, `alwaysActive`, `topK`, `ttl`).                                                                     |
-| `ToolSearchHandle`       | type | Stable interface for the tool-search runtime: `id`, `getStateStats`, `clearState`, `clearAllState`, `cleanupNow`. Wraps Mastra's internal processor. |
-| `SkillSearchHandle`      | type | Stable interface for the skill-search runtime: `id` (Mastra's processor has no other public methods today; the harness owns lifecycle).              |
+| Export                    | Kind | Description                                                                                                                                               |
+| ------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MastraAgentHarness`      | type | Branded `AgentHarness` subtype; carries the Mastra-specific `extensions` namespace and the inferred config type.                                          |
+| `MastraAgentConfig`       | type | `AgentConfig` extended with Mastra-only fields (`toolSearch`, `skillSearch`). Inferred at `manager.createAgent` automatically — annotation rarely needed. |
+| `MastraToolSearchConfig`  | type | Shape of `MastraAgentConfig.toolSearch` (`pool`, `alwaysActive`, `topK`, `ttl`).                                                                          |
+| `MastraSkillSearchConfig` | type | Shape of `MastraAgentConfig.skillSearch` (`topK`). Opts into Mastra's `SkillSearchProcessor`.                                                             |
+| `ToolSearchHandle`        | type | Stable interface for the tool-search runtime: `id`, `getStateStats`, `clearState`, `clearAllState`, `cleanupNow`. Wraps Mastra's internal processor.      |
+| `SkillSearchHandle`       | type | Stable interface for the skill-search runtime: `id` (Mastra's processor has no other public methods today; the harness owns lifecycle).                   |
 
 The Mastra-specific accessors live on `manager.extensions.mastra` (`getToolSearchProcessor(agentId)`,
 `getSkillSearchProcessor(agentId)`, `formatMcpToolName(serverName, toolName)`) and require no separate import.
@@ -90,12 +91,13 @@ const agent = await manager.createAgent(projectRoot, {
   toolSearch: {
     pool: '*', // or an explicit name list
     alwaysActive: [
-      'lookup_account',
-      // Build the Mastra-specific namespaced name for an MCP tool that hasn't
-      // been discovered yet. The output format is harness-specific
-      // (Mastra: `${server}_${tool}`); for cross-harness tool identification
-      // anywhere else, prefer the `(serverName, toolName)` pair on `McpToolInfo`.
-      manager.extensions.mastra.formatMcpToolName('sfdx', 'deploy_metadata'),
+      // Every tool from a server (post-discovery expansion).
+      { serverName: 'sfdx' },
+      // Exactly one tool on a specific server.
+      { serverName: 'other', toolName: 'lookup_account' },
+      // Any tool by this name, regardless of source — built-ins, workspace
+      // tools, consumer-declared tools, AND any MCP server's tool surface.
+      { toolName: 'resume_tool_operation' },
     ],
     topK: 5, // advisory; defaults to Mastra's 5
     ttl: 3_600_000, // ms; advisory; defaults to Mastra's 1h
@@ -105,16 +107,35 @@ const agent = await manager.createAgent(projectRoot, {
 
 When `toolSearch` is set, `createAgent` blocks on MCP discovery so MCP tools enter the searchable pool. Without
 `toolSearch`, MCP discovery stays non-blocking (existing behavior). `alwaysActive` tools are visible directly to the
-model; everything else lives in the searchable pool. Unknown `alwaysActive` names are kept (for late MCP discovery);
-unknown `pool` names are dropped.
+model; everything else lives in the searchable pool.
+
+Each `alwaysActive` entry is an `AlwaysActiveEntry` (re-exported from `@salesforce/sfdx-agent-sdk/harness` and shared
+with `ClaudeAgentConfig.toolSearch.alwaysActive`). At least one of `serverName` or `toolName` must be present — `{}`
+rejects at config time. Unknown `pool` names are dropped; unmatched `{ toolName }`-only entries are kept for late MCP
+discovery.
 
 `MastraToolSearchConfig.topK` and `ttl` are advisory — Mastra applies its own defaults if omitted.
 
 #### Skill search
 
-Skills (`AgentConfig.skills`) load eagerly by default. When `toolSearch` is also set, skills load on demand via
-harness-injected `search_skills` / `load_skill` meta-tools (Mastra's `SkillSearchProcessor`). The gating is deliberate —
-consumers who opt into `toolSearch` get the same on-demand pattern across tools and skills.
+Skills (`AgentConfig.skills`) load eagerly by default. Set `MastraAgentConfig.skillSearch` to switch to on-demand
+loading via harness-injected `search_skills` / `load_skill` meta-tools (Mastra's `SkillSearchProcessor`):
+
+```ts
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  skills: ['/path/to/skills'],
+  skillSearch: { topK: 5 }, // ranked, on-demand discovery; eager catalog stays out of the prompt
+});
+```
+
+`skillSearch.topK` is advisory; Mastra defaults to 5 if omitted. The same `skillSearch` field exists on
+`ClaudeAgentConfig`, so cross-harness consumers can opt into on-demand skill discovery on either harness with the same
+shape.
+
+> **Breaking change (#468).** Pre-#468, on-demand skill search was implicitly gated on `skills && toolSearch`. That
+> coupling has been removed: `skillSearch` is now the explicit opt-in, independent of `toolSearch`. Consumers who relied
+> on the coupling must add `skillSearch: {}` to their config to keep the previous behavior.
 
 #### Operational handles
 
@@ -198,6 +219,20 @@ for await (const event of result.eventStream) {
 }
 ```
 
+### Tool-result redaction
+
+Tool-result redaction is configured at the manager layer, not the factory. Pass a `hooksForAgent` callback to
+`createAgentManager`; the SDK threads the resolved `AgentHooks` bag through `createAgent`'s `options.hooks`, and the
+Mastra harness registers a `ToolResultRedactionProcessor` on the agent's `inputProcessors` chain whose
+`processInputStep` walks new tool-result rows on the MessageList and replaces their content in place. The same
+`ToolResultRedactor` works on the Claude harness. See the SDK README → "Tool-Result Redaction" for the full pattern
+(including a `failClosed(...)` wrapper consumers can use to substitute a safe stub on throw).
+
+The processor composes with existing harness-internal processors (`ToolSearchProcessor`, `SkillSearchProcessor`); no
+consumer-supplied processor passthrough is needed. Throws propagate from `processInputStep` and the harness's approval
+coordinator surfaces them as an `error` ChatEvent on the consumer's eventStream — see ARCHITECTURE.md for the full
+contract.
+
 ### Using LLM Gateway Express
 
 ```ts

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
-export { type MastraAgentConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
+export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
 export type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
 export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
 export { LLMGExpressMastraModelConfigFactory, type LLMGExpressConfig } from './llmg-express-model-config-factory.js';

package/dist/mastra-harness.d.ts

@@ -2,6 +2,7 @@ import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import { MCPClient } from '@mastra/mcp';
 import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import type { MastraModelConfigFactory } from './model-config-factory.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
@@ -44,6 +45,12 @@ interface McpServerState {
     errorDetail?: McpServerErrorDetail;
     ready: Promise<void>;
     settled: boolean;
+    /**
+     * Discovered tools for this server, keyed by the harness's namespaced form
+     * `${serverName}_${toolName}`. The namespacing is applied at discovery time
+     * by `runMcpDiscovery` and is the contract every reader of this map relies
+     * on (tool merging, alwaysActive expansion, MCP-tool metadata lookup).
+     */
     tools: ToolsInput;
 }
 /**
@@ -51,6 +58,13 @@ interface McpServerState {
  * generic API never sees them.
  */
 interface MastraAgentState {
+    /**
+     * Project folder this agent operates within. Captured at `createAgent`
+     * time and reused by `updateAgent` to rebuild the `Workspace`
+     * (`projectRoot` is immutable post-create — `Agent.updateAgentConfig`
+     * does not allow changing it).
+     */
+    projectRoot: string;
     /** Mastra Agent instance. */
     agent: Agent;
     /**
@@ -99,6 +113,15 @@ interface MastraAgentState {
     toolSearchProcessor?: ToolSearchProcessor;
     /** Skill-search processor instance, when both `skills` and `toolSearch` are configured. */
     skillSearchProcessor?: SkillSearchProcessor;
+    /**
+     * Per-agent hook bag the SDK passed at `createAgent` time. The SDK
+     * resolves the bag once per install / restore / `updateAgentConfig` via
+     * `createAgentManager`'s `hooksForAgent` callback. The harness reads
+     * `hooks.onToolResult` at processor construction time and ignores
+     * unknown hook fields (forward-compat). Defaults to `{}` when the
+     * consumer didn't pass a `hooksForAgent`.
+     */
+    hooks: AgentHooks;
 }
 /**
  * Branded subtype consumers parameterize over to reach Mastra-specific
@@ -135,9 +158,9 @@ export type MastraAgentHarness = WithAgentConfig<AgentHarness & {
             getToolSearchProcessor(agentId: string): ToolSearchHandle | undefined;
             /**
              * Returns a {@link SkillSearchHandle} for an agent, or `undefined`
-             * if the agent doesn't have both `skills` and `toolSearch` configured
-             * (skill search is only enabled when both are set; without `toolSearch`,
-             * Mastra falls back to eager skill loading).
+             * if the agent doesn't have both `skills` and `skillSearch` configured
+             * (skill search is only enabled when both are set; without `skillSearch`,
+             * Mastra falls back to eager skill loading via `SkillsProcessor`).
              */
             getSkillSearchProcessor(agentId: string): SkillSearchHandle | undefined;
             /**
@@ -238,6 +261,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      */
     createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
     }): Promise<void>;
     /**
      * @requirements
@@ -264,6 +288,28 @@ export declare class MastraHarness implements MastraAgentHarness {
      * telemetry pair fires; the returned promise still resolves.
      */
     reconnectMcpServer(agentId: string, serverName: string): Promise<void>;
+    /**
+     * Implementation of {@link AgentHarness.updateAgent}. Diffs the next config
+     * against the agent's currently-applied state, preserves any MCP client
+     * whose `MCPServerConfig` is structurally equal to the previously-applied
+     * one, and rebuilds the Mastra `Agent` so non-MCP changes (instructions,
+     * model, tools, skills, rules, toolSearch) take effect.
+     *
+     * The Mastra `Agent`'s `tools: () => …` closure captures `state.mcpServers`
+     * by reference, so the new `Agent` constructed here observes the same Map
+     * the diff just mutated — preserved clients keep their discovered tool
+     * catalogs without a re-listing.
+     *
+     * State writes are per-server-incremental: each disconnect/connect mutates
+     * `state.mcpServers` synchronously after the corresponding harness work
+     * finishes. A re-entrant `updateAgent` call (e.g. SDK rollback against
+     * `previousConfig`) sees the harness's current truth and reverts only the
+     * actual deltas.
+     */
+    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
+    }): Promise<void>;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.

package/dist/mastra-harness.js

@@ -13,7 +13,7 @@ import { LibSQLStore } from '@mastra/libsql';
 import { createClient } from '@libsql/client';
 import { MCPClient } from '@mastra/mcp';
 import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, resolveToolApprovalMode, } from '@salesforce/sfdx-agent-sdk';
-import { HarnessBusOwner, lowerStreamInput } from '@salesforce/sfdx-agent-sdk/harness';
+import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import { mapMastraToMessage, mapMessageToMastra, partToTranscriptText } from './mastra-message-mapper.js';
 import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/schema-compat';
@@ -21,8 +21,9 @@ import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
 import { hasEnabledServers, mapToMastraMCPServers } from './mcp-config-mapper.js';
 import { buildMcpErrorDetail, sanitizeMcpErrorMessage } from './mcp-error-classifier.js';
 import { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
-import { partitionPool, } from './tool-search.js';
+import { partitionPool, resolveAlwaysActive, } from './tool-search.js';
 import {} from '@salesforce/llm-gateway-sdk';
+import { ToolResultRedactionProcessor } from './mastra-tool-result-redaction-processor.js';
 import { backfillCreatedAt, buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
 import { makeAbortable } from './utils.js';
 import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, } from '@mastra/core/workspace';
@@ -126,6 +127,33 @@ const MAX_TRANSCRIPT_CHARS = 400_000;
  * like deploys. Per-server `timeout` in MCPServerConfig still overrides this.
  */
 const DEFAULT_MCP_TIMEOUT_MS = 600_000;
+/**
+ * Build the `Map<namespacedName, ToolSource>` index `resolveAlwaysActive`
+ * needs to match `{ serverName }` / `{ serverName, toolName }` / `{ toolName }`
+ * entries against the merged custom-tools + MCP catalog.
+ *
+ * Custom tools key on their declared name with `serverName: undefined`
+ * (matching the cross-harness `tool-call` ChatEvent shape for non-MCP tools).
+ * MCP tools key on `${serverName}_${toolName}` with the un-namespaced
+ * `(serverName, toolName)` pair as the source — recovered by stripping the
+ * `${serverName}_` prefix from the namespaced key, the same way every reader
+ * of `MastraAgentState.mcpServers` handles namespacing.
+ */
+function buildToolSources(customTools, mcpServers) {
+    const sources = new Map();
+    for (const toolName of Object.keys(customTools)) {
+        sources.set(toolName, { serverName: undefined, toolName });
+    }
+    for (const [serverName, serverState] of mcpServers) {
+        const prefix = `${serverName}_`;
+        for (const namespaced of Object.keys(serverState.tools)) {
+            if (!namespaced.startsWith(prefix))
+                continue;
+            sources.set(namespaced, { serverName, toolName: namespaced.slice(prefix.length) });
+        }
+    }
+    return sources;
+}
 /** Loads `config.rules` into a single composed `instructions` string. See ARCHITECTURE.md → "Rule Composition". */
 async function composeInstructionsWithRules(baseInstructions, rulePaths) {
     const base = baseInstructions ?? '';
@@ -206,9 +234,9 @@ async function listMarkdownFilesInDirectory(dir) {
  * `Map<namespacedToolName, { serverName, McpToolInfo }>` index keyed off
  * discovery completion.
  */
-function lookupMcpToolMetadata(agentState, namespacedToolName) {
+function lookupMcpToolMetadata(mcpServers, namespacedToolName) {
     let best;
-    for (const [serverName, serverState] of agentState.mcpServers) {
+    for (const [serverName, serverState] of mcpServers) {
         if (!namespacedToolName.startsWith(`${serverName}_`))
             continue;
         if (!(namespacedToolName in serverState.tools))
@@ -519,10 +547,11 @@ export class MastraHarness {
         let toolSearchProcessor;
         let toolSearchAlwaysActive;
         let skillSearchProcessor;
-        // `toolSearch` rides through on the consumer's `MastraAgentConfig`
-        // even though `HarnessAgentConfig` itself doesn't declare it —
-        // `toHarnessConfig` preserves extra fields via spread.
+        // `toolSearch` and `skillSearch` ride through on the consumer's
+        // `MastraAgentConfig` even though `HarnessAgentConfig` itself doesn't
+        // declare them — `toHarnessConfig` preserves extra fields via spread.
         const toolSearchConfig = config.toolSearch;
+        const skillSearchConfig = config.skillSearch;
         try {
             const allowedPaths = (config.skills ?? []).filter((s) => path.isAbsolute(s));
             const localFs = new LocalFilesystem({ basePath: projectRoot, allowedPaths });
@@ -546,11 +575,11 @@ export class MastraHarness {
                 ])),
             });
             await mastraWorkspace.init();
-            // On-demand skill search: only when both `skills` and `toolSearch`
-            // are configured. Without `toolSearch`, Mastra's built-in eager
-            // skill loading is used (existing behavior).
-            if (mastraWorkspace.skills && toolSearchConfig) {
-                skillSearchProcessor = new SkillSearchProcessor({ workspace: mastraWorkspace });
+            if (mastraWorkspace.skills && skillSearchConfig) {
+                skillSearchProcessor = new SkillSearchProcessor({
+                    workspace: mastraWorkspace,
+                    ...(skillSearchConfig.topK !== undefined && { search: { topK: skillSearchConfig.topK } }),
+                });
             }
             // When toolSearch is configured, await MCP discovery so MCP tools
             // can enter the searchable pool. Without it, MCP discovery stays
@@ -562,7 +591,16 @@ export class MastraHarness {
                 const mcpTools = [...mcpServerStates.values()].reduce((acc, s) => ({ ...acc, ...s.tools }), {});
                 const allTools = { ...customTools, ...mcpTools };
                 const knownNames = new Set(Object.keys(allTools));
-                const partition = partitionPool(toolSearchConfig.pool, toolSearchConfig.alwaysActive, knownNames);
+                // Resolve `toolSearch.alwaysActive` entries against the
+                // merged custom-tools + MCP catalog. Each entry covers
+                // `{ serverName }` (server-wide), `{ serverName, toolName }`
+                // (precise), or `{ toolName }` (cross-source) — see
+                // `tool-search.ts` resolveAlwaysActive for the full rules.
+                // Unresolved `{ toolName }`-only entries flow through to
+                // `partitionPool`'s late-discovery hatch.
+                const sources = buildToolSources(customTools, mcpServerStates);
+                const { resolved, unresolvedToolNames } = resolveAlwaysActive(toolSearchConfig.alwaysActive, sources);
+                const partition = partitionPool(toolSearchConfig.pool, resolved, unresolvedToolNames, knownNames);
                 toolSearchAlwaysActive = new Set(partition.alwaysActive);
                 const poolTools = {};
                 for (const name of partition.pool) {
@@ -576,7 +614,24 @@ export class MastraHarness {
                     ttl: toolSearchConfig.ttl,
                 });
             }
-            const inputProcessorsList = [skillSearchProcessor, toolSearchProcessor].filter((p) => p !== undefined);
+            // Tool-result redaction processor — registered LAST in the
+            // inputProcessors chain so it sees the final messageList state
+            // after any earlier processor mutations. Reads the redactor
+            // from the per-agent hooks bag the SDK passed at createAgent
+            // time (resolved by `createAgentManager`'s `hooksForAgent`).
+            // Closes over the live mcpServerStates map (same reference the
+            // agent state will hold) so MCP `serverName` enrichment on
+            // `ToolResultRedactionInput` matches the cross-harness
+            // `tool-result` ChatEvent shape.
+            const onToolResult = options?.hooks?.onToolResult;
+            const toolResultRedactionProcessor = onToolResult
+                ? new ToolResultRedactionProcessor(agentId, onToolResult, (namespacedToolName) => lookupMcpToolMetadata(mcpServerStates, namespacedToolName))
+                : undefined;
+            const inputProcessorsList = [
+                skillSearchProcessor,
+                toolSearchProcessor,
+                toolResultRedactionProcessor,
+            ].filter((p) => p !== undefined);
             const inputProcessors = inputProcessorsList.length > 0 ? inputProcessorsList : undefined;
             agent = new Agent({
                 id: agentId,
@@ -605,6 +660,7 @@ export class MastraHarness {
             this.mastra.addAgent(agent);
             mastraAgentAdded = true;
             this.activeAgents.set(agentId, {
+                projectRoot,
                 agent,
                 composedInstructions,
                 validateFiles,
@@ -615,6 +671,7 @@ export class MastraHarness {
                 consumerToolNames,
                 toolSearchProcessor,
                 skillSearchProcessor,
+                hooks: options?.hooks ?? {},
             });
         }
         catch (error) {
@@ -769,6 +826,7 @@ export class MastraHarness {
             serverState.settled = true;
             const emitStatusChange = this.prepareMcpStatusChange(agentId, serverName, serverState, McpServerStatus.Error, message);
             this.buses.getLogBus()?.warn('MCP server reconnect failed', {
+                agentId,
                 serverName,
                 error: message,
             });
@@ -797,6 +855,222 @@ export class MastraHarness {
         serverState.ready = this.runMcpDiscovery(agentId, serverName, serverState.client, state.mcpServers, epoch, undefined, startTime);
         await serverState.ready;
     }
+    /**
+     * Implementation of {@link AgentHarness.updateAgent}. Diffs the next config
+     * against the agent's currently-applied state, preserves any MCP client
+     * whose `MCPServerConfig` is structurally equal to the previously-applied
+     * one, and rebuilds the Mastra `Agent` so non-MCP changes (instructions,
+     * model, tools, skills, rules, toolSearch) take effect.
+     *
+     * The Mastra `Agent`'s `tools: () => …` closure captures `state.mcpServers`
+     * by reference, so the new `Agent` constructed here observes the same Map
+     * the diff just mutated — preserved clients keep their discovered tool
+     * catalogs without a re-listing.
+     *
+     * State writes are per-server-incremental: each disconnect/connect mutates
+     * `state.mcpServers` synchronously after the corresponding harness work
+     * finishes. A re-entrant `updateAgent` call (e.g. SDK rollback against
+     * `previousConfig`) sees the harness's current truth and reverts only the
+     * actual deltas.
+     */
+    async updateAgent(agentId, llmGatewayClient, config = {}, options) {
+        const state = this.getAgentStateOrThrow(agentId);
+        options?.abortSignal?.throwIfAborted();
+        // ── Phase 0: validate non-MCP inputs before any MCP client is touched.
+        //            A bad rule path or skill path rejects updateAgent here so
+        //            half-applied state from non-MCP failures is impossible.
+        //            Mirrors Claude's posture; closes a Mastra atomicity gap
+        //            where Phase 1 ran first and a Phase-2 throw left MCP
+        //            servers already half-cycled.
+        const composedInstructions = await composeInstructionsWithRules(config.instructions, config.rules);
+        const allowedPaths = (config.skills ?? []).filter((s) => path.isAbsolute(s));
+        // projectRoot is immutable post-create — captured on agent state at
+        // createAgent time. Reuse it rather than threading it through every
+        // updateAgent call.
+        const projectRoot = state.projectRoot;
+        const localFs = new LocalFilesystem({ basePath: projectRoot, allowedPaths });
+        const sandbox = new LocalSandbox({
+            workingDirectory: projectRoot,
+            env: process.env,
+        });
+        const mastraWorkspace = new Workspace({
+            filesystem: localFs,
+            skills: config.skills,
+            sandbox,
+            tools: Object.fromEntries(ALL_MASTRA_WORKSPACE_TOOL_NAMES.map((nativeName) => [
+                nativeName,
+                { name: stripMastraWorkspacePrefix(nativeName) },
+            ])),
+        });
+        try {
+            await mastraWorkspace.init();
+        }
+        catch (error) {
+            await mastraWorkspace.destroy().catch(() => undefined);
+            throw error;
+        }
+        // ── Phase 1: MCP diff against state.mcpConfig ─────────────────────
+        const prevConfig = state.mcpConfig ?? {};
+        const nextConfig = config.mcpServers ?? {};
+        const allNames = new Set([...Object.keys(prevConfig), ...Object.keys(nextConfig)]);
+        const nextEnabledServers = hasEnabledServers(nextConfig)
+            ? mapToMastraMCPServers(nextConfig, config.orgJwt)
+            : {};
+        for (const name of allNames) {
+            const prev = prevConfig[name];
+            const next = nextConfig[name];
+            if (mcpServerConfigEqual(prev, next))
+                continue;
+            // Tear down whatever was previously attached for this name. Both
+            // "removed" and "changed" go through this branch; "added" hits no
+            // previous entry so the disconnect is a no-op.
+            const prevEntry = state.mcpServers.get(name);
+            if (prevEntry) {
+                state.mcpServers.delete(name);
+                await prevEntry.ready.catch(() => undefined);
+                await prevEntry.client.disconnect().catch(() => undefined);
+            }
+            // Connect the new one if the next config has it enabled.
+            if (next && next.enabled !== false) {
+                const serverDef = nextEnabledServers[name];
+                if (serverDef) {
+                    const client = new MCPClient({
+                        id: `${agentId}:${name}`,
+                        servers: { [name]: serverDef },
+                        timeout: DEFAULT_MCP_TIMEOUT_MS,
+                    });
+                    const entry = {
+                        client,
+                        currentStatus: McpServerStatus.Connecting,
+                        epoch: 0,
+                        ready: Promise.resolve(),
+                        settled: false,
+                        tools: {},
+                    };
+                    state.mcpServers.set(name, entry);
+                    entry.ready = this.runMcpDiscovery(agentId, name, client, state.mcpServers, 0, options?.abortSignal);
+                }
+            }
+        }
+        // ── Phase 2: non-MCP rebuild ──────────────────────────────────────
+        const consumerToolNames = new Set((config.tools ?? []).map((t) => t.name));
+        const parkerLookup = (threadId) => this.activeAgents.get(agentId)?.coordinators.get(threadId)?.parkConsumerToolCall;
+        const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools, parkerLookup) : {};
+        const { model: resolvedModel, validateFiles } = this.modelConfigFactory.create(llmGatewayClient, this.buses.getLogBus());
+        // Capture the live mcpServers map by reference — the new Agent's
+        // tools() closure will read it on every step, so preserved clients'
+        // discovered tools stay visible without a re-listing.
+        const mcpServers = state.mcpServers;
+        const toolSearchConfig = config.toolSearch;
+        const skillSearchConfig = config.skillSearch;
+        let toolSearchProcessor;
+        let toolSearchAlwaysActive;
+        let skillSearchProcessor;
+        try {
+            if (mastraWorkspace.skills && skillSearchConfig) {
+                skillSearchProcessor = new SkillSearchProcessor({
+                    workspace: mastraWorkspace,
+                    ...(skillSearchConfig.topK !== undefined && { search: { topK: skillSearchConfig.topK } }),
+                });
+            }
+            if (toolSearchConfig) {
+                if (mcpServers.size > 0) {
+                    await Promise.allSettled([...mcpServers.values()].map((s) => s.ready));
+                }
+                const mcpTools = [...mcpServers.values()].reduce((acc, s) => ({ ...acc, ...s.tools }), {});
+                const allTools = { ...customTools, ...mcpTools };
+                const knownNames = new Set(Object.keys(allTools));
+                const sources = buildToolSources(customTools, mcpServers);
+                const { resolved, unresolvedToolNames } = resolveAlwaysActive(toolSearchConfig.alwaysActive, sources);
+                const partition = partitionPool(toolSearchConfig.pool, resolved, unresolvedToolNames, knownNames);
+                toolSearchAlwaysActive = new Set(partition.alwaysActive);
+                const poolTools = {};
+                for (const name of partition.pool) {
+                    if (allTools[name]) {
+                        poolTools[name] = allTools[name];
+                    }
+                }
+                toolSearchProcessor = new ToolSearchProcessor({
+                    tools: poolTools,
+                    search: toolSearchConfig.topK !== undefined ? { topK: toolSearchConfig.topK } : undefined,
+                    ttl: toolSearchConfig.ttl,
+                });
+            }
+            // Tool-result redaction processor — built off the per-agent hook
+            // bag the SDK passed at updateAgent time. Same wiring as createAgent
+            // (registered LAST in the chain so it sees the post-mutation
+            // messageList state); closes over the live state.mcpServers map so
+            // MCP `serverName` enrichment matches the cross-harness shape.
+            const onToolResult = options?.hooks?.onToolResult;
+            const toolResultRedactionProcessor = onToolResult
+                ? new ToolResultRedactionProcessor(agentId, onToolResult, (namespacedToolName) => lookupMcpToolMetadata(mcpServers, namespacedToolName))
+                : undefined;
+            const inputProcessorsList = [
+                skillSearchProcessor,
+                toolSearchProcessor,
+                toolResultRedactionProcessor,
+            ].filter((p) => p !== undefined);
+            const inputProcessors = inputProcessorsList.length > 0 ? inputProcessorsList : undefined;
+            const newAgent = new Agent({
+                id: agentId,
+                name: config.name || agentId,
+                instructions: composedInstructions,
+                model: resolvedModel,
+                memory: this.memory,
+                tools: () => {
+                    const mcpTools = [...mcpServers.values()].reduce((acc, s) => ({ ...acc, ...s.tools }), {});
+                    const merged = { ...customTools, ...mcpTools };
+                    if (!toolSearchAlwaysActive) {
+                        return merged;
+                    }
+                    const active = {};
+                    for (const [name, tool] of Object.entries(merged)) {
+                        if (toolSearchAlwaysActive.has(name)) {
+                            active[name] = tool;
+                        }
+                    }
+                    return active;
+                },
+                workspace: mastraWorkspace,
+                ...(inputProcessors ? { inputProcessors } : {}),
+            });
+            // Mastra's addAgent silently no-ops on a duplicate key, so we must
+            // remove first. The previous Agent instance is still referenced by
+            // any in-flight stream's coordinator (captured at stream-start) and
+            // continues to run against its bound model. The next stream() will
+            // resolve newAgent from activeAgents.
+            this.mastra.removeAgent(agentId);
+            this.mastra.addAgent(newAgent);
+            // Dispose the previous workspace and skill-search processor only
+            // after the new ones are wired in, so any synchronous reader sees
+            // a coherent state. Coordinators are intentionally NOT disposed —
+            // they hold references to the old Agent and finish their turns
+            // against it.
+            const previousWorkspace = state.mastraWorkspace;
+            const previousSkillSearchProcessor = state.skillSearchProcessor;
+            state.agent = newAgent;
+            state.composedInstructions = composedInstructions;
+            state.validateFiles = validateFiles;
+            state.mcpConfig = config.mcpServers;
+            state.mastraWorkspace = mastraWorkspace;
+            state.consumerToolNames = consumerToolNames;
+            state.toolSearchProcessor = toolSearchProcessor;
+            state.skillSearchProcessor = skillSearchProcessor;
+            state.hooks = options?.hooks ?? {};
+            previousSkillSearchProcessor?.dispose();
+            await previousWorkspace?.destroy().catch(() => undefined);
+        }
+        catch (error) {
+            // Phase 2 failed after Phase 1 mutated state.mcpServers. We don't
+            // try to revert Phase 1 here — the SDK's rollback path will call
+            // updateAgent(previousConfig) which re-diffs against the now-
+            // current state and reverts the actual deltas. Phase 2 cleanup is
+            // local: dispose anything we constructed.
+            skillSearchProcessor?.dispose();
+            await mastraWorkspace.destroy().catch(() => undefined);
+            throw error;
+        }
+    }
     // ── Thread (Chat Session) Lifecycle ──────────────────────────────
     /**
      * @requirements
@@ -915,7 +1189,7 @@ export class MastraHarness {
             ]);
         }
         catch (err) {
-            throw new AgentSDKError(`Failed to compact thread "${threadId}" for agent "${agentId}": ${err instanceof Error ? err.message : String(err)}`, AgentSDKErrorType.COMPACTION_FAILED, { cause: err });
+            throw new AgentSDKError(`Failed to compact thread "${threadId}" for agent "${agentId}": ${getErrorMessage(err)}`, AgentSDKErrorType.COMPACTION_FAILED, { cause: err });
         }
         // Source-thread cleanup is best-effort. The user's data is already
         // safely seeded into newThreadId; a failed delete leaves an orphan
@@ -1039,7 +1313,7 @@ export class MastraHarness {
             toolApprovalTimeoutMs: this.toolApprovalTimeoutMs,
             mode: approvalMode,
             consumerToolNames: agentState.consumerToolNames,
-            lookupMcpToolMetadata: (name) => lookupMcpToolMetadata(agentState, name),
+            lookupMcpToolMetadata: (name) => lookupMcpToolMetadata(agentState.mcpServers, name),
             logBus: this.buses.getLogBus(),
         });
         agentState.coordinators.set(threadId, coordinator);
@@ -1413,6 +1687,7 @@ export class MastraHarness {
                 s.settled = true;
                 const emitStatusChange = this.prepareMcpStatusChange(agentId, serverName, s, McpServerStatus.Error, errorMessage);
                 this.buses.getLogBus()?.warn('MCP server discovery failed', {
+                    agentId,
                     serverName,
                     error: errorMessage,
                 });

package/dist/mastra-tool-result-redaction-processor.d.ts

@@ -0,0 +1,54 @@
+import type { ProcessInputStepArgs, Processor } from '@mastra/core/processors';
+import { type McpToolAnnotations, type ToolResultRedactor } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Internal MCP-catalog lookup the harness passes the processor at construction
+ * time, closed over the agent's `mcpServers` map. Returns the originating
+ * server name (and optionally annotations) for a Mastra-namespaced tool name
+ * (`<serverName>_<toolName>`); `undefined` for consumer-declared / workspace
+ * / built-in tools. Mirrors `MastraHarness#lookupMcpToolMetadata` so the
+ * `ToolResultRedactionInput.serverName` enrichment matches the cross-harness
+ * shape on the `tool-result` ChatEvent.
+ */
+export type McpServerLookup = (namespacedToolName: string) => {
+    serverName: string;
+    annotations?: McpToolAnnotations;
+} | undefined;
+/**
+ * Mastra `Processor` that runs a consumer-supplied {@link ToolResultRedactor}
+ * over every new tool-result message before the next LLM call sees it.
+ *
+ * ### Why `processInputStep` and not `processInput`
+ *
+ * `processInput` fires once at the start of a stream. Tool results arrive
+ * mid-stream (the model emits a tool-call, the tool runs, the result row is
+ * appended to the MessageList, then the loop pumps another LLM call). Only
+ * `processInputStep` fires before EVERY step's LLM call — so it sees newly
+ * appended tool-result rows on the second and subsequent steps and gets a
+ * chance to redact them before the model is invoked.
+ *
+ * ### Per-call dedup
+ *
+ * The same MessageList survives across steps within a single
+ * `agent.stream()` invocation. To avoid re-redacting on every step (which
+ * would be quadratic *and* would mean the redactor sees its own previous
+ * replacements), the processor records every `toolCallId` it has redacted
+ * in `args.state`, scoped per-stream by Mastra's processor-state contract.
+ *
+ * ### Throw policy
+ *
+ * The processor does NOT catch redactor throws. An exception propagates
+ * through `processInputStep`, which the Mastra approval coordinator's pump
+ * loop treats as `pump-error`: the consumer sees a synthetic `error` +
+ * `finish('error')` ChatEvent pair on the eventStream and the run aborts.
+ * The original tool output never reaches the model. Consumers requiring a
+ * richer fail-closed substitute wrap their redactor's body in `try`/`catch`
+ * themselves — see SDK README → "Tool-Result Redaction".
+ */
+export declare class ToolResultRedactionProcessor implements Processor<'sfdx-tool-result-redaction'> {
+    private readonly agentId;
+    private readonly redactor;
+    private readonly lookupMcpToolMetadata;
+    readonly id: "sfdx-tool-result-redaction";
+    constructor(agentId: string, redactor: ToolResultRedactor, lookupMcpToolMetadata: McpServerLookup);
+    processInputStep(args: ProcessInputStepArgs): Promise<void>;
+}

package/dist/mastra-tool-result-redaction-processor.js

@@ -0,0 +1,136 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context';
+import {} from '@salesforce/sfdx-agent-sdk';
+/**
+ * Mastra `Processor` that runs a consumer-supplied {@link ToolResultRedactor}
+ * over every new tool-result message before the next LLM call sees it.
+ *
+ * ### Why `processInputStep` and not `processInput`
+ *
+ * `processInput` fires once at the start of a stream. Tool results arrive
+ * mid-stream (the model emits a tool-call, the tool runs, the result row is
+ * appended to the MessageList, then the loop pumps another LLM call). Only
+ * `processInputStep` fires before EVERY step's LLM call — so it sees newly
+ * appended tool-result rows on the second and subsequent steps and gets a
+ * chance to redact them before the model is invoked.
+ *
+ * ### Per-call dedup
+ *
+ * The same MessageList survives across steps within a single
+ * `agent.stream()` invocation. To avoid re-redacting on every step (which
+ * would be quadratic *and* would mean the redactor sees its own previous
+ * replacements), the processor records every `toolCallId` it has redacted
+ * in `args.state`, scoped per-stream by Mastra's processor-state contract.
+ *
+ * ### Throw policy
+ *
+ * The processor does NOT catch redactor throws. An exception propagates
+ * through `processInputStep`, which the Mastra approval coordinator's pump
+ * loop treats as `pump-error`: the consumer sees a synthetic `error` +
+ * `finish('error')` ChatEvent pair on the eventStream and the run aborts.
+ * The original tool output never reaches the model. Consumers requiring a
+ * richer fail-closed substitute wrap their redactor's body in `try`/`catch`
+ * themselves — see SDK README → "Tool-Result Redaction".
+ */
+export class ToolResultRedactionProcessor {
+    agentId;
+    redactor;
+    lookupMcpToolMetadata;
+    id = 'sfdx-tool-result-redaction';
+    constructor(agentId, redactor, lookupMcpToolMetadata) {
+        this.agentId = agentId;
+        this.redactor = redactor;
+        this.lookupMcpToolMetadata = lookupMcpToolMetadata;
+    }
+    async processInputStep(args) {
+        const seen = readSeenSet(args.state);
+        // The harness sets MASTRA_THREAD_ID_KEY on every thread-bound entry
+        // point's RequestContext. Thread-less paths (e.g. compactThread's
+        // `summarize()` helper) fall back to '' — the redactor uses threadId
+        // for identification only, not routing.
+        const ctx = args.requestContext;
+        const threadIdValue = ctx?.get?.(MASTRA_THREAD_ID_KEY);
+        const threadId = typeof threadIdValue === 'string' ? threadIdValue : '';
+        for (const message of args.messages) {
+            await redactMessageInPlace({
+                message,
+                seen,
+                redactor: this.redactor,
+                lookup: this.lookupMcpToolMetadata,
+                agentId: this.agentId,
+                threadId,
+            });
+        }
+    }
+}
+const SEEN_KEY = '__sfdx-tool-result-redaction:seen-toolCallIds';
+function readSeenSet(state) {
+    const existing = state[SEEN_KEY];
+    if (existing instanceof Set)
+        return existing;
+    const fresh = new Set();
+    state[SEEN_KEY] = fresh;
+    return fresh;
+}
+/**
+ * Walk one DB-shaped message's parts in place. `MastraToolInvocationPart`s
+ * carry the tool result on `toolInvocation.result` (success) or surface
+ * errors via `state === 'output-error'` with `errorText`. Both paths are
+ * funneled through the redactor so consumers don't have to special-case the
+ * error variant.
+ */
+async function redactMessageInPlace(opts) {
+    const { message, seen, redactor, lookup, agentId, threadId } = opts;
+    const parts = message.content.parts;
+    if (!Array.isArray(parts))
+        return;
+    for (const rawPart of parts) {
+        if (!isToolInvocationResultPart(rawPart))
+            continue;
+        const part = rawPart;
+        const inv = part.toolInvocation;
+        const toolCallId = inv.toolCallId;
+        if (seen.has(toolCallId))
+            continue;
+        seen.add(toolCallId);
+        const isError = inv.state === 'output-error' || inv.state === 'output-denied';
+        const originalOutput = isError && inv.errorText !== undefined ? inv.errorText : inv.result;
+        const metadata = lookup(inv.toolName);
+        const result = await redactor({
+            agentId,
+            threadId,
+            toolCallId,
+            toolName: inv.toolName,
+            ...(metadata?.serverName ? { serverName: metadata.serverName } : {}),
+            output: originalOutput,
+            isError,
+        });
+        if (!result || typeof result !== 'object' || !('output' in result))
+            continue;
+        // Both success and error paths replace `result` so the model sees
+        // the redacted shape. `errorText` is left intact for non-error
+        // success paths (untouched) and overwritten with the redaction
+        // string when the original was an error so downstream UI keeps a
+        // consistent text projection.
+        inv.result = result.output;
+        if (isError && typeof result.output === 'string') {
+            inv.errorText = result.output;
+        }
+    }
+}
+function isToolInvocationResultPart(part) {
+    if (part.type !== 'tool-invocation')
+        return false;
+    const inv = part.toolInvocation;
+    if (!inv || typeof inv.toolCallId !== 'string' || typeof inv.toolName !== 'string')
+        return false;
+    // Only redact result-bearing states. `partial-call` / `call` /
+    // `approval-requested` / `approval-responded` haven't produced an output
+    // yet; redacting them would either no-op (result is undefined) or get
+    // overwritten on the next state transition.
+    return inv.state === 'result' || inv.state === 'output-error' || inv.state === 'output-denied';
+}
+//# sourceMappingURL=mastra-tool-result-redaction-processor.js.map

package/dist/mcp-error-classifier.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { isAbortError } from '@salesforce/agentic-common';
+import { getErrorMessage, isAbortError } from '@salesforce/agentic-common';
 /**
  * Structural duck-type for MCP-shaped errors. Matches the upstream
  * `@modelcontextprotocol/sdk` `McpError` class (`extends Error`, numeric
@@ -35,7 +35,7 @@ function isMcpErrorLike(err) {
  * through `String(...)`.
  */
 export function sanitizeMcpErrorMessage(err) {
-    const raw = err instanceof Error ? err.message : String(err);
+    const raw = getErrorMessage(err);
     const lines = raw.split(/\r?\n/);
     // Keep the first line that is NOT a V8 stack frame. V8 frames start with
     // arbitrary leading whitespace followed by "at " (matched at line start).

package/dist/tool-search.d.ts

@@ -1,4 +1,5 @@
 import type { AgentConfig } from '@salesforce/sfdx-agent-sdk';
+import { type AlwaysActiveEntry } from '@salesforce/sfdx-agent-sdk/harness';
 /**
  * Configuration for hiding a large tool catalog behind Mastra's
  * search/load workflow. When present on `MastraAgentConfig.toolSearch`,
@@ -9,44 +10,78 @@ import type { AgentConfig } from '@salesforce/sfdx-agent-sdk';
 export type MastraToolSearchConfig = {
     /**
      * Tools eligible for search/load. `'*'` means every searchable tool;
-     * an explicit array limits the pool to the listed names.
+     * an explicit array limits the pool to the listed names. Pool entries
+     * are bare tool names (un-namespaced) — the harness resolves them
+     * against the merged custom-tools + MCP catalog.
      */
     pool: string[] | '*';
     /**
      * Tools that bypass search and are always visible to the model.
-     * Overrides `pool` on overlap. MCP tool names use the harness namespace
-     * prefix, e.g. `sfdx_deploy_metadata` for the `deploy_metadata` tool on
-     * the `sfdx` server.
+     *
+     * Each entry covers one of three patterns:
+     * - `{ serverName: 'X' }` — every tool from server `X`.
+     * - `{ serverName: 'X', toolName: 'Y' }` — exactly tool `Y` on server `X`.
+     * - `{ toolName: 'Y' }` — any tool named `Y`, regardless of source.
+     *
+     * Overrides `pool` on overlap.
+     *
+     * Mirrors `ClaudeAgentConfig.toolSearch.alwaysActive`. See
+     * {@link AlwaysActiveEntry} on `@salesforce/sfdx-agent-sdk/harness`
+     * for the full matching semantics.
      */
-    alwaysActive?: string[];
+    alwaysActive?: AlwaysActiveEntry[];
     /** Max tools returned per search (advisory). */
     topK?: number;
     /** Time-to-live in ms for a granted tool in the active set (advisory). */
     ttl?: number;
 };
+/**
+ * Configuration for hiding a large skill catalog behind Mastra's
+ * on-demand `search_skills` / `load_skill` meta-tools. When present
+ * on `MastraAgentConfig.skillSearch`, the harness wires
+ * `SkillSearchProcessor` so the model discovers skills via search
+ * rather than seeing the full catalog injected into the system
+ * prompt. When absent, the default `SkillsProcessor` (eager catalog)
+ * is used.
+ *
+ * Mirrors the cross-harness shape — Claude's `ClaudeAgentConfig.skillSearch`
+ * has the same field.
+ */
+export type MastraSkillSearchConfig = {
+    /**
+     * Max number of results returned per `search_skills` call (advisory).
+     * Defaults to 5 — same as Mastra's `SkillSearchProcessor` default and
+     * Claude's `ClaudeSkillSearchConfig.topK` default.
+     */
+    topK?: number;
+};
 /**
  * Mastra-flavored extension of {@link AgentConfig}, adding the Mastra-only
- * `toolSearch` field. Consumers do not import or pass this type explicitly —
- * `MastraAgentHarness` brands itself with `MastraAgentConfig` via
- * `WithAgentConfig`, so `manager.createAgent`'s config parameter resolves to
- * this shape automatically and `toolSearch` autocompletes on the object
- * literal.
+ * `toolSearch` and `skillSearch` fields. Consumers do not import or pass
+ * this type explicitly — `MastraAgentHarness` brands itself with
+ * `MastraAgentConfig` via `WithAgentConfig`, so `manager.createAgent`'s
+ * config parameter resolves to this shape automatically and the extra
+ * fields autocomplete on the object literal.
  *
  * @example
  * ```ts
  * const agent = await manager.createAgent(projectRoot, {
  *     instructions: '...',
  *     tools,
- *     toolSearch: { pool: '*', alwaysActive: ['lookup_account'] },
+ *     toolSearch: { pool: '*', alwaysActive: [{ toolName: 'lookup_account' }] },
+ *     skills: ['/path/to/skills'],
+ *     skillSearch: { topK: 5 },
  * });
  * ```
  *
  * Extra fields ride through `toHarnessConfig`'s `...rest` spread to the
- * harness, which reads `toolSearch` at its boundary via runtime narrowing.
+ * harness, which reads them at its boundary via runtime narrowing.
  */
 export type MastraAgentConfig = AgentConfig & {
     /** Hide tools behind Mastra's search/load workflow. */
     toolSearch?: MastraToolSearchConfig;
+    /** Hide skills behind Mastra's `search_skills` / `load_skill` meta-tools. */
+    skillSearch?: MastraSkillSearchConfig;
 };
 /**
  * Opaque handle to the tool-search runtime state, exposed via
@@ -97,11 +132,47 @@ export interface SkillSearchHandle {
     readonly id: string;
 }
 /**
- * Resolve `pool` / `alwaysActive` against known tools. `'*'` expands to all
- * known names; unknown pool names are dropped; unknown alwaysActive names are
- * kept for late MCP discovery; alwaysActive overrides pool on overlap.
+ * Tool sourcing context fed to {@link resolveAlwaysActive}. The harness has
+ * already merged consumer custom tools with discovered MCP tools by the
+ * time it asks tool-search to partition; this map keeps each tool's origin
+ * recoverable so `{ serverName }` and `{ toolName }` entries match correctly.
+ */
+export type ToolSource = {
+    /** Logical MCP server name (the key in `AgentConfig.mcpServers`), or `undefined` for non-MCP tools (custom tools, workspace tools, built-ins). */
+    serverName: string | undefined;
+    /** Bare tool name from the upstream MCP server's `tools/list`, or the consumer-declared name for non-MCP tools. */
+    toolName: string;
+};
+/**
+ * Resolve {@link MastraToolSearchConfig.alwaysActive} entries to a set of
+ * Mastra-namespaced tool names that should bypass tool-search deferral.
+ *
+ * Each entry is matched against `knownToolSources` (a map keyed by the
+ * Mastra-namespaced name `{customName}` for custom tools or
+ * `${serverName}_${toolName}` for MCP tools, with the un-namespaced
+ * `(serverName, toolName)` pair as the value) using the cross-harness
+ * {@link matchesAlwaysActive} predicate. Unmatched entries are kept in the
+ * returned `unresolved` list so the harness can fold them into the
+ * tool-search pool's "kept for late MCP discovery" hatch — same posture
+ * as the previous `partitionPool`'s string-based behavior.
+ *
+ * Pure / deterministic.
+ */
+export declare function resolveAlwaysActive(entries: AlwaysActiveEntry[] | undefined, knownToolSources: ReadonlyMap<string, ToolSource>): {
+    resolved: Set<string>;
+    unresolvedToolNames: string[];
+};
+/**
+ * Resolve `pool` / `alwaysActive` against known tools.
+ *
+ * - `pool: '*'` expands to all known namespaced names; unknown pool names
+ *   in an explicit array are dropped.
+ * - `alwaysActive` is the resolved-and-namespaced set from
+ *   {@link resolveAlwaysActive}, plus any unresolved `{ toolName }`-only
+ *   entries kept for late MCP discovery.
+ * - alwaysActive overrides pool on overlap.
  */
-export declare function partitionPool(poolSpec: string[] | '*', alwaysActive: string[] | undefined, allKnown: ReadonlySet<string>): {
+export declare function partitionPool(poolSpec: string[] | '*', alwaysActiveResolved: Set<string>, unresolvedToolNames: readonly string[], allKnown: ReadonlySet<string>): {
     pool: string[];
     alwaysActive: string[];
 };

package/dist/tool-search.js

@@ -2,16 +2,67 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { matchesAlwaysActive, validateAlwaysActiveEntry, } from '@salesforce/sfdx-agent-sdk/harness';
 /**
- * Resolve `pool` / `alwaysActive` against known tools. `'*'` expands to all
- * known names; unknown pool names are dropped; unknown alwaysActive names are
- * kept for late MCP discovery; alwaysActive overrides pool on overlap.
+ * Resolve {@link MastraToolSearchConfig.alwaysActive} entries to a set of
+ * Mastra-namespaced tool names that should bypass tool-search deferral.
+ *
+ * Each entry is matched against `knownToolSources` (a map keyed by the
+ * Mastra-namespaced name `{customName}` for custom tools or
+ * `${serverName}_${toolName}` for MCP tools, with the un-namespaced
+ * `(serverName, toolName)` pair as the value) using the cross-harness
+ * {@link matchesAlwaysActive} predicate. Unmatched entries are kept in the
+ * returned `unresolved` list so the harness can fold them into the
+ * tool-search pool's "kept for late MCP discovery" hatch — same posture
+ * as the previous `partitionPool`'s string-based behavior.
+ *
+ * Pure / deterministic.
  */
-export function partitionPool(poolSpec, alwaysActive, allKnown) {
-    const resolvedActive = alwaysActive ?? [];
-    const activeSet = new Set(resolvedActive);
+export function resolveAlwaysActive(entries, knownToolSources) {
+    const resolved = new Set();
+    const unresolvedToolNames = [];
+    if (!entries || entries.length === 0)
+        return { resolved, unresolvedToolNames };
+    for (const entry of entries) {
+        validateAlwaysActiveEntry(entry);
+        let matched = false;
+        for (const [namespaced, source] of knownToolSources) {
+            if (matchesAlwaysActive([entry], source.serverName, source.toolName)) {
+                resolved.add(namespaced);
+                matched = true;
+            }
+        }
+        if (!matched && entry.toolName !== undefined && entry.serverName === undefined) {
+            // Late-discovery hatch: a `{ toolName }`-only entry that doesn't
+            // resolve today might match a yet-to-be-discovered MCP tool by the
+            // same name. Carry it forward so the partition function can keep
+            // it visible. Server-scoped misses are NOT carried — those are
+            // typos (configured server name we know of, no matching tool) and
+            // surfacing them would mask the typo.
+            unresolvedToolNames.push(entry.toolName);
+        }
+    }
+    return { resolved, unresolvedToolNames };
+}
+/**
+ * Resolve `pool` / `alwaysActive` against known tools.
+ *
+ * - `pool: '*'` expands to all known namespaced names; unknown pool names
+ *   in an explicit array are dropped.
+ * - `alwaysActive` is the resolved-and-namespaced set from
+ *   {@link resolveAlwaysActive}, plus any unresolved `{ toolName }`-only
+ *   entries kept for late MCP discovery.
+ * - alwaysActive overrides pool on overlap.
+ */
+export function partitionPool(poolSpec, alwaysActiveResolved, unresolvedToolNames, allKnown) {
+    // Late-discovery names appended verbatim — the partition's consumer (the
+    // ToolSearchProcessor) treats `alwaysActive` as a name-list it filters
+    // against the live tool catalog, so unmatched names are harmless until
+    // they resolve.
+    const merged = [...alwaysActiveResolved, ...unresolvedToolNames];
+    const activeSet = new Set(merged);
     const resolvedPoolBase = poolSpec === '*' ? Array.from(allKnown) : poolSpec.filter((n) => allKnown.has(n));
     const pool = resolvedPoolBase.filter((n) => !activeSet.has(n));
-    return { pool, alwaysActive: resolvedActive };
+    return { pool, alwaysActive: merged };
 }
 //# sourceMappingURL=tool-search.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -24,40 +24,41 @@
     "dist",
     "!dist/**/*.map",
     "!dist/test",
+    "CHANGELOG.md",
     "LICENSE.txt"
   ],
   "dependencies": {
     "@ai-sdk/provider": "^3.0.10",
     "@libsql/client": "^0.15.15",
-    "@mastra/core": "^1.36.0",
+    "@mastra/core": "^1.37.1",
     "@mastra/libsql": "^1.11.1",
-    "@mastra/mcp": "^1.8.0",
-    "@mastra/memory": "^1.19.0",
+    "@mastra/mcp": "^1.8.1",
+    "@mastra/memory": "^1.20.0",
     "@mastra/schema-compat": "^1.2.10",
-    "@salesforce/agentic-common": "0.8.0",
-    "@salesforce/llm-gateway-sdk": "0.12.0"
+    "@salesforce/agentic-common": "0.9.0",
+    "@salesforce/llm-gateway-sdk": "0.13.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.16.0"
+    "@salesforce/sfdx-agent-sdk": "0.17.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.16.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-sdk": "0.17.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": {