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

package/README.md

@@ -46,14 +46,15 @@ Linux and macOS release the handle eagerly; the retry options are no-ops on thos
 
 ### Core
 
-| Export                                | Kind      | Description                                                                               |
-| ------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
-| `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.    |
-| `MastraModelConfigFactory`            | interface | Strategy for creating model configurations; injected into `MastraHarnessFactory`.         |
-| `ResolvedModelConfig`                 | type      | Return type of `MastraModelConfigFactory.create()` — wraps a `MastraModelConfig`.         |
-| `DefaultMastraModelConfigFactory`     | class     | Default factory using the Salesforce LLM Gateway (`SalesforceMastraModelGateway`).        |
-| `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).      |
-| `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`). |
+| Export                                | Kind      | Description                                                                                 |
+| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
+| `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.      |
+| `MastraHarnessFactoryConfig`          | interface | Configuration for `MastraHarnessFactory` (`modelConfigFactory?`, `toolApprovalTimeoutMs?`). |
+| `MastraModelConfigFactory`            | interface | Strategy for creating model configurations; injected into `MastraHarnessFactory`.           |
+| `ResolvedModelConfig`                 | type      | Return type of `MastraModelConfigFactory.create()` — wraps a `MastraModelConfig`.           |
+| `DefaultMastraModelConfigFactory`     | class     | Default factory using the Salesforce LLM Gateway (`SalesforceMastraModelGateway`).          |
+| `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).        |
+| `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`).   |
 
 ### Extension surface
 
@@ -151,19 +152,55 @@ for await (const event of result.eventStream) {
 }
 ```
 
+### Tool approval timeout
+
+When `requireToolApproval: true` is set on a `chat()` call, the harness suspends the workflow on each
+`tool-approval-request` and waits for the consumer to call `approveToolCall(...)` / `declineToolCall(...)` /
+`submitToolResult(...)`. To bound how long a pending approval can wait — for example, when a UI process crashes or a
+user walks away — the factory accepts a `toolApprovalTimeoutMs` option. It defaults to `600_000` (10 minutes) and
+matches the `ClaudeHarnessFactoryConfig` knob of the same name.
+
+```ts
+const harnessFactory = new MastraHarnessFactory({
+  toolApprovalTimeoutMs: 60_000, // auto-deny pending approvals after 60s
+});
+```
+
+When the timer fires, the harness aborts the suspended Mastra run, drops the `activeRuns` entry for the thread, and
+yields a synthetic terminal pair on the active `eventStream`:
+
+```ts
+{ type: 'error', error: Error('Tool approval timed out after 60000ms.'), code: 'tool-approval-timeout' }
+{ type: 'finish', finishReason: 'error' }
+```
+
+Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool reject with
+`no active run found for thread "<id>"`. The granularity is per thread — each suspended `ActiveRun` arms its own timer
+because Mastra suspends one tool approval at a time per thread; multi-tool turns get a fresh timer with each
+continuation. To observe the timeout, keep iterating the `eventStream` past the `tool-approval-request` event so the
+synthetic terminal pair lands in your loop:
+
+```ts
+for await (const event of result.eventStream) {
+  if (event.type === 'error' && event.code === 'tool-approval-timeout') {
+    // Pending approval was never answered.
+  }
+}
+```
+
 ### Using LLM Gateway Express
 
 ```ts
 import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
 import { MastraHarnessFactory, LLMGExpressMastraModelConfigFactory } from '@salesforce/sfdx-agent-harness-mastra';
 
