@salesforce/sfdx-agent-harness-mastra 0.67.0 → 0.68.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.68.0] - 2026-09-02
+
+### Fixes
+- **harness-mastra**: per-read idle-read timeout on gateway stream @W-24078276@ ([#791](https://github.com/forcedotcom/agentic-dx/pull/791))
+
 ## [0.67.0] - 2026-09-02
 
 ### Fixes

package/dist/mastra-harness.d.ts

@@ -230,6 +230,13 @@ export interface MastraHarnessOptions {
     clock?: Clock;
     idGenerator?: UniqueIDGenerator;
     toolApprovalTimeoutMs?: number;
+    /**
+     * Per-read idle timeout (ms) for the LLM gateway response body. Defaults to
+     * {@link DEFAULT_IDLE_READ_TIMEOUT_MS}. The internal test seam for the
+     * idle-read watchdog (6b, W-24078276) — no factory/consumer knob, matching
+     * `resumeRpcTimeoutMs`'s posture (6c). `<= 0` disables the watchdog.
+     */
+    idleReadTimeoutMs?: number;
     /**
      * Inner fetch the harness threads into every in-process HTTP call site
      * (LLM gateway language-model builders + MCP remote transports). Defaults
@@ -286,6 +293,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly clock;
     private readonly idGenerator;
     private readonly toolApprovalTimeoutMs;
+    private readonly idleReadTimeoutMs;
     private readonly innerFetch;
     private readonly wireObserverAbortController;
     private readonly languageModelBuilders?;

package/dist/mastra-harness.js

@@ -172,6 +172,24 @@ const MAX_TRANSCRIPT_CHARS = 400_000;
  * like deploys. Per-server `timeout` in MCPServerConfig still overrides this.
  */
 const DEFAULT_MCP_TIMEOUT_MS = 600_000;
+/**
+ * Default per-read idle timeout (ms) for the gateway response body (6b,
+ * W-24078276) — see the "gateway stream has a per-read idle-read timeout"
+ * Critical Invariant. It is a per-read watchdog (resets on every chunk), NOT a
+ * wall-clock cap, so a healthy long-running turn making byte-level progress is
+ * never bounded; it fires only on genuinely zero forward progress.
+ *
+ * 2 minutes, backed by an orgfarm-e2e measurement of the SDK-consumed body on
+ * the primary Bedrock-Anthropic path: the gateway emits `message_start`
+ * immediately and streams frames continuously, so the MAX observed silent gap
+ * was ~1.8s even on an 837 KB generation AND on a ~500k-token prefill (Opus 4.8,
+ * 1M window) — TTFB was ~0-1ms in every case. 120s therefore clears the worst
+ * observed forward-progress gap by ~65x while still being ~15x tighter than the
+ * service layer's 30-min net (6a). Injectable via
+ * {@link MastraHarnessOptions.idleReadTimeoutMs} (the test seam; no
+ * factory/consumer knob — same posture as `resumeRpcTimeoutMs`, 6c).
+ */
+const DEFAULT_IDLE_READ_TIMEOUT_MS = 120_000;
 /**
  * Build the `Map<namespacedName, ToolSource>` index `resolveAlwaysActive`
  * needs to match `{ serverName }` / `{ serverName, toolName }` / `{ toolName }`
@@ -446,6 +464,7 @@ export class MastraHarness {
     clock;
     idGenerator;
     toolApprovalTimeoutMs;
+    idleReadTimeoutMs;
     innerFetch;
     wireObserverAbortController = new AbortController();
     languageModelBuilders;
@@ -454,6 +473,7 @@ export class MastraHarness {
         this.clock = opts.clock ?? new RealClock();
         this.idGenerator = opts.idGenerator ?? new UUIDGenerator();
         this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs ?? 600_000;
+        this.idleReadTimeoutMs = opts.idleReadTimeoutMs ?? DEFAULT_IDLE_READ_TIMEOUT_MS;
         this.innerFetch = opts.innerFetch ?? globalThis.fetch;
         this.languageModelBuilders = opts.languageModelBuilders;
         this.storage = new LibSQLStore({
@@ -1474,6 +1494,7 @@ export class MastraHarness {
             }
         };
         const innerFetch = this.innerFetch;
+        const idleReadTimeoutMs = this.idleReadTimeoutMs;
         const wireHooks = {
             emitWireCommunication,
             getModel: () => getInfo().nativeModelId,
@@ -1486,22 +1507,28 @@ export class MastraHarness {
         switch (initial.providerHint) {
             case 'bedrock-anthropic':
                 // Salesforce LLM Gateway's `/invoke-with-response-stream` (Bedrock pass-through).
-                return buildAnthropicLanguageModel({ getInfo, logBus, wireHooks, innerFetch });
+                return buildAnthropicLanguageModel({ getInfo, logBus, wireHooks, innerFetch, idleReadTimeoutMs });
             case 'anthropic':
                 // Direct Anthropic Messages API (`api.anthropic.com/v1/messages`) —
                 // different wire shape (`x-api-key` auth, body without `anthropic_version`).
-                return buildAnthropicDirectLanguageModel({ getInfo, logBus, wireHooks, innerFetch });
+                return buildAnthropicDirectLanguageModel({ getInfo, logBus, wireHooks, innerFetch, idleReadTimeoutMs });
             case 'openai-responses':
             case 'openai':
                 // OpenAI Responses API. Salesforce LLM Gateway's `/responses` pass-through
                 // for `'openai-responses'`; `api.openai.com/v1/responses` for `'openai'` direct.
                 // Same wire shape; the only difference is the `baseUrl` the resolver supplies.
-                return buildOpenAILanguageModel({ getInfo, logBus, wireHooks, innerFetch });
+                return buildOpenAILanguageModel({ getInfo, logBus, wireHooks, innerFetch, idleReadTimeoutMs });
             case 'openai-compatible':
                 // OpenAI-compatible Chat Completions API (LLMG Express, LiteLLM, etc.).
                 // Different wire shape from Responses — `/v1/chat/completions` with
                 // `choices[0].delta` streaming events.
-                return buildOpenAIChatCompletionsLanguageModel({ getInfo, logBus, wireHooks, innerFetch });
+                return buildOpenAIChatCompletionsLanguageModel({
+                    getInfo,
+                    logBus,
+                    wireHooks,
+                    innerFetch,
+                    idleReadTimeoutMs,
+                });
             default: {
                 // Consult the injected builders map before throwing. This is the
                 // extension point for consumer-registered wire shapes (e.g. a temporary

package/dist/pass-through-anthropic.d.ts

@@ -29,6 +29,8 @@ export declare function buildAnthropicLanguageModel(opts: {
      * don't need to thread it.
      */
     innerFetch?: typeof fetch;
+    /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
+    idleReadTimeoutMs?: number;
 }): LanguageModelV3;
 /**
  * Builds the in-process `LanguageModelV3` impl for direct-Anthropic API access
@@ -56,6 +58,8 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
     wireHooks?: GatewayFetchWireHooks;
     /** See {@link buildAnthropicLanguageModel} `innerFetch`. */
     innerFetch?: typeof fetch;
+    /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
+    idleReadTimeoutMs?: number;
 }): LanguageModelV3;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into Anthropic's Messages API shape

