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

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: classify context-window overflow as a typed CONTEXT_LENGTH_EXCEEDED error @W-24074717@ ([#788](https://github.com/forcedotcom/agentic-dx/pull/788))
+
 ## [0.65.0] - 2026-09-02
 
 _No changes — released alongside dependent packages._

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/dist/mastra-event-adapter.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { CONTEXT_LENGTH_EXCEEDED_CODE, createContextLengthExceededError } from '@salesforce/sfdx-agent-sdk';
 import { isClassifiedStreamError } from './stream-errors.js';
 /**
  * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.
@@ -153,10 +154,19 @@ export class MastraEventAdapter {
             }
             case 'error': {
                 const rawError = chunk.payload.error;
+                const code = isClassifiedStreamError(rawError) ? rawError.code : undefined;
+                const baseError = rawError instanceof Error ? rawError : new Error(String(rawError));
+                // Context-window overflow is the one classified error we upgrade to
+                // the SDK's typed `AgentSDKError(CONTEXT_LENGTH_EXCEEDED)` so the
+                // in-stream signal matches the pre-flight throw and carries the
+                // actionable message; the raw ValidationStreamError rides on `.cause`.
+                if (code === CONTEXT_LENGTH_EXCEEDED_CODE) {
+                    return { type: 'error', error: createContextLengthExceededError(baseError), code };
+                }
                 return {
                     type: 'error',
-                    error: rawError instanceof Error ? rawError : new Error(String(rawError)),
-                    ...(isClassifiedStreamError(rawError) ? { code: rawError.code } : {}),
+                    error: baseError,
+                    ...(code !== undefined ? { code } : {}),
                 };
             }
             case 'tripwire':

package/dist/stream-errors.d.ts

@@ -1,6 +1,13 @@
 export declare const NETWORK_ERROR_CODE: 'network-error';
 export declare const EMPTY_STREAM_ERROR_CODE: 'empty-stream';
-export declare const CONTEXT_OVERFLOW_ERROR_CODE: 'context-window-exceeded';
+/**
+ * The overflow `ErrorEvent.code`. Aliased to the SDK-owned
+ * {@link CONTEXT_LENGTH_EXCEEDED_CODE} so this harness and the cross-harness
+ * contract can never drift on the wire value; the adapter upgrades a
+ * ValidationStreamError carrying this code to the typed
+ * `AgentSDKError(CONTEXT_LENGTH_EXCEEDED)` before it reaches the consumer.
+ */
+export declare const CONTEXT_OVERFLOW_ERROR_CODE: "context-window-exceeded";
 export declare const VALIDATION_ERROR_CODE: 'validation-error';
 export declare const GATEWAY_RESPONSE_ERROR_CODE: 'gateway-error';
 /**

package/dist/stream-errors.js

@@ -2,9 +2,17 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { CONTEXT_LENGTH_EXCEEDED_CODE, isContextWindowOverflowMessage } from '@salesforce/sfdx-agent-sdk';
 export const NETWORK_ERROR_CODE = 'network-error';
 export const EMPTY_STREAM_ERROR_CODE = 'empty-stream';
-export const CONTEXT_OVERFLOW_ERROR_CODE = 'context-window-exceeded';
+/**
+ * The overflow `ErrorEvent.code`. Aliased to the SDK-owned
+ * {@link CONTEXT_LENGTH_EXCEEDED_CODE} so this harness and the cross-harness
+ * contract can never drift on the wire value; the adapter upgrades a
+ * ValidationStreamError carrying this code to the typed
+ * `AgentSDKError(CONTEXT_LENGTH_EXCEEDED)` before it reaches the consumer.
+ */
+export const CONTEXT_OVERFLOW_ERROR_CODE = CONTEXT_LENGTH_EXCEEDED_CODE;
 export const VALIDATION_ERROR_CODE = 'validation-error';
 export const GATEWAY_RESPONSE_ERROR_CODE = 'gateway-error';
 /**
@@ -109,12 +117,6 @@ export function isStreamTransportError(error) {
     }
     return false;
 }
-/**
- * Messages Bedrock / Anthropic use for a context-window overflow — the subset of
- * `ValidationException` worth surfacing with the more specific
- * `context-window-exceeded` code (ties into spike item 04).
- */
-const CONTEXT_OVERFLOW_PATTERNS = /input is too long|prompt is too long|too many (input )?tokens|maximum context length|context (window|length)|exceed(s|ed)? (the )?(maximum )?context/i;
 /**
  * Recognizes the Bedrock `ValidationException` shape (8d), walking the `cause`
  * chain and duck-typing the several ways `@anthropic-ai/bedrock-sdk` /
@@ -131,7 +133,7 @@ export function recognizeBedrockValidationError(error) {
         seen.add(current);
         const message = extractValidationExceptionMessage(current);
         if (message !== undefined) {
-            const code = CONTEXT_OVERFLOW_PATTERNS.test(message) ? CONTEXT_OVERFLOW_ERROR_CODE : VALIDATION_ERROR_CODE;
+            const code = isContextWindowOverflowMessage(message) ? CONTEXT_OVERFLOW_ERROR_CODE : VALIDATION_ERROR_CODE;
             return new ValidationStreamError(message, code);
         }
         current = current.cause;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.65.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.66.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.66.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",