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

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 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.17.0] - 2026-06-09
+
+### Fixes
+- **harness-mastra**: drop inline WAL-pragma workaround now that LibSQLStore.close() ships stable ([#576](https://github.com/forcedotcom/agentic-dx/pull/576))
+
+### Chores
+- **deps**: bump dependencies across packages @W-22695116@ ([#577](https://github.com/forcedotcom/agentic-dx/pull/577))
+- **deps**: bump the mastra group across 1 directory with 5 updates ([#569](https://github.com/forcedotcom/agentic-dx/pull/569))
+- **deps**: bump @libsql/client from 0.15.15 to 0.17.3 ([#570](https://github.com/forcedotcom/agentic-dx/pull/570))
+- **deps-dev**: bump @types/node from 22.19.19 to 22.19.20 in the dev-dependencies group ([#568](https://github.com/forcedotcom/agentic-dx/pull/568))
+
+## [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

@@ -26,10 +26,10 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ### Removing the storage directory on Windows
 
-`manager.shutdown()` closes the libsql client (forcedotcom/agentic-dx#429), but the underlying SQLite/WAL handle release
-on Windows is asynchronous at the OS level. After `shutdown()` returns, Windows can take anywhere from ~60 ms to several
-seconds to actually release the file lock — so a naïve `fs.rm(storageRoot)` immediately afterward will fail with
-`EBUSY`. Pass `maxRetries` and `retryDelay` so Node retries until the OS lets go:
+`manager.shutdown()` checkpoints the WAL and closes the libsql client (forcedotcom/agentic-dx#429,
+mastra-ai/mastra#17285), but the underlying SQLite handle release on Windows is asynchronous at the OS level. After
+`shutdown()` returns, Windows can briefly hold the file lock — so a naïve `fs.rm(storageRoot)` immediately afterward can
+fail with `EBUSY`. Pass `maxRetries` and `retryDelay` so Node retries until the OS lets go:
 
 ```ts
 import { rm } from 'node:fs/promises';
@@ -38,9 +38,7 @@ await manager.shutdown();
 await rm(storageRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
 ```
 
-Linux and macOS release the handle eagerly; the retry options are no-ops on those platforms. Tracking upstream at
-[mastra-ai/mastra#17285](https://github.com/mastra-ai/mastra/issues/17285) — when `LibSQLStore` exposes a public
-`close()` that includes a WAL checkpoint, this delay should shrink or disappear.
+Linux and macOS release the handle eagerly; the retry options are no-ops on those platforms.
 
 ## Public API
 
@@ -62,13 +60,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 +89,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 +105,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 +217,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;
             /**
@@ -184,18 +207,10 @@ export declare class MastraHarness implements MastraAgentHarness {
      * would mix process state.
      */
     protected readonly activeAgents: Map<string, MastraAgentState>;
-    private readonly libsqlClient;
     private readonly storage;
     private readonly memory;
     private readonly mastra;
     private readonly buses;
-    /**
-     * Tracks the in-flight storage init so {@link shutdown} can settle it
-     * before closing the libsql client. Without this, Mastra's lazy storage
-     * init can fire after `client.close()` and surface as an unhandled
-     * `CLIENT_CLOSED` rejection (#429 follow-up).
-     */
-    private readonly storageReady;
     /**
      * Mastra-specific extension surface, typed off `MastraAgentHarness`. The
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
@@ -210,10 +225,10 @@ export declare class MastraHarness implements MastraAgentHarness {
      * @requirements
      * - MUST disconnect the mcpClient for every active agent before clearing state.
      * - MUST clear the `activeAgents` map.
-     * - MUST shut down the global `this.mastra` orchestrator.
-     * - MUST close the libsql client so the underlying SQLite handle is released
-     *   (Windows blocks fs.rm of the storage dir while the WAL/shm files are open;
-     *   see forcedotcom/agentic-dx#429).
+     * - MUST shut down the global `this.mastra` orchestrator. Mastra.shutdown() awaits
+     *   `storage.close()`, which checkpoints the WAL and unlinks the -wal/-shm sidecars
+     *   so a subsequent `fs.rm` of the storage dir succeeds on Windows
+     *   (forcedotcom/agentic-dx#429, mastra-ai/mastra#17285).
      */
     shutdown(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
@@ -238,6 +253,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 +280,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`.