@salesforce/sfdx-agent-harness-mastra 0.66.0 → 0.67.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 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.67.0] - 2026-09-02
+
+### Fixes
+- **harness-mastra**: wall-clock timeout on outbound resume RPC @W-24026787@ ([#790](https://github.com/forcedotcom/agentic-dx/pull/790))
+
 ## [0.66.0] - 2026-09-02
 
 ### Features

package/dist/mastra-approval-coordinator.d.ts

@@ -35,6 +35,22 @@ export interface MastraApprovalCoordinatorOptions {
     };
     requestContext: RequestContext;
     toolApprovalTimeoutMs: number;
+    /**
+     * Wall-clock bound on the outbound resume RPC — `agent.approveToolCall(...)`
+     * / `agent.declineToolCall(...)` — NOT on the resumed turn's work (6c, spike
+     * agent-offline-failure-modes, W-24026787). Those calls return promptly with
+     * a fresh `fullStream` handle; the model's actual generation (which can be a
+     * long deployment or a slow "thinking" turn) streams through that handle,
+     * pumped separately with no timeout — so a healthy resume is never capped.
+     * This bound only fires when the establishment round-trip itself hangs and
+     * never hands back a stream: after a human decision the "waiting for a human"
+     * timer is already cancelled and the session is `busy`, so on plain-REST no
+     * idle timer or auto-decline sweep is left to recover it. On timeout the
+     * coordinator routes through the shared `teardown('timeout', …)` path so the
+     * sink still gets a terminal error+finish and the session is released rather
+     * than wedged. Defaults to {@link DEFAULT_RESUME_RPC_TIMEOUT_MS}.
+     */
+    resumeRpcTimeoutMs?: number;
     /**
      * Per-tool approval-decision callback (Phase 2a). When defined, gating is
      * **active**: the harness passed `requireToolApproval: true` to Mastra so
@@ -159,6 +175,7 @@ export declare class MastraApprovalCoordinator {
     private readonly memory;
     private readonly requestContext;
     private readonly toolApprovalTimeoutMs;
+    private readonly resumeRpcTimeoutMs;
     private readonly lookupPolicy?;
     private readonly batchApprovals;
     private readonly consumerToolNames;

package/dist/mastra-approval-coordinator.js

@@ -23,6 +23,10 @@ function pickIdWithDecision(pendingIds, decisions) {
     return undefined;
 }
 const POLICY_DENIED_RESULT_TEXT = 'Denied by tool policy.';
+/** Default {@link MastraApprovalCoordinatorOptions.resumeRpcTimeoutMs} — 5 minutes. */
+const DEFAULT_RESUME_RPC_TIMEOUT_MS = 300_000;
+/** Race sentinel: the resume RPC establishment exceeded {@link DEFAULT_RESUME_RPC_TIMEOUT_MS}. */
+const RESUME_TIMEOUT = 'resume-timeout';
 /**
  * Per-`(agentId, threadId)` coordinator that subsumes the pre-#529
  * `MastraStreamBroker` + `activeRuns` pair into one object owning a single
@@ -65,6 +69,7 @@ export class MastraApprovalCoordinator {
     memory;
     requestContext;
     toolApprovalTimeoutMs;
+    resumeRpcTimeoutMs;
     lookupPolicy;
     batchApprovals;
     consumerToolNames;
@@ -170,6 +175,7 @@ export class MastraApprovalCoordinator {
         this.memory = opts.memory;
         this.requestContext = opts.requestContext;
         this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs;
+        this.resumeRpcTimeoutMs = opts.resumeRpcTimeoutMs ?? DEFAULT_RESUME_RPC_TIMEOUT_MS;
         this.lookupPolicy = opts.lookupPolicy;
         this.batchApprovals = opts.batchApprovals ?? false;
         this.consumerToolNames = opts.consumerToolNames;
@@ -684,42 +690,95 @@ export class MastraApprovalCoordinator {
      * pushed) or the new `fullStream` to pump next.
      */
     async driveResumeReturning(toolCallId, decision) {
+        // Kick off the resume RPC. See `resumeRpcTimeoutMs` for why the bound
+        // below is on this handshake only, never the streamed work.
+        const resume = decision.kind === 'approve'
+            ? this.agent.approveToolCall({
+                runId: this.currentRunId,
+                toolCallId,
+                memory: this.memory,
+                requestContext: this.requestContext,
+            })
+            : this.agent.declineToolCall({
+                runId: this.currentRunId,
+                toolCallId,
+                memory: this.memory,
+                requestContext: this.requestContext,
+                ...(decision.modelMessage ? { reason: decision.modelMessage } : {}),
+            });
+        // 6c (W-24026787): bound the handshake with a wall-clock timer. See
+        // `resumeRpcTimeoutMs` for why this is the only recovery backstop left
+        // at this point on plain-REST. Race the RPC against the timer; whichever
+        // settles first wins and the timer is always cleared so the win path
+        // never leaves a stray timer to double-signal.
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(RESUME_TIMEOUT), this.resumeRpcTimeoutMs);
+        });
+        let raced;
         try {
-            const output = decision.kind === 'approve'
-                ? await this.agent.approveToolCall({
-                    runId: this.currentRunId,
-                    toolCallId,
-                    memory: this.memory,
-                    requestContext: this.requestContext,
-                })
-                : await this.agent.declineToolCall({
-                    runId: this.currentRunId,
-                    toolCallId,
-                    memory: this.memory,
-                    requestContext: this.requestContext,
-                    ...(decision.modelMessage ? { reason: decision.modelMessage } : {}),
-                });
-            // Post-await guard: abort/dispose may have fired during the
-            // round-trip. Release the new run if so.
-            if (this.aborted || this.disposed) {
+            raced = await Promise.race([resume, timeout]);
+        }
+        catch (err) {
+            // The resume RPC rejected outright. Route through teardown so
+            // siblings in `pendingSuspendIds` settle as auto-resolved rather
+            // than silently orphaning.
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.teardown('pump-error', error, 'pump-error');
+            return 'done';
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (raced === RESUME_TIMEOUT) {
+            // Release a belatedly-established run on EVERY timeout path — this
+            // must sit ABOVE the aborted/disposed/timedOut guard below. This
+            // resume timer is a local, not in `approvalTimers`, so `teardown`'s
+            // `cancelAllTimers` can't cancel it: a `POST /cancel` during a hung
+            // handshake ends the sink but does NOT short-circuit this timer, so
+            // it still fires ~resumeRpcTimeoutMs later, hits the guard, and
+            // returns — and if the hung RPC then resolves, nothing else would
+            // release its run. Attaching here keeps the release on that
+            // abort/dispose-then-late-resolve edge (mirrors the abort/dispose
+            // post-await guard below). The RPC is never used to drive another
+            // stream — the turn is over; a late rejection is a no-op (also
+            // already consumed by the race).
+            void resume.then((out) => {
                 try {
-                    this.agent.abortRunStream(output.runId);
+                    this.agent.abortRunStream(out.runId);
                 }
                 catch {
                     /* best-effort */
                 }
+            }, () => {
+                /* late rejection: already consumed by the race */
+            });
+            // abort/dispose/another timeout may have already won and ended the
+            // sink — if so, nothing more to do (the release above still ran).
+            if (this.aborted || this.disposed || this.timedOut)
                 return 'done';
-            }
-            this.currentRunId = output.runId;
-            return output.fullStream;
+            this.timedOut = true;
+            // Route through the SAME teardown path abort/dispose/approval-timeout
+            // use, so the single-terminal invariant holds and the session is
+            // released. `teardown`'s sink pushes no-op once the sink has ended,
+            // so this can't double-signal a turn that already terminated.
+            this.teardown('timeout', new Error(`Tool resume RPC timed out after ${this.resumeRpcTimeoutMs}ms for tool call "${toolCallId}".`), RESUME_TIMEOUT);
+            return 'done';
         }
-        catch (err) {
-            // Route through teardown so siblings in `pendingSuspendIds`
-            // settle as auto-resolved rather than silently orphaning.
-            const error = err instanceof Error ? err : new Error(String(err));
-            this.teardown('pump-error', error, 'pump-error');
+        const output = raced;
+        // Post-await guard: abort/dispose may have fired during the round-trip.
+        // Release the new run if so.
+        if (this.aborted || this.disposed) {
+            try {
+                this.agent.abortRunStream(output.runId);
+            }
+            catch {
+                /* best-effort */
+            }
             return 'done';
         }
+        this.currentRunId = output.runId;
+        return output.fullStream;
     }
     awaitContinuation() {
         return new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -42,12 +42,12 @@
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.67.0"
+    "@salesforce/sfdx-agent-sdk": "0.68.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.67.0",
+    "@salesforce/sfdx-agent-sdk": "0.68.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",