@salesforce/sfdx-agent-harness-mastra 0.7.0 → 0.9.0

package/README.md

@@ -24,6 +24,24 @@ const manager = await createAgentManager('/path/to/storage', new MastraHarnessFa
 See the [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full consumer-facing API. For
 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:
+
+```ts
+import { rm } from 'node:fs/promises';
+
+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.
+
 ## Public API
 
 ### Core

package/dist/mastra-harness.d.ts

@@ -2,7 +2,7 @@ import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import type { ChunkType } from '@mastra/core/stream';
 import { MCPClient } from '@mastra/mcp';
-import { type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerInfo, type Message, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
 import type { MastraModelConfigFactory } from './model-config-factory.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
@@ -20,18 +20,53 @@ import { Workspace } from '@mastra/core/workspace';
  * if the consumer breaks out of the event stream early (common in
  * approval UIs), we must finish reading the stream to ensure the
  * snapshot is persisted before we attempt to resume.
+ *
+ * `disposeAbortListener` is invoked whenever the entry is replaced or
+ * removed so the per-run abort listener (installed by `stream()` against
+ * the caller's `streamOptions.abortSignal`) cannot fire on a run that is
+ * no longer the active one for the thread. Mirrors the SDK invariant
+ * "every chat turn ends with exactly one terminal `FinishEvent`" by
+ * ensuring we don't accidentally abort a continuation run that
+ * `approveToolCall` / `declineToolCall` has already authorized.
  */
 interface ActiveRun {
     runId: string;
     fullStream: ReadableStream<ChunkType>;
+    disposeAbortListener?: () => void;
 }
 /**
  * Per-server MCP state. Each enabled server gets its own MCPClient and
  * independent discovery promise so readiness is tracked individually.
+ *
+ * `epoch` increments on every fresh discovery (initial create + each
+ * reconnect). Discovery callbacks captured against an earlier epoch drop their
+ * writes when a newer discovery has already started for the same server, so an
+ * orphaned in-flight `listToolsetsWithErrors()` cannot overwrite a fresher
+ * discovery's `tools` / `error` / `settled` state.
  */
 interface McpServerState {
     client: MCPClient;
+    /**
+     * Last `McpServerStatus` value emitted (or seeded to `Connecting` at
+     * construction). Updated synchronously by `emitMcpStatusChange()` so a
+     * follow-up `getMcpServerInfo()` call observes the world the most recent
+     * `mcp-server-status-changed` event described.
+     */
+    currentStatus: McpServerStatus;
+    epoch: number;
+    /**
+     * Sanitized human-readable error message. V8 stack frames and file paths
+     * have been stripped — safe for UI banners and telemetry tags. The full
+     * error (with `.stack`) is preserved on the `mcp-server-discovery-failed`
+     * event's `error` field.
+     */
     error?: string;
+    /**
+     * Structured failure projection. Mirrors the SDK's `McpServerErrorDetail`
+     * shape so consumers can route on category / code / retriable. Populated
+     * alongside `error`.
+     */
+    errorDetail?: McpServerErrorDetail;
     ready: Promise<void>;
     settled: boolean;
     tools: ToolsInput;
@@ -112,10 +147,18 @@ 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`.
@@ -127,6 +170,9 @@ export declare class MastraHarness implements MastraAgentHarness {
      * - 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).
      */
     shutdown(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
@@ -165,6 +211,18 @@ export declare class MastraHarness implements MastraAgentHarness {
      */
     getAgentIds(): Promise<string[]>;
     getMcpServerInfo(agentId: string): McpServerInfo[];
+    /**
+     * Eager implementation of {@link AgentHarness.reconnectMcpServer}: calls
+     * Mastra's `MCPClient.reconnectServer(name)` primitive, supersedes any
+     * in-flight discovery (replace-ready semantics — latest call wins), and
+     * awaits the new discovery before resolving.
+     *
+     * Programming errors (unknown agent / unknown server / disabled) reject.
+     * Transport / discovery failures are recorded on the per-server state
+     * (visible via {@link getMcpServerInfo}) and a `mcp-server-discovery-*`
+     * telemetry pair fires; the returned promise still resolves.
+     */
+    reconnectMcpServer(agentId: string, serverName: string): Promise<void>;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
@@ -215,6 +273,14 @@ export declare class MastraHarness implements MastraAgentHarness {
      *   User turns are treated as authoritative input.
      */
     compactThread(agentId: string, threadId: string): Promise<string>;
+    /**
+     * Best-effort wrapper around `destroyThread`: swallows the error so the
+     * caller's outer flow isn't aborted by a teardown blip, but logs the
+     * failure at warn level so a future regression in `destroyThread` is
+     * still observable. Used by `compactThread` on both the empty-source and
+     * non-empty paths.
+     */
+    private destroyThreadBestEffort;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
@@ -223,6 +289,10 @@ export declare class MastraHarness implements MastraAgentHarness {
      * - MUST return a `ChatStreamResult` with `textStream` and `eventStream`.
      * - On pre-stream rejection from `agent.stream()`, MUST re-throw without emitting telemetry —
      *   the SDK's chat-session boundary catches the rejection and emits `chat-stream-error`.
+     * - MUST install a per-run abort listener on `options.abortSignal` so that aborting
+     *   while a tool-approval is pending tears down the suspended Mastra run and clears
+     *   the thread's `ActiveRun` entry. See ARCHITECTURE.md → "Tool Approval Flow → Abort
+     *   during pending approval (#409)".
      */
     stream(agentId: string, threadId: string, message: string, options?: StreamOptions): Promise<ChatStreamResult>;
     /**
@@ -302,7 +372,6 @@ export declare class MastraHarness implements MastraAgentHarness {
      * directly.
      */
     private summarize;
-    private buildSummaryPrompt;
     /**
      * Two-pass summarization for transcripts above the char budget. The
      * transcript is split into roughly-equal chunks each ≤ MAX_TRANSCRIPT_CHARS,
@@ -317,9 +386,92 @@ export declare class MastraHarness implements MastraAgentHarness {
      */
     private splitIntoChunks;
     private getAgentStateOrThrow;
+    /**
+     * Synchronously flips `serverState.currentStatus` (no-op when the next
+     * status equals the current) and returns a closure that, when invoked,
+     * emits the corresponding `mcp-server-status-changed` event. Returns
+     * `undefined` when the status didn't change — the caller has nothing
+     * to emit.
+     *
+     * Splitting the state flip from the emit lets callers update internal
+     * state synchronously alongside `settled` (so a synchronous listener
+     * reading `getMcpServerInfo()` from inside the discovery telemetry
+     * callback observes the post-settle world per issue #373) while still
+     * deferring the status-change emit until after the discovery telemetry
+     * has fired.
+     *
+     * The returned closure swallows `DISPOSED` errors the same way the
+     * discovery emit sites do: background discovery callbacks can resolve
+     * after `shutdown()` has disposed the buses.
+     */
+    private prepareMcpStatusChange;
+    /**
+     * Runs MCP discovery for one server: emits the
+     * `mcp-server-discovery-started` / `…-completed` / `…-failed` telemetry
+     * triple and writes results into the corresponding entry in `serverStates`.
+     *
+     * The caller MUST `set()` the entry into `serverStates` either before
+     * calling this helper (the `createAgent` path constructs the entry
+     * synchronously after this returns the promise) or before any await
+     * boundary in the helper's chain — the chain reads back via
+     * `serverStates.get(serverName)!` to write `tools` / `error`. Both call
+     * sites today put the entry in place before the first microtask boundary.
+     *
+     * Errors observed during discovery are recorded on the entry's `error`
+     * field; the returned promise resolves either way (it only rejects when
+     * an aborted operation throws after we have already cleaned up). The
+     * `settled` flag is pinned BEFORE the terminal telemetry emit so a
+     * synchronous listener calling `getMcpServerInfo()` from inside the
+     * `mcp-server-discovery-{completed,failed}` callback observes the same
+     * world the event described — see issue #373.
+     */
+    private runMcpDiscovery;
     private toChatStreamResult;
+    /**
+     * Replace (or set) the active run for a thread, disposing any prior
+     * entry's per-run abort listener so the prior signal cannot fire on the
+     * new run.
+     */
+    private replaceActiveRun;
+    /**
+     * Remove the active run for a thread, disposing its per-run abort listener
+     * if present. Safe to call when no entry exists.
+     */
+    private removeActiveRun;
+    /**
+     * Wire `abortSignal.abort()` to tear down the suspended Mastra run for
+     * `threadId`. Returns a disposer that removes the listener; callers must
+     * invoke it whenever the entry is replaced or removed so a stale signal
+     * cannot abort an unrelated continuation run.
+     *
+     * Identity guard: the listener checks `agentState.activeRuns.get(threadId) === run`
+     * before calling `abortRunStream`, so a defensive race with another
+     * `stream()` call on the same thread cannot double-abort.
+     *
+     * Closes #409 — without this listener, aborting while a tool-approval is
+     * pending leaves Mastra's prepared run alive and `activeRuns[threadId]`
+     * pointing at a runId the consumer can no longer settle, so subsequent
+     * `approveToolCall` reaches Mastra and surfaces a confusing
+     * "could not find a suspended run" error instead of the SDK-level
+     * "no active run found" guard.
+     */
+    private installPerRunAbortListener;
+    private handlePerRunAbort;
     private getMemoryOrThrow;
     private agentResourceId;
+    /**
+     * Build a `RequestContext` carrying the thread + resource ids under the
+     * reserved keys Mastra reads when input processors (e.g. `ToolSearchProcessor`,
+     * `SkillSearchProcessor`) call `requestContext.get(MASTRA_THREAD_ID_KEY)`.
+     *
+     * `memory: { thread, resource }` populates Mastra's memory layer but is NOT
+     * propagated into the request context, so processors that key per-thread
+     * state by `MASTRA_THREAD_ID_KEY` would otherwise see `undefined` and fall
+     * back to the `'default'` bucket — folding every consumer thread into one.
+     * Surfacing the ids here lets `ToolSearchHandle.clearState(threadId)`
+     * actually match what the processor stored.
+     */
+    private buildRequestContext;
     private createEventStream;
     private readableStreamToAsyncGenerator;
     /**