package/dist/pass-through-anthropic.js

@@ -21,7 +21,7 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * the next request.
  */
 export function buildAnthropicLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
     const initialInfo = getInfo();
     const ctx = {
         getInfo,
@@ -34,7 +34,7 @@ export function buildAnthropicLanguageModel(opts) {
             // The fetch wrapper re-evaluates `getHeaders()` on every outbound call —
             // JWT rotation, premium-rate-limit gate flips, BYOK provider rotation
             // all land on the next request without rebuilding the bridge.
-            fetch: createGatewayFetch(() => info.getHeaders(), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch),
+            fetch: createGatewayFetch(() => info.getHeaders(), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch, idleReadTimeoutMs, logBus),
         }),
     };
     return {
@@ -70,7 +70,7 @@ export function buildAnthropicLanguageModel(opts) {
  * language model.
  */
 export function buildAnthropicDirectLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
     const initialInfo = getInfo();
     const ctx = {
         getInfo,
@@ -88,7 +88,7 @@ export function buildAnthropicDirectLanguageModel(opts) {
         new Anthropic({
             apiKey: 'anthropic-direct-resolver-managed',
             baseURL: info.baseUrl,
-            fetch: createGatewayFetch(() => translateBearerToXApiKey(info), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch),
+            fetch: createGatewayFetch(() => translateBearerToXApiKey(info), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch, idleReadTimeoutMs, logBus),
         }),
     };
     return {

package/dist/pass-through-openai-chat-completions.d.ts

@@ -30,6 +30,8 @@ export declare function buildOpenAIChatCompletionsLanguageModel(opts: {
     wireHooks?: GatewayFetchWireHooks;
     /** See `buildAnthropicLanguageModel` `innerFetch`. */
     innerFetch?: typeof fetch;
+    /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
+    idleReadTimeoutMs?: number;
 }): LanguageModelV3;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into the OpenAI Chat Completions

package/dist/pass-through-openai-chat-completions.js

@@ -26,9 +26,9 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * without rebuilding the language model.
  */
 export function buildOpenAIChatCompletionsLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
     const initialInfo = getInfo();
-    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch };
+    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs };
     return {
         specificationVersion: 'v3',
         provider: 'openai-compatible-chat-completions-pass-through',
@@ -56,7 +56,7 @@ async function buildRequest(ctx, options) {
         // request. The SDK still wants a non-empty `apiKey` at construction;
         // an opaque sentinel keeps it from reading `process.env['OPENAI_API_KEY']`.
         apiKey: 'openai-compatible-resolver-managed',
-        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks, ctx.innerFetch),
+        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks, ctx.innerFetch, ctx.idleReadTimeoutMs, ctx.logBus),
     });
     const messages = translatePromptToChatCompletions(options.prompt);
     const tools = translateToolsToChatCompletions(options);