-const harnessFactory = new MastraHarnessFactory(
-  new LLMGExpressMastraModelConfigFactory({
+const harnessFactory = new MastraHarnessFactory({
+  modelConfigFactory: new LLMGExpressMastraModelConfigFactory({
     apiKey: process.env.LLMG_EXPRESS_API_KEY!,
     baseUrl: process.env.LLMG_EXPRESS_BASE_URL!,
     modelId: 'claude-sonnet-4-20250514',
   }),
-);
+});
 
 const manager = await createAgentManager('/path/to/storage', harnessFactory);
 ```

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { MastraHarnessFactory } from './mastra-harness-factory.js';
+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, formatMcpToolName, } from './tool-search.js';
 export type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';

package/dist/mastra-harness-factory.d.ts

@@ -1,11 +1,28 @@
 import type { HarnessFactory } from '@salesforce/sfdx-agent-sdk';
 import { type MastraAgentHarness } from './mastra-harness.js';
 import type { MastraModelConfigFactory } from './model-config-factory.js';
+export interface MastraHarnessFactoryConfig {
+    /**
+     * Strategy for resolving the Mastra model configuration. Defaults to
+     * `DefaultMastraModelConfigFactory`, which targets the standard LLM
+     * Gateway path.
+     */
+    modelConfigFactory?: MastraModelConfigFactory;
+    /**
+     * How long to wait for a `requireToolApproval` consumer to call
+     * `approveToolCall` / `declineToolCall` before auto-denying via
+     * `agent.abortRunStream(...)` and yielding a synthetic `error`
+     * (`code: 'tool-approval-timeout'`) + `finish` (`finishReason: 'error'`)
+     * terminal pair. Defaults to `600_000` (10 minutes), matching
+     * `ClaudeHarnessFactoryConfig.toolApprovalTimeoutMs`.
+     */
+    toolApprovalTimeoutMs?: number;
+}
 /** Mastra-backed factory for creating AgentHarness instances. */
 export declare class MastraHarnessFactory implements HarnessFactory<MastraAgentHarness> {
-    private readonly modelConfigFactory?;
+    private readonly config;
     readonly harnessId = "mastra";
     readonly protocolVersion = 1;
-    constructor(modelConfigFactory?: MastraModelConfigFactory | undefined);
+    constructor(config?: MastraHarnessFactoryConfig);
     create(storageRootFolder: string): Promise<MastraAgentHarness>;
 }

package/dist/mastra-harness-factory.js

@@ -3,16 +3,20 @@
  * See LICENSE.txt for license terms.
  */
 import { MastraHarness } from './mastra-harness.js';
+const DEFAULT_TOOL_APPROVAL_TIMEOUT_MS = 600_000;
 /** Mastra-backed factory for creating AgentHarness instances. */
 export class MastraHarnessFactory {
-    modelConfigFactory;
+    config;
     harnessId = 'mastra';
     protocolVersion = 1;
-    constructor(modelConfigFactory) {
-        this.modelConfigFactory = modelConfigFactory;
+    constructor(config = {}) {
+        this.config = config;
     }
     async create(storageRootFolder) {
-        return new MastraHarness(storageRootFolder, this.modelConfigFactory);
+        return new MastraHarness(storageRootFolder, {
+            modelConfigFactory: this.config.modelConfigFactory,
+            toolApprovalTimeoutMs: this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS,
+        });
     }
 }
 //# sourceMappingURL=mastra-harness-factory.js.map

package/dist/mastra-harness.d.ts

@@ -33,6 +33,31 @@ interface ActiveRun {
     runId: string;
     fullStream: ReadableStream<ChunkType>;
     disposeAbortListener?: () => void;
+    /**
+     * Clears the per-run tool-approval timeout (`setTimeout` handle wrapped in
+     * a closure). Invoked at every site that overwrites or removes the entry,
+     * mirroring `disposeAbortListener` semantics. See ARCHITECTURE.md →
+     * "Approval timeout (#408)".
+     */
+    disposeTimeout?: () => void;
+    /**
+     * Whether the originating `stream()` call was made with
+     * `requireToolApproval: true`. Carried forward across continuations
+     * (`approveToolCall`, `declineToolCall`, `submitToolResult`) so each
+     * continuation arms a fresh approval-timeout timer.
+     */
+    requireToolApproval?: boolean;
+    /**
+     * Set by `handleApprovalTimeout` and read by `createEventStream`'s
+     * `Promise.race` against the next `reader.read()`. When the race
+     * resolves to this signal, the generator yields the synthetic `error`
+     * (`code: 'tool-approval-timeout'`) + `finish` terminal pair without
+     * needing the underlying `fullStream` to close — Mastra's
+     * `abortRunStream` is a silent no-op for suspended runs, so we cannot
+     * count on the stream closing on its own.
+     */
+    timedOutSignal?: Promise<'timed-out'>;
+    timedOut?: boolean;
 }
 /**
  * Per-server MCP state. Each enabled server gets its own MCPClient and
@@ -134,11 +159,20 @@ export type MastraAgentHarness = WithAgentConfig<AgentHarness & {
         };
     };
 }, MastraAgentConfig>;
+/**
+ * Construction options for {@link MastraHarness}. Internal — consumers
+ * configure the harness via {@link MastraHarnessFactory} (which forwards a
+ * curated subset of these fields). Tests pass stubs (`clock`, `idGenerator`)
+ * directly.
+ */
+export interface MastraHarnessOptions {
+    modelConfigFactory?: MastraModelConfigFactory;
+    clock?: Clock;
+    idGenerator?: UniqueIDGenerator;
+    toolApprovalTimeoutMs?: number;
+}
 export declare class MastraHarness implements MastraAgentHarness {
     private readonly storageRootFolder;
-    private readonly modelConfigFactory;
-    private readonly clock;
-    private readonly idGenerator;
     readonly harnessId = "mastra";
     readonly protocolVersion = 1;
     /**
@@ -164,7 +198,11 @@ export declare class MastraHarness implements MastraAgentHarness {
      * SDK never reads this; consumers reach through `manager.extensions.mastra`.
      */
     readonly extensions: MastraAgentHarness['extensions'];
-    constructor(storageRootFolder: string, modelConfigFactory?: MastraModelConfigFactory, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    private readonly modelConfigFactory;
+    private readonly clock;
+    private readonly idGenerator;
+    private readonly toolApprovalTimeoutMs;
+    constructor(storageRootFolder: string, opts?: MastraHarnessOptions);
     /**
      * @requirements
      * - MUST disconnect the mcpClient for every active agent before clearing state.
@@ -429,13 +467,13 @@ export declare class MastraHarness implements MastraAgentHarness {
     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.
+     * entry's per-run abort listener and approval-timeout timer so neither
+     * can 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.
+     * and approval-timeout timer if present. Safe to call when no entry exists.
      */
     private removeActiveRun;
     /**
@@ -457,6 +495,46 @@ export declare class MastraHarness implements MastraAgentHarness {
      */
     private installPerRunAbortListener;
     private handlePerRunAbort;
+    /**
+     * Arm a one-shot tool-approval timer for `run`. Returns a disposer that
+     * clears the timer; callers must invoke it whenever the entry is replaced
+     * or removed so a stale timer cannot fire on an unrelated continuation.
+     *
+     * Closes #408 — without this, an unanswered `requireToolApproval: true`
+     * request leaves Mastra's prepared run alive and `activeRuns[threadId]`
+     * pointing at a `runId` the consumer never settles, so the suspended
+     * workflow leaks until the manager shuts down. Mirrors the
+     * `ClaudeStreamBroker` per-pending-approval timer in
+     * `@salesforce/sfdx-agent-harness-claude`; the granularity differs (per
+     * thread here, per `toolCallId` there) because Mastra suspends one tool
+     * approval at a time per thread.
+     */
+    private installApprovalTimeout;
+    /**
+     * Fire-once handler invoked when `installApprovalTimeout`'s timer expires
+     * before the consumer calls `approveToolCall` / `declineToolCall` /
+     * `submitToolResult`.
+     *
+     * Identity guard: if the entry has already been replaced or removed
+     * (consumer settled in flight, abort fired, agent destroyed), no-op. Same
+     * race posture as `handlePerRunAbort` and as Claude's
+     * `ClaudeStreamBroker.handleApprovalTimeout` early-return.
+     *
+     * On fire: flag the run, drop the entry from `activeRuns` (so subsequent
+     * `approveToolCall` etc. surface the SDK-level "no active run found"
+     * guard), call `agent.abortRunStream(runId)` (best-effort — for a
+     * suspended run this is a no-op since the prepared-runs registry has
+     * already released it), and resolve the `timedOutSignal` so
+     * `createEventStream`'s `Promise.race` against the next `reader.read()`
+     * picks the timeout signal and yields the synthetic `error`
+     * (`code: 'tool-approval-timeout'`) + `finish` terminal pair. The #409
+     * abort path doesn't need a side signal because Mastra closes the
+     * fullStream natively when the caller's `abortSignal` fires; the timeout
+     * path has no such signal and Mastra's `abortRunStream` is a silent
+     * no-op for suspended runs, so the generator must learn about the
+     * timeout out-of-band.
+     */
+    private handleApprovalTimeout;
     private getMemoryOrThrow;
     private agentResourceId;
     /**
@@ -472,6 +550,14 @@ export declare class MastraHarness implements MastraAgentHarness {
      * actually match what the processor stored.
      */
     private buildRequestContext;
+    /**
+     * Resolve when `signal` aborts; resolves immediately if already aborted.
+     * Used in `createEventStream`'s suspended-wait branch so the generator
+     * wakes on `controller.abort()` even though the underlying `fullStream`
+     * has already returned `done` (Mastra closes the stream right after
+     * `tool-call-approval`).
+     */
+    private waitForAbort;
     private createEventStream;
     private readableStreamToAsyncGenerator;
     /**

package/dist/mastra-harness.js

@@ -302,9 +302,6 @@ function mapMastraToolsToMcpToolInfo(tools, logBus) {
 }
 export class MastraHarness {
     storageRootFolder;
-    modelConfigFactory;
-    clock;
-    idGenerator;
     harnessId = 'mastra';
     protocolVersion = 1;
     /**
@@ -343,11 +340,16 @@ export class MastraHarness {
             },
         },
     };
-    constructor(storageRootFolder, modelConfigFactory = new DefaultMastraModelConfigFactory(), clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    modelConfigFactory;
+    clock;
+    idGenerator;
+    toolApprovalTimeoutMs;
+    constructor(storageRootFolder, opts = {}) {
         this.storageRootFolder = storageRootFolder;
-        this.modelConfigFactory = modelConfigFactory;
-        this.clock = clock;
-        this.idGenerator = idGenerator;
+        this.modelConfigFactory = opts.modelConfigFactory ?? new DefaultMastraModelConfigFactory();
+        this.clock = opts.clock ?? new RealClock();
+        this.idGenerator = opts.idGenerator ?? new UUIDGenerator();
+        this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs ?? 600_000;
         // Construct the libsql Client ourselves and inject it into LibSQLStore
         // via the `{ client }` constructor form. We keep our own reference so
         // shutdown() can call client.close() — Mastra's shutdown() does not
@@ -403,8 +405,10 @@ export class MastraHarness {
      */
     async shutdown() {
         await Promise.all([...this.activeAgents.values()].map(async (state) => {
-            for (const run of state.activeRuns.values())
+            for (const run of state.activeRuns.values()) {
                 run.disposeAbortListener?.();
+                run.disposeTimeout?.();
+            }
             state.activeRuns.clear();
             await Promise.allSettled(Array.from(state.mcpServers.values()).map(async (s) => {
                 await s.ready.catch(() => undefined);
@@ -417,6 +421,25 @@ export class MastraHarness {
         // Settle the constructor's eager init before closing — see the
         // `storageReady` field comment for the why.
         await this.storageReady;
+        // Fold the WAL into the main DB and switch journal_mode=DELETE
+        // so SQLite unlinks the -wal/-shm sidecars on close. Without this,
+        // Windows holds the sidecars open well past `client.close()` and
+        // racing `fs.rm` calls (e.g. vitest's per-test cleanup) crash the
+        // worker. Mirrors the fix Mastra shipped on `LibSQLStore.close()`
+        // in `@mastra/libsql@1.12.0-alpha.0`. Replace this block with a
+        // call to `storage.close()` once that release ships stable — see
+        // https://github.com/forcedotcom/agentic-dx/issues/475.
+        try {
+            await this.libsqlClient.execute('PRAGMA wal_checkpoint(TRUNCATE);');
+            await this.libsqlClient.execute('PRAGMA journal_mode=DELETE;');
+        }
+        catch (err) {
+            // Best-effort: still close even if checkpoint fails (e.g. the
+            // client was already closed by a prior shutdown path).
+            this.buses.getLogBus()?.warn('libsql WAL checkpoint failed before close', {
+                error: getErrorMessage(err),
+            });
+        }
         this.libsqlClient.close();
         this.buses.dispose();
     }
@@ -601,8 +624,10 @@ export class MastraHarness {
      */
     async destroyAgent(agentId) {
         const state = this.getAgentStateOrThrow(agentId);
-        for (const run of state.activeRuns.values())
+        for (const run of state.activeRuns.values()) {
             run.disposeAbortListener?.();
+            run.disposeTimeout?.();
+        }
         state.activeRuns.clear();
         await Promise.allSettled(Array.from(state.mcpServers.values()).map(async (s) => {
             await s.ready.catch(() => undefined);
@@ -927,7 +952,7 @@ export class MastraHarness {
             abortSignal: options?.abortSignal,
             requireToolApproval: options?.requireToolApproval,
         });
-        return this.toChatStreamResult(agentState, threadId, output, options?.abortSignal);
+        return this.toChatStreamResult(agentState, threadId, output, options?.abortSignal, options?.requireToolApproval);
     }
     // ── Tool Execution ───────────────────────────────────────────────
     /**
@@ -952,6 +977,7 @@ export class MastraHarness {
         if (!activeRun) {
             throw new Error(`MastraHarness.submitToolResult(): no active run found for thread "${threadId}" on agent "${agentId}"`);
         }
+        const requireToolApproval = activeRun.requireToolApproval;
         await this.drainReadableStream(activeRun.fullStream);
         const output = await agentState.agent.resumeStream({ approved: true, result: toolResult.result, isError: toolResult.isError }, {
             runId: activeRun.runId,
@@ -962,7 +988,7 @@ export class MastraHarness {
             },
             requestContext: this.buildRequestContext(agentId, threadId),
         });
-        return this.toChatStreamResult(agentState, threadId, output);
+        return this.toChatStreamResult(agentState, threadId, output, undefined, requireToolApproval);
     }
     // ── Tool Approval ────────────────────────────────────────────────
     /**
@@ -990,6 +1016,7 @@ export class MastraHarness {
         if (!activeRun) {
             throw new Error(`MastraHarness.approveToolCall(): no active run found for thread "${threadId}" on agent "${agentId}"`);
         }
+        const requireToolApproval = activeRun.requireToolApproval;
         await this.drainReadableStream(activeRun.fullStream);
         const output = await agentState.agent.approveToolCall({
             runId: activeRun.runId,
@@ -1000,7 +1027,7 @@ export class MastraHarness {
             },
             requestContext: this.buildRequestContext(agentId, threadId),
         });
-        return this.toChatStreamResult(agentState, threadId, output);
+        return this.toChatStreamResult(agentState, threadId, output, undefined, requireToolApproval);
     }
     /**
      * @requirements
@@ -1022,6 +1049,7 @@ export class MastraHarness {
         if (!activeRun) {
             throw new Error(`MastraHarness.declineToolCall(): no active run found for thread "${threadId}" on agent "${agentId}"`);
         }
+        const requireToolApproval = activeRun.requireToolApproval;
         await this.drainReadableStream(activeRun.fullStream);
         const output = await agentState.agent.declineToolCall({
             runId: activeRun.runId,
@@ -1032,7 +1060,7 @@ export class MastraHarness {
             },
             requestContext: this.buildRequestContext(agentId, threadId),
         });
-        return this.toChatStreamResult(agentState, threadId, output);
+        return this.toChatStreamResult(agentState, threadId, output, undefined, requireToolApproval);
     }
     // ── Message History ──────────────────────────────────────────────
     /**
@@ -1330,40 +1358,53 @@ export class MastraHarness {
             }
         });
     }
-    toChatStreamResult(agentState, threadId, output, abortSignal) {
+    toChatStreamResult(agentState, threadId, output, abortSignal, requireToolApproval) {
         // Entries are keyed by threadId so each thread holds at most one entry.
         // Stale entries are overwritten here on the next stream; explicit cleanup
         // happens via destroyThread() / destroyAgent() / shutdown(). Proactive
         // removal on stream completion is not safe because the suspend/resume
         // flow (submitToolResult, approveToolCall) needs the entry after the stream closes.
         const newRun = { runId: output.runId, fullStream: output.fullStream };
+        if (requireToolApproval) {
+            newRun.requireToolApproval = true;
+            // Deferred promise the generator races against reader.read() so the
+            // timer wins without depending on the stream closing — Mastra's
+            // abortRunStream is a silent no-op for suspended runs.
+            let resolveTimedOut;
+            newRun.timedOutSignal = new Promise((resolve) => {
+                resolveTimedOut = resolve;
+            });
+            newRun.disposeTimeout = this.installApprovalTimeout(agentState, threadId, newRun, resolveTimedOut);
+        }
         if (abortSignal) {
             newRun.disposeAbortListener = this.installPerRunAbortListener(agentState, threadId, newRun, abortSignal);
         }
         this.replaceActiveRun(agentState, threadId, newRun);
         const adapter = new MastraEventAdapter(this.buses.getLogBus());
         return {
-            eventStream: this.createEventStream(output.fullStream, adapter, agentState, abortSignal),
+            eventStream: this.createEventStream(output.fullStream, adapter, agentState, newRun, abortSignal),
             textStream: this.readableStreamToAsyncGenerator(output.textStream),
         };
     }
     /**
      * 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.
+     * entry's per-run abort listener and approval-timeout timer so neither
+     * can fire on the new run.
      */
     replaceActiveRun(agentState, threadId, run) {
         const prior = agentState.activeRuns.get(threadId);
         prior?.disposeAbortListener?.();
+        prior?.disposeTimeout?.();
         agentState.activeRuns.set(threadId, run);
     }
     /**
      * Remove the active run for a thread, disposing its per-run abort listener
-     * if present. Safe to call when no entry exists.
+     * and approval-timeout timer if present. Safe to call when no entry exists.
      */
     removeActiveRun(agentState, threadId) {
         const prior = agentState.activeRuns.get(threadId);
         prior?.disposeAbortListener?.();
+        prior?.disposeTimeout?.();
         agentState.activeRuns.delete(threadId);
     }
     /**
@@ -1413,6 +1454,7 @@ export class MastraHarness {
             // is responsible for its run.
             if (agentState.activeRuns.get(threadId) !== run)
                 return;
+            run.disposeTimeout?.();
             agentState.activeRuns.delete(threadId);
             agentState.agent.abortRunStream(run.runId);
         }
@@ -1430,6 +1472,63 @@ export class MastraHarness {
             }
         }
     }
+    /**
+     * Arm a one-shot tool-approval timer for `run`. Returns a disposer that
+     * clears the timer; callers must invoke it whenever the entry is replaced
+     * or removed so a stale timer cannot fire on an unrelated continuation.
+     *
+     * Closes #408 — without this, an unanswered `requireToolApproval: true`
+     * request leaves Mastra's prepared run alive and `activeRuns[threadId]`
+     * pointing at a `runId` the consumer never settles, so the suspended
+     * workflow leaks until the manager shuts down. Mirrors the
+     * `ClaudeStreamBroker` per-pending-approval timer in
+     * `@salesforce/sfdx-agent-harness-claude`; the granularity differs (per
+     * thread here, per `toolCallId` there) because Mastra suspends one tool
+     * approval at a time per thread.
+     */
+    installApprovalTimeout(agentState, threadId, run, signalTimedOut) {
+        const timer = setTimeout(() => this.handleApprovalTimeout(agentState, threadId, run, signalTimedOut), this.toolApprovalTimeoutMs);
+        return () => clearTimeout(timer);
+    }
+    /**
+     * Fire-once handler invoked when `installApprovalTimeout`'s timer expires
+     * before the consumer calls `approveToolCall` / `declineToolCall` /
+     * `submitToolResult`.
+     *
+     * Identity guard: if the entry has already been replaced or removed
+     * (consumer settled in flight, abort fired, agent destroyed), no-op. Same
+     * race posture as `handlePerRunAbort` and as Claude's
+     * `ClaudeStreamBroker.handleApprovalTimeout` early-return.
+     *
+     * On fire: flag the run, drop the entry from `activeRuns` (so subsequent
+     * `approveToolCall` etc. surface the SDK-level "no active run found"
+     * guard), call `agent.abortRunStream(runId)` (best-effort — for a
+     * suspended run this is a no-op since the prepared-runs registry has
+     * already released it), and resolve the `timedOutSignal` so
+     * `createEventStream`'s `Promise.race` against the next `reader.read()`
+     * picks the timeout signal and yields the synthetic `error`
+     * (`code: 'tool-approval-timeout'`) + `finish` terminal pair. The #409
+     * abort path doesn't need a side signal because Mastra closes the
+     * fullStream natively when the caller's `abortSignal` fires; the timeout
+     * path has no such signal and Mastra's `abortRunStream` is a silent
+     * no-op for suspended runs, so the generator must learn about the
+     * timeout out-of-band.
+     */
+    handleApprovalTimeout(agentState, threadId, run, signalTimedOut) {
+        if (agentState.activeRuns.get(threadId) !== run)
+            return;
+        run.timedOut = true;
+        agentState.activeRuns.delete(threadId);
+        try {
+            agentState.agent.abortRunStream(run.runId);
+        }
+        catch (err) {
+            this.buses
+                .getLogBus()
+                ?.warn(`Failed to abort suspended run "${run.runId}" on tool-approval timeout for thread "${threadId}": ${getErrorMessage(err)}`, { threadId, runId: run.runId, timeoutMs: this.toolApprovalTimeoutMs }, err instanceof Error ? err : new Error(String(err)));
+        }
+        signalTimedOut('timed-out');
+    }
     async getMemoryOrThrow(agentId) {
         const agentState = this.getAgentStateOrThrow(agentId);
         const memory = await agentState.agent.getMemory();
@@ -1459,7 +1558,21 @@ export class MastraHarness {
         ctx.set(MASTRA_RESOURCE_ID_KEY, this.agentResourceId(agentId));
         return ctx;
     }
-    async *createEventStream(fullStream, adapter, agentState, abortSignal) {
+    /**
+     * Resolve when `signal` aborts; resolves immediately if already aborted.
+     * Used in `createEventStream`'s suspended-wait branch so the generator
+     * wakes on `controller.abort()` even though the underlying `fullStream`
+     * has already returned `done` (Mastra closes the stream right after
+     * `tool-call-approval`).
+     */
+    waitForAbort(signal) {
+        if (signal.aborted)
+            return Promise.resolve('aborted');
+        return new Promise((resolve) => {
+            signal.addEventListener('abort', () => resolve('aborted'), { once: true });
+        });
+    }
+    async *createEventStream(fullStream, adapter, agentState, run, abortSignal) {
         // Tracks whether the consumer has observed a terminal event already.
         // Either `finish` (natural completion) or any `error` event counts —
         // the SDK's `wrapEventStream` treats any error as terminal and
@@ -1468,33 +1581,122 @@ export class MastraHarness {
         // per turn. The narrower "only abort-coded errors count" predicate
         // would mis-fire on tripwire/regular errors that race the abort.
         let sawTerminal = false;
-        for await (const chunk of this.readableStreamToAsyncGenerator(fullStream)) {
-            const event = adapter.toChatEvent(chunk);
-            if (!event)
-                continue;
-            if (event.type === 'finish' || event.type === 'error') {
-                sawTerminal = true;
-            }
-            if (isEnrichableToolEvent(event)) {
-                const toolName = event.type === 'tool-approval-request' ? event.toolCall.toolName : event.toolName;
-                const metadata = lookupMcpToolMetadata(agentState, toolName);
-                if (metadata) {
-                    yield {
-                        ...event,
-                        serverName: metadata.serverName,
-                        ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
-                    };
+        // Tracks whether the consumer is currently sitting on a yielded
+        // `tool-approval-request` with no settle/abort/timeout decision yet.
+        // When Mastra suspends a run it closes the underlying `fullStream`
+        // immediately after the `tool-call-approval` chunk — `reader.read()`
+        // returns `{ done: true }` synchronously. If we treated that as
+        // "stream completed", the timeout timer would never get a chance to
+        // fire (the generator would exit before the timer's macrotask), and
+        // the consumer's `for await` would terminate with no terminal event.
+        // While suspended, wait on the per-run timeout signal instead — the
+        // timer is the only thing that can move the run forward.
+        let approvalPending = false;
+        const reader = fullStream.getReader();
+        // Wraps a `read()` so `Promise.race` can disambiguate which side won.
+        // The timeout signal resolves to the literal `'timed-out'`; a `read()`
+        // rejection is reported as `{ kind: 'rejected', err }` and the loop
+        // body decides how to interpret it: silence ONLY when `run.timedOut`
+        // is set (the lock-release race after the timer fires is benign);
+        // anything else is a real upstream error that must propagate so the
+        // SDK's `wrapEventStream` boundary can synthesize the terminal pair.
+        const readChunk = () => reader.read().then((r) => (r.done ? { kind: 'done' } : { kind: 'chunk', value: r.value }), (err) => ({ kind: 'rejected', err }));
+        try {
+            while (true) {
+                let outcome;
+                if (approvalPending) {
+                    // Stream is suspended on a tool-approval. The underlying
+                    // `fullStream` returns `done` immediately after Mastra
+                    // emits `tool-call-approval` (snapshot is persisted, then
+                    // the stream closes), so we cannot rely on it for further
+                    // signal — wait for whichever side decides the run's fate
+                    // (timeout fire or caller's abortSignal). Continued reads
+                    // would loop returning `done` and burn CPU. If neither
+                    // signal is present (e.g. consumer set `requireToolApproval:
+                    // true` without an `abortSignal` on a harness with no
+                    // timeout), fall through to a plain `readChunk` — the
+                    // generator will exit cleanly on `done` and the consumer
+                    // gets no terminal, matching the pre-fix behavior for
+                    // that misconfiguration.
+                    const waiters = [];
+                    if (run.timedOutSignal)
+                        waiters.push(run.timedOutSignal);
+                    if (abortSignal)
+                        waiters.push(this.waitForAbort(abortSignal));
+                    outcome = waiters.length > 0 ? await Promise.race(waiters) : await readChunk();
+                }
+                else {
+                    // Race the next read against the per-run timeout signal so
+                    // the generator wakes up immediately when the timer fires —
+                    // Mastra's `abortRunStream` is a silent no-op for suspended
+                    // runs, so the underlying stream may never close on its
+                    // own.
+                    outcome = run.timedOutSignal
+                        ? await Promise.race([readChunk(), run.timedOutSignal])
+                        : await readChunk();
+                }
+                if (outcome === 'timed-out')
+                    break;
+                if (outcome === 'aborted')
+                    break;
+                if (outcome.kind === 'done')
+                    break;
+                if (outcome.kind === 'rejected') {
+                    // Only the lock-release race after the timer fires should
+                    // be silenced; a real upstream error must surface so
+                    // `wrapEventStream` can emit `chat-stream-error` + finish.
+                    if (run.timedOut)
+                        break;
+                    throw outcome.err instanceof Error ? outcome.err : new Error(String(outcome.err));
+                }
+                const event = adapter.toChatEvent(outcome.value);
+                if (!event)
                     continue;
+                if (event.type === 'finish' || event.type === 'error') {
+                    sawTerminal = true;
+                    // Stream is on its way out — disposing the timer here
+                    // prevents the 10-min armed-but-unused fire on streams
+                    // that completed naturally without ever pending an
+                    // approval. See ARCHITECTURE.md → "Approval timeout (#408)".
+                    run.disposeTimeout?.();
                 }
+                if (event.type === 'tool-approval-request') {
+                    // Mastra suspends the run after this chunk; the
+                    // underlying `fullStream` will return `done` next read.
+                    // Switch to "wait for timeout" mode so we don't exit the
+                    // generator before the timer can fire.
+                    approvalPending = true;
+                }
+                if (isEnrichableToolEvent(event)) {
+                    const toolName = event.type === 'tool-approval-request' ? event.toolCall.toolName : event.toolName;
+                    const metadata = lookupMcpToolMetadata(agentState, toolName);
+                    if (metadata) {
+                        yield {
+                            ...event,
+                            serverName: metadata.serverName,
+                            ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
+                        };
+                        continue;
+                    }
+                }
+                yield event;
             }