package/dist/pass-through-openai.d.ts

@@ -22,6 +22,8 @@ export declare function buildOpenAILanguageModel(opts: {
     wireHooks?: GatewayFetchWireHooks;
     /** See `buildAnthropicLanguageModel` `innerFetch`. */
     innerFetch?: typeof fetch;
+    /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
+    idleReadTimeoutMs?: number;
 }): LanguageModelV3;
 /**
  * Translates a V3 `LanguageModelV3Prompt` into OpenAI's Responses input shape:

package/dist/pass-through-openai.js

@@ -18,9 +18,9 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * next request.
  */
 export function buildOpenAILanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
     const initialInfo = getInfo();
-    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch };
+    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs };
     return {
         specificationVersion: 'v3',
         provider: 'salesforce-llm-gateway-pass-through-openai',
@@ -56,7 +56,7 @@ async function buildOpenAIRequest(ctx, options) {
         // Re-evaluates `getHeaders()` per outbound call so JWT rotation /
         // premium-rate-limit gate flips / BYOK provider rotation land on the
         // next request without rebuilding this bridge.
-        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks, ctx.innerFetch),
+        fetch: createGatewayFetch(() => info.getHeaders(), wireHooks, ctx.innerFetch, ctx.idleReadTimeoutMs, ctx.logBus),
     });
     const { input, instructions } = translatePromptToOpenAI(options.prompt);
     const tools = translateToolsToOpenAI(options);

package/dist/stream-errors.d.ts

@@ -27,6 +27,32 @@ export declare class NetworkStreamError extends ClassifiedStreamError {
     readonly code: "network-error";
     constructor(cause: Error);
 }
+/**
+ * The gateway response body went idle — no bytes for `idleMs` with no forward
+ * progress — so the harness's per-read idle watchdog tore the connection down
+ * (6b, spike agent-offline-failure-modes, W-24078276). A half-open socket (TCP
+ * open, no bytes, no FIN/RST) would otherwise wedge the turn forever; this error
+ * releases it as a transport fault.
+ *
+ * It classifies as {@link NETWORK_ERROR_CODE} — an idle half-open socket is the
+ * same "the transport dropped, a retry could recover" class `NetworkStreamError`
+ * covers (downstream retry/backoff keys on the code, 8e). Unlike the Anthropic
+ * path's `NetworkStreamError`, this carries the code DIRECTLY on a
+ * `ClassifiedStreamError` subtype, so it surfaces `network-error` uniformly on
+ * every provider path: the Anthropic iterator catch enqueues it unchanged
+ * (`recognizeBedrockValidationError` returns `undefined` and it is NOT re-wrapped),
+ * and the OpenAI catches enqueue it raw — in both cases `MastraEventAdapter`
+ * copies `.code` via {@link isClassifiedStreamError}. It is deliberately NOT
+ * matched by {@link isStreamTransportError} (that would double-wrap it in a
+ * `NetworkStreamError` on the Anthropic path for no gain). Its `name` is NOT
+ * `AbortError`, so the provider SDK `Stream` iterators do not swallow it as a
+ * user cancel (which would resurface the false-success wedge, 8a).
+ */
+export declare class IdleReadTimeoutError extends ClassifiedStreamError {
+    readonly name = "IdleReadTimeoutError";
+    readonly code: "network-error";
+    constructor(idleMs: number);
+}
 /** A stream that closed cleanly with no recognized content/usage/terminal event — the "false-success" case (8a); `empty-stream`. */
 export declare class EmptyStreamError extends ClassifiedStreamError {
     readonly name = "EmptyStreamError";

package/dist/stream-errors.js

@@ -33,6 +33,35 @@ export class NetworkStreamError extends ClassifiedStreamError {
         super(cause.message, { cause });
     }
 }
+/**
+ * The gateway response body went idle — no bytes for `idleMs` with no forward
+ * progress — so the harness's per-read idle watchdog tore the connection down
+ * (6b, spike agent-offline-failure-modes, W-24078276). A half-open socket (TCP
+ * open, no bytes, no FIN/RST) would otherwise wedge the turn forever; this error
+ * releases it as a transport fault.
+ *
+ * It classifies as {@link NETWORK_ERROR_CODE} — an idle half-open socket is the
+ * same "the transport dropped, a retry could recover" class `NetworkStreamError`
+ * covers (downstream retry/backoff keys on the code, 8e). Unlike the Anthropic
+ * path's `NetworkStreamError`, this carries the code DIRECTLY on a
+ * `ClassifiedStreamError` subtype, so it surfaces `network-error` uniformly on
+ * every provider path: the Anthropic iterator catch enqueues it unchanged
+ * (`recognizeBedrockValidationError` returns `undefined` and it is NOT re-wrapped),
+ * and the OpenAI catches enqueue it raw — in both cases `MastraEventAdapter`
+ * copies `.code` via {@link isClassifiedStreamError}. It is deliberately NOT
+ * matched by {@link isStreamTransportError} (that would double-wrap it in a
+ * `NetworkStreamError` on the Anthropic path for no gain). Its `name` is NOT
+ * `AbortError`, so the provider SDK `Stream` iterators do not swallow it as a
+ * user cancel (which would resurface the false-success wedge, 8a).
+ */
+export class IdleReadTimeoutError extends ClassifiedStreamError {
+    name = 'IdleReadTimeoutError';
+    code = NETWORK_ERROR_CODE;
+    constructor(idleMs) {
+        super(`LLM Gateway stream idle for ${idleMs}ms with no forward progress (no bytes received); ` +
+            'treating as a transport fault and tearing down the connection.');
+    }
+}
 /** A stream that closed cleanly with no recognized content/usage/terminal event — the "false-success" case (8a); `empty-stream`. */
 export class EmptyStreamError extends ClassifiedStreamError {
     name = 'EmptyStreamError';

package/dist/v3-stream-mapping.d.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelV3FinishReason, LanguageModelV3StreamPart, LanguageModelV3ToolResultOutput, LanguageModelV3Usage } from '@ai-sdk/provider';
-import { type Clock, type UniqueIDGenerator } from '@salesforce/agentic-common';
+import { type Clock, type LogBus, type UniqueIDGenerator } from '@salesforce/agentic-common';
 import type { Model } from '@salesforce/sfdx-agent-sdk';
 /**
  * Shared V3 helpers for the Mastra harness's `LanguageModelV3` implementations
@@ -230,7 +230,29 @@ export type GatewayFetchWireHooks = {
  * <n> }` so wire-communication captures don't blow the consumer's log file
  * budget.
  */
-export declare function createGatewayFetch(getHeaders: () => Record<string, string> | Promise<Record<string, string>>, wireHooks?: GatewayFetchWireHooks, innerFetch?: typeof fetch): typeof fetch;
+export declare function createGatewayFetch(getHeaders: () => Record<string, string> | Promise<Record<string, string>>, wireHooks?: GatewayFetchWireHooks, innerFetch?: typeof fetch, 
+/**
+ * Per-read idle timeout (ms) for the response body handed to the provider
+ * SDK. When set (`> 0`), the SDK-facing body is wrapped in a watchdog that
+ * resets on every chunk and, after `idleReadTimeoutMs` of ZERO bytes, tears
+ * the connection down and errors the stream with a classified
+ * {@link IdleReadTimeoutError} (`network-error`) — so a half-open socket
+ * (TCP open, no bytes, no FIN/RST) fails the turn loudly instead of hanging
+ * forever (6b, W-24078276). This is a true per-read idle watchdog, NOT a
+ * wall-clock cap: a healthy long-running turn that keeps making byte-level
+ * progress (Anthropic streams `ping`/thinking deltas during long
+ * operations) is never capped. Omitted / `0` disables the watchdog (the
+ * default for the many `createGatewayFetch` unit tests that resolve
+ * immediately); the harness always supplies a value in production.
+ */
+idleReadTimeoutMs?: number, 
+/**
+ * Optional log bus. When the idle watchdog fires, it emits a `warn` here so
+ * the field can distinguish a real half-open-socket teardown from a healthy
+ * turn clipped by a too-tight timeout (a false positive). Silent in steady
+ * state — nothing is logged unless the watchdog actually trips.
+ */
+logBus?: LogBus): typeof fetch;
 /**
  * The `WireCommunicationEvent` shape from `@salesforce/sfdx-agent-sdk` minus the
  * harness-injected fields. Kept structural so this module doesn't import

package/dist/v3-stream-mapping.js

@@ -4,6 +4,7 @@
  */
 import { RealClock, UUIDGenerator } from '@salesforce/agentic-common';
 import { EventStreamCodec } from '@smithy/eventstream-codec';