-            yield event;
         }
-        // The fullStream closed. If abort fired during a suspended-run path
-        // (consumer aborted while a tool-approval was pending), Mastra
-        // releases the prepared run silently — the fullStream just ends with
-        // no `abort` chunk — so synthesize the terminal pair the SDK
-        // invariant requires. See ARCHITECTURE.md → "Tool Approval Flow →
-        // Abort during pending approval (#409)".
+        finally {
+            reader.releaseLock();
+        }
+        // The fullStream closed. If a suspended-run terminal cause fired —
+        // consumer never answered a `requireToolApproval` request (#408) or
+        // consumer aborted while a tool-approval was pending (#409) — Mastra
+        // releases the prepared run silently, so the fullStream just ends
+        // with no terminal chunk. Synthesize the terminal pair the SDK
+        // invariant requires. See ARCHITECTURE.md → "Tool Approval Flow".
+        //
+        // Ordering: check `run.timedOut` BEFORE `abortSignal?.aborted` because
+        // `handleApprovalTimeout` calls `agent.abortRunStream(...)`, which on
+        // some Mastra paths flips the abort signal. Pinning timeout-first
+        // means the consumer's `error.code` is the most informative one
+        // (`'tool-approval-timeout'` rather than `'abort'`).
         //
         // Adapter-coupling note: this gate depends on `MastraEventAdapter`
         // not yielding a `finish` chunk between `tool-call-approval` and
@@ -1504,7 +1706,15 @@ export class MastraHarness {
         // would set `sawTerminal` early and silently suppress the synth.
         // If that lands, switch the predicate to track only the terminal
         // `finish` (e.g. via a per-stream "suspended" flag).
-        if (!sawTerminal && abortSignal?.aborted) {
+        if (!sawTerminal && run.timedOut) {
+            yield {
+                type: 'error',
+                error: new Error(`Tool approval timed out after ${this.toolApprovalTimeoutMs}ms.`),
+                code: 'tool-approval-timeout',
+            };
+            yield { type: 'finish', finishReason: 'error' };
+        }
+        else if (!sawTerminal && abortSignal?.aborted) {
             yield {
                 type: 'error',
                 error: new DOMException('The stream was aborted.', 'AbortError'),

package/dist/mcp-config-mapper.d.ts

@@ -13,7 +13,10 @@ export declare function hasEnabledServers(config: MCPConfiguration | undefined):
  * - `MCPStdioServerConfig` maps to a Mastra stdio definition (`command`, `args`, `env`).
  * - `MCPRemoteServerConfig` maps to a Mastra HTTP definition (`url` as a `URL` object,
  *   `headers` forwarded via `requestInit`).
- * - Per-server `timeout` is preserved when provided.
+ * - Per-server `timeout` is preserved when provided. For remote servers it is bound to both
+ *   Mastra's `timeout` (post-connect request lifetime) and `connectTimeout` (initial transport
+ *   handshake) so the configured value covers both phases — Mastra's hardcoded 3s
+ *   `connectTimeout` default would otherwise abort cold-start handshakes before `timeout` applied.
  * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
  *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
  */

package/dist/mcp-config-mapper.js

@@ -19,7 +19,10 @@ export function hasEnabledServers(config) {
  * - `MCPStdioServerConfig` maps to a Mastra stdio definition (`command`, `args`, `env`).
  * - `MCPRemoteServerConfig` maps to a Mastra HTTP definition (`url` as a `URL` object,
  *   `headers` forwarded via `requestInit`).
- * - Per-server `timeout` is preserved when provided.
+ * - Per-server `timeout` is preserved when provided. For remote servers it is bound to both
+ *   Mastra's `timeout` (post-connect request lifetime) and `connectTimeout` (initial transport
+ *   handshake) so the configured value covers both phases — Mastra's hardcoded 3s
+ *   `connectTimeout` default would otherwise abort cold-start handshakes before `timeout` applied.
  * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
  *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
  */
@@ -46,7 +49,10 @@ export function mapToMastraMCPServers(config, orgJwt) {
                     requestInit: { headers: serverConfig.headers },
                 }),
                 ...(orgJwt && { fetch: createAuthFetch(serverConfig.url, orgJwt, serverConfig.headers) }),
-                ...(serverConfig.timeout !== undefined && { timeout: serverConfig.timeout }),
+                ...(serverConfig.timeout !== undefined && {
+                    timeout: serverConfig.timeout,
+                    connectTimeout: serverConfig.timeout,
+                }),
             };
             result[name] = def;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -35,14 +35,14 @@
     "@mastra/memory": "^1.19.0",
     "@mastra/schema-compat": "^1.2.10",
     "@salesforce/agentic-common": "0.6.0",
-    "@salesforce/llm-gateway-sdk": "0.7.0"
+    "@salesforce/llm-gateway-sdk": "0.8.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.10.0"
+    "@salesforce/sfdx-agent-sdk": "0.12.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.10.0",
+    "@salesforce/sfdx-agent-sdk": "0.12.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",