+import { IdleReadTimeoutError } from './stream-errors.js';
 /**
  * Shared V3 helpers for the Mastra harness's `LanguageModelV3` implementations
  * — stream-shaping primitives, finish-reason / usage mappers, prompt-translation
@@ -265,7 +266,29 @@ export function mapOpenAIUsage(usage) {
  * <n> }` so wire-communication captures don't blow the consumer's log file
  * budget.
  */
-export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThis.fetch) {
+export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThis.fetch, 
+/**
+ * Per-read idle timeout (ms) for the response body handed to the provider
+ * SDK. When set (`> 0`), the SDK-facing body is wrapped in a watchdog that
+ * resets on every chunk and, after `idleReadTimeoutMs` of ZERO bytes, tears
+ * the connection down and errors the stream with a classified
+ * {@link IdleReadTimeoutError} (`network-error`) — so a half-open socket
+ * (TCP open, no bytes, no FIN/RST) fails the turn loudly instead of hanging
+ * forever (6b, W-24078276). This is a true per-read idle watchdog, NOT a
+ * wall-clock cap: a healthy long-running turn that keeps making byte-level
+ * progress (Anthropic streams `ping`/thinking deltas during long
+ * operations) is never capped. Omitted / `0` disables the watchdog (the
+ * default for the many `createGatewayFetch` unit tests that resolve
+ * immediately); the harness always supplies a value in production.
+ */
+idleReadTimeoutMs, 
+/**
+ * Optional log bus. When the idle watchdog fires, it emits a `warn` here so
+ * the field can distinguish a real half-open-socket teardown from a healthy
+ * turn clipped by a too-tight timeout (a false positive). Silent in steady
+ * state — nothing is logged unless the watchdog actually trips.
+ */
+logBus) {
     return async (input, init) => {
         const resolved = await getHeaders();
         // Per WHATWG Fetch, `init.headers` is `HeadersInit = Headers | Record<string, string> | [string, string][]`.
@@ -278,9 +301,15 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
         for (const [k, v] of Object.entries(resolved)) {
             finalHeaders.set(k, v); // resolver wins on conflict — same semantics as the prior spread merge.
         }
-        const finalInit = { ...init, headers: finalHeaders };
+        // Link the caller's AbortSignal (finding 05 / W-23988781 wires the turn's
+        // signal into fetch) with an internal idle-timeout controller, so an idle
+        // expiry aborts the underlying fetch — tearing down the socket AND both
+        // tee branches — while a caller abort still works unchanged.
+        const idle = makeIdleReadGuard(init?.signal, idleReadTimeoutMs, logBus);
+        const finalInit = { ...init, headers: finalHeaders, ...(idle ? { signal: idle.signal } : {}) };
         if (!wireHooks) {
-            return innerFetch(input, finalInit);
+            const response = await innerFetch(input, finalInit);
+            return idle ? idle.wrapResponse(response) : response;
         }
         const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
         const method = (finalInit.method ?? 'GET').toUpperCase();
@@ -317,7 +346,11 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
             };
             if (response.body === null || !(wireHooks.hasWireCommunicationSubscribers?.() ?? true)) {
                 emitResponse();
-                return response;
+                // Common production path: wire subscribers are opt-in and usually
+                // absent, so the watchdog MUST wrap here too — not only in the tee
+                // branch below — or a half-open socket wedges the turn whenever
+                // nobody is observing wire communication.
+                return idle ? idle.wrapResponse(response) : response;
             }
             const [observerBody, sdkBody] = response.body.tee();
             void observeResponseBody({
@@ -329,7 +362,7 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
                 clock,
                 onComplete: emitResponse,
             }).catch(() => undefined);
-            return new Response(sdkBody, response);
+            return new Response(idle ? idle.wrap(sdkBody) : sdkBody, response);
         }
         catch (error) {
             wireHooks.emitWireCommunication({
@@ -345,6 +378,113 @@ export function createGatewayFetch(getHeaders, wireHooks, innerFetch = globalThi
         }
     };
 }
+/**
+ * Builds the per-request idle-read guard, or `undefined` when the watchdog is
+ * disabled (`idleReadTimeoutMs` unset / `<= 0`).
+ *
+ * The returned `signal` links the caller's abort signal with an internal
+ * controller and is passed to the underlying `fetch`, so aborting on idle-timeout
+ * tears down the live socket (and, in the wire-hooks path, both tee branches at
+ * once). `wrap` wraps the SDK-facing body in the watchdog stream; `wrapResponse`
+ * is the convenience form for the non-tee return sites (bodyless responses pass
+ * through untouched).
+ */
+function makeIdleReadGuard(callerSignal, idleReadTimeoutMs, logBus) {
+    if (idleReadTimeoutMs === undefined || idleReadTimeoutMs <= 0)
+        return undefined;
+    const controller = new AbortController();
+    const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    const wrap = (body) => wrapWithIdleReadTimeout(body, idleReadTimeoutMs, () => {
+        // Field signal for the one failure mode this watchdog can cause — a
+        // false-positive teardown of a healthy-but-silent turn. Silent unless
+        // it actually fires.
+        logBus?.warn(`LLM Gateway stream idle for ${idleReadTimeoutMs}ms with no forward progress (no bytes received); ` +
+            'tearing down the connection as a network-error.', { idleReadTimeoutMs });
+        // Abort the fetch so undici tears down the connection; the wrapped
+        // stream is errored separately with the non-abort IdleReadTimeoutError
+        // the SDK actually observes (an AbortError would be swallowed).
+        controller.abort(new IdleReadTimeoutError(idleReadTimeoutMs));
+    });
+    return {
+        signal,
+        wrap,
+        wrapResponse: (response) => (response.body ? new Response(wrap(response.body), response) : response),
+    };
+}
+/**
+ * Wraps a response body in a passthrough stream that resets an idle timer on
+ * every chunk (and arms it up front to cover time-to-first-byte). After
+ * `idleMs` of ZERO bytes it calls `onTimeout` (tears the socket down) and errors
+ * the wrapped stream with {@link IdleReadTimeoutError} — the error the provider
+ * SDK's body reader surfaces, classified as `network-error`. A normal
+ * completion, a downstream cancel, or a source error all clear the timer, so no
+ * timer outlives the read. The timer is `unref`'d where supported so a stray
+ * armed watchdog never keeps the process alive.
+ */
+function wrapWithIdleReadTimeout(source, idleMs, onTimeout) {
+    const reader = source.getReader();
+    let timer;
+    let timedOut = false;
+    const clearIdle = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    return new ReadableStream({
+        start(controller) {
+            const arm = () => {
+                clearIdle();
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    const err = new IdleReadTimeoutError(idleMs);
+                    onTimeout();
+                    try {
+                        controller.error(err);
+                    }
+                    catch {
+                        // Already closed / errored — nothing to do.
+                    }
+                    void reader.cancel(err).catch(() => undefined);
+                }, idleMs);
+                timer.unref?.();
+            };
+            arm();
+            const pump = async () => {
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (timedOut)
+                            return; // the timer already errored the stream
+                        if (done) {
+                            clearIdle();
+                            controller.close();
+                            return;
+                        }
+                        arm(); // reset the idle window on every chunk
+                        controller.enqueue(value);
+                    }
+                }
+                catch (err) {
+                    if (timedOut)
+                        return;
+                    clearIdle();
+                    try {
+                        controller.error(err);
+                    }
+                    catch {
+                        // Already closed / errored.
+                    }
+                }
+            };
+            void pump();
+        },
+        cancel(reason) {
+            clearIdle();
+            return reader.cancel(reason);
+        },
+    });
+}
 const TRACE_BODY_BYTE_BUDGET = 256 * 1024;
 /**
  * Observes only the owned tee branch. Cancellation intentionally does not await

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.67.0",
+  "version": "0.68.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.68.0"
+    "@salesforce/sfdx-agent-sdk": "0.69.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.68.0",
+    "@salesforce/sfdx-agent-sdk": "0.69.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",