@salesforce/sfdx-agent-harness-mastra 0.61.0 → 0.63.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.63.0] - 2026-09-02
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: reject concurrent turns with a typed SESSION_BUSY error @W-24044572@ ([#783](https://github.com/forcedotcom/agentic-dx/pull/783))
+
+## [0.62.0] - 2026-09-02
+
+### Fixes
+- **harness-mastra**: classify empty/opaque gateway stream failures @W-24026850@ @W-24027340@ ([#782](https://github.com/forcedotcom/agentic-dx/pull/782))
+
 ## [0.61.0] - 2026-09-01
 
 ### Fixes

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

@@ -261,6 +261,18 @@ export declare class MastraApprovalCoordinator {
     private timedOut;
     constructor(opts: MastraApprovalCoordinatorOptions);
     initialSink(): GenSink<ChatEvent>;
+    /**
+     * True once this turn has reached a terminal event — a natural `finish`
+     * pushed by the pump, or the synthetic `error` + `finish('error')` pair a
+     * `teardown` (abort / dispose / timeout / pump-error) emits. Both end the
+     * single per-turn sink, so `initial.isEnded()` is the authoritative "this
+     * turn is over" signal. A coordinator still pumping — including one PARKED on
+     * a `tool-approval-request` or a consumer-tool `submitToolResult` — has not
+     * ended its sink and is therefore NOT settled. `MastraHarness.stream()` reads
+     * this to reject a concurrent turn with `SESSION_BUSY` (a still-active
+     * coordinator) versus safely replace a settled one.
+     */
+    isSettled(): boolean;
     /**
      * Mastra's current run id. The harness's MCP-progress dispatcher uses
      * this to filter incoming `notifications/progress` to the coordinator

package/dist/mastra-approval-coordinator.js

@@ -184,6 +184,20 @@ export class MastraApprovalCoordinator {
     initialSink() {
         return this.initial;
     }
+    /**
+     * True once this turn has reached a terminal event — a natural `finish`
+     * pushed by the pump, or the synthetic `error` + `finish('error')` pair a
+     * `teardown` (abort / dispose / timeout / pump-error) emits. Both end the
+     * single per-turn sink, so `initial.isEnded()` is the authoritative "this
+     * turn is over" signal. A coordinator still pumping — including one PARKED on
+     * a `tool-approval-request` or a consumer-tool `submitToolResult` — has not
+     * ended its sink and is therefore NOT settled. `MastraHarness.stream()` reads
+     * this to reject a concurrent turn with `SESSION_BUSY` (a still-active
+     * coordinator) versus safely replace a settled one.
+     */
+    isSettled() {
+        return this.initial.isEnded();
+    }
     /**
      * Mastra's current run id. The harness's MCP-progress dispatcher uses
      * this to filter incoming `notifications/progress` to the coordinator

package/dist/mastra-event-adapter.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { isNetworkStreamError } from './stream-errors.js';
+import { isClassifiedStreamError } from './stream-errors.js';
 /**
  * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.
  *
@@ -156,7 +156,7 @@ export class MastraEventAdapter {
                 return {
                     type: 'error',
                     error: rawError instanceof Error ? rawError : new Error(String(rawError)),
-                    ...(isNetworkStreamError(rawError) ? { code: rawError.code } : {}),
+                    ...(isClassifiedStreamError(rawError) ? { code: rawError.code } : {}),
                 };
             }
             case 'tripwire':

package/dist/mastra-harness.js

@@ -1618,12 +1618,20 @@ export class MastraHarness {
         // round-trip per tool call.
         const { lookupPolicy, batchApprovals } = this.buildPolicyGate(agentState, options);
         const gatingActive = lookupPolicy !== undefined;
-        // Dispose any coordinator the prior turn on this thread allocated.
-        // Without this a stale coordinator from the prior turn would still
-        // route settle calls and accumulate listeners. Mode-flip safe: the
-        // new coordinator is constructed fresh below regardless of the new
-        // turn's mode.
+        // Concurrency guard (spike agent-offline-failure-modes #10, W-24044572):
+        // reject a second turn on a thread whose prior turn is still ACTIVE with a
+        // typed `SESSION_BUSY` error, instead of silently disposing the first
+        // (which surfaced to the first consumer as a spurious `DISPOSED` — a
+        // "silent lost turn"). A coordinator is active until its sink ends (natural
+        // finish or teardown), so one still pumping — including one parked on an
+        // approval / consumer-tool result — blocks a new turn. An already-settled
+        // coordinator (finished or errored) is safe to dispose-and-replace, so the
+        // idempotent settling of an already-terminal turn is preserved.
         const priorCoordinator = agentState.coordinators.get(threadId);
+        if (priorCoordinator && !priorCoordinator.isSettled()) {
+            throw new AgentSDKError(`A turn is already in progress for thread "${threadId}" on agent "${agentId}". ` +
+                'Only one turn may run at a time per thread; await the in-flight turn before starting another.', AgentSDKErrorType.SESSION_BUSY);
+        }
         if (priorCoordinator) {
             priorCoordinator.dispose();
             agentState.coordinators.delete(threadId);

package/dist/pass-through-anthropic.js

@@ -4,7 +4,7 @@
  */
 import { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 import Anthropic from '@anthropic-ai/sdk';
-import { NetworkStreamError, isStreamTransportError } from './stream-errors.js';
+import { EmptyStreamError, NetworkStreamError, isStreamTransportError, recognizeBedrockValidationError, } from './stream-errors.js';
 import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, normalizeToolArgsString, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
@@ -173,6 +173,13 @@ async function doGenerate(ctx, options) {
     // Forward the turn's AbortSignal into the SDK's RequestOptions so firing the
     // controller (POST /cancel, idle timeout, shutdown abortAll) actually aborts
     // the outbound gateway fetch, not just harness bookkeeping (W-23988781).
+    //
+    // doGenerate is intentionally NOT run through recognizeBedrockValidationError
+    // (unlike doStream's create() seam): the only non-streaming caller in this
+    // harness is compactThread's summarize(), whose rejection is already wrapped
+    // as COMPACTION_FAILED. Error classification here targets the streaming turn
+    // path (8d) — a raw create() rejection propagating uncoded is correct for the
+    // summarize-only path.
     const message = await client.messages.create({ ...commonParams, stream: false }, { signal: options.abortSignal });
     const content = [];
     let sawToolCalls = false;
@@ -206,7 +213,37 @@ async function doStream(ctx, options) {
     const { client, commonParams } = await buildAnthropicRequest(ctx, options);
     // See doGenerate: thread the AbortSignal into the SDK so a mid-stream abort
     // tears down the live gateway socket (W-23988781).
-    const sdkStream = await client.messages.create({ ...commonParams, stream: true }, { signal: options.abortSignal });
+    let sdkStream;
+    try {
+        sdkStream = await client.messages.create({ ...commonParams, stream: true }, { signal: options.abortSignal });
+    }
+    catch (error) {
+        // A Bedrock `ValidationException` (notably a context-window overflow) is an
+        // HTTP 4xx that rejects `.create()` BEFORE the response stream is
+        // established — it never reaches the iterator catch below, so this is where
+        // that shape must be classified (8d). Confirmed on the orgfarm-e2e mastra
+        // run: an oversized-input failure surfaces as a rejected `.create()`, not a
+        // mid-stream frame. Yield it as an `error` chunk carrying the typed code
+        // rather than letting the raw rejection propagate uncoded. Every OTHER
+        // pre-stream rejection is rethrown unchanged to preserve the documented
+        // abort contract (an `APIUserAbortError` before the response propagates as a
+        // thrown rejection). We deliberately do NOT run the transport classifier
+        // here: `isStreamTransportError` matches the `AbortError` name, so
+        // classifying a pre-stream abort as `network-error` would break that
+        // contract. (A gateway that instead delivers the ValidationException as a
+        // 200 + eventstream error frame is still covered by the iterator catch.)
+        const validation = recognizeBedrockValidationError(error);
+        if (!validation)
+            throw error;
+        return {
+            stream: new ReadableStream({
+                start: (controller) => {
+                    controller.enqueue({ type: 'error', error: validation });
+                    controller.close();
+                },
+            }),
+        };
+    }
     const stream = new ReadableStream({
         start: async (controller) => {
             const textSpan = new TextSpanLifecycle();
@@ -214,6 +251,11 @@ async function doStream(ctx, options) {
             // sequence of input_json_delta strings on a single content block.
             const toolUseByIndex = new Map();
             let sawToolCalls = false;
+            // 8a false-success guard: did we see ≥1 recognized content / usage
+            // event? If the iterator exhausts cleanly having seen none, an
+            // intermediary closed the body without serving the request — surface a
+            // classified `error`, not a synthesized empty `finish`.
+            let sawContentOrUsage = false;
             // Cumulative usage tracked across `message_start` and `message_delta`.
             let mergedUsage;
             let finishRaw;
@@ -225,6 +267,7 @@ async function doStream(ctx, options) {
                     switch (event.type) {
                         case 'message_start': {
                             mergedUsage = mergeUsage(mergedUsage, event.message.usage);
+                            sawContentOrUsage = true;
                             // `stop_reason` is null on message_start in streaming mode.
                             break;
                         }
@@ -253,6 +296,7 @@ async function doStream(ctx, options) {
                             const delta = event.delta;
                             if (delta.type === 'text_delta') {
                                 textSpan.delta(controller, delta.text);
+                                sawContentOrUsage = true;
                             }
                             else if (delta.type === 'input_json_delta') {
                                 const tu = toolUseByIndex.get(event.index);
@@ -268,6 +312,7 @@ async function doStream(ctx, options) {
                             const tu = toolUseByIndex.get(event.index);
                             if (tu) {
                                 sawToolCalls = true;
+                                sawContentOrUsage = true;
                                 controller.enqueue({
                                     type: 'tool-call',
                                     toolCallId: tu.id,
@@ -283,6 +328,7 @@ async function doStream(ctx, options) {
                         case 'message_delta': {
                             mergedUsage = mergeUsage(mergedUsage, event.usage);
                             finishRaw = event.delta.stop_reason;
+                            sawContentOrUsage = true;
                             break;
                         }
                         case 'message_stop': {
@@ -296,10 +342,25 @@ async function doStream(ctx, options) {
                         }
                     }
                 }
-                // Stream ended without an explicit `message_stop` — close out the span
-                // and synthesize a terminal `finish` so V3 consumers see exactly one.
+                // Stream ended without an explicit `message_stop`. If we saw at least
+                // one recognized content / usage event, close out the span and
+                // synthesize a terminal `finish` so V3 consumers see exactly one. If
+                // we saw NONE — a clean-but-empty body — surface a classified `error`
+                // instead of a false-success empty `finish` (8a). A cancelled turn is
+                // exempt: an aborted stream ends cleanly here too (the SDK `Stream`
+                // swallows the abort), and its terminal event is the coordinator's
+                // teardown, not an empty-stream error.
                 if (!terminalEmitted) {
                     textSpan.closeIfOpen(controller);
+                    if (!sawContentOrUsage && !options.abortSignal?.aborted) {
+                        controller.enqueue({
+                            type: 'error',
+                            error: new EmptyStreamError('LLM Gateway pass-through (Anthropic) stream closed without any content, usage, or terminal event'),
+                        });
+                        terminalEmitted = true;
+                        controller.close();
+                        return;
+                    }
                     const finishReason = mapAnthropicFinishReason(finishRaw, sawToolCalls);
                     const usage = finalizeUsage(mergedUsage, ctx, finishReason.raw);
                     controller.enqueue({ type: 'finish', finishReason, usage });
@@ -316,10 +377,14 @@ async function doStream(ctx, options) {
                     controller.close();
                     return;
                 }
-                controller.enqueue({
-                    type: 'error',
-                    error: isStreamTransportError(error) ? new NetworkStreamError(error) : error,
-                });
+                // Classify before forwarding: a transport truncation → NetworkStreamError
+                // (`network-error`); a Bedrock ValidationException → ValidationStreamError
+                // (`context-window-exceeded` / `validation-error`, 8d). An unrecognized
+                // provider error is forwarded raw (uncoded), same as before.
+                const classified = isStreamTransportError(error)
+                    ? new NetworkStreamError(error)
+                    : recognizeBedrockValidationError(error);
+                controller.enqueue({ type: 'error', error: classified ?? error });
                 controller.close();
             }
         },

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

@@ -3,6 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import OpenAI from 'openai';
+import { EmptyStreamError } from './stream-errors.js';
 import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, normalizeToolArgsString, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
@@ -139,6 +140,11 @@ async function doStream(ctx, options) {
             let finishRaw;
             let usage;
             let terminalEmitted = false;
+            // 8a false-success guard — see the Anthropic builder. Set on any content
+            // text, tool call, usage chunk, or terminal `finish_reason`; a stream that
+            // produced none of those surfaces a classified `error`, not an empty
+            // `finish`.
+            let sawContentOrUsage = false;
             try {
                 for await (const chunk of sdkStream) {
                     // OpenAI-compatible servers emit a final usage-only chunk when
@@ -147,6 +153,7 @@ async function doStream(ctx, options) {
                     // populated `usage` field; treat it as a usage-only signal.
                     if (chunk.usage) {
                         usage = mapChatCompletionUsage(chunk.usage);
+                        sawContentOrUsage = true;
                     }
                     const choice = chunk.choices[0];
                     if (!choice)
@@ -154,6 +161,7 @@ async function doStream(ctx, options) {
                     const delta = choice.delta;
                     if (delta.content) {
                         textSpan.delta(controller, delta.content);
+                        sawContentOrUsage = true;
                     }
                     if (delta.tool_calls) {
                         // V3 ordering: any open text span must close BEFORE tool-call parts
@@ -164,6 +172,7 @@ async function doStream(ctx, options) {
                         // and pass-through-openai.ts both rotate eagerly at the same moment).
                         // `rotate` is a no-op when no text span is open.
                         textSpan.rotate(controller);
+                        sawContentOrUsage = true;
                         for (const tc of delta.tool_calls) {
                             const idx = tc.index;
                             let acc = toolCallsByIndex.get(idx);
@@ -189,6 +198,7 @@ async function doStream(ctx, options) {
                     }
                     if (choice.finish_reason !== null && choice.finish_reason !== undefined) {
                         finishRaw = choice.finish_reason;
+                        sawContentOrUsage = true;
                         // Flush any buffered tool calls. Chat Completions doesn't send a
                         // discrete "tool_call done" event — they're complete once the
                         // chunk's `finish_reason` arrives.
@@ -226,6 +236,19 @@ async function doStream(ctx, options) {
                     }
                 }
                 textSpan.closeIfOpen(controller);
+                // 8a: a clean-but-empty stream (no content, tool call, usage, or
+                // terminal `finish_reason`) is a false success — surface a classified
+                // `error` instead of the synthesized `finish`. A cancelled turn is
+                // exempt (its terminal event is the coordinator's teardown).
+                if (!sawContentOrUsage && !options.abortSignal?.aborted) {
+                    controller.enqueue({
+                        type: 'error',
+                        error: new EmptyStreamError('OpenAI-compatible chat-completions stream closed without any content, usage, or terminal event'),
+                    });
+                    terminalEmitted = true;
+                    controller.close();
+                    return;
+                }
                 const finishReason = mapChatCompletionFinishReason(finishRaw ?? null, sawToolCalls);
                 const finalUsage = usage ?? mapChatCompletionUsage(undefined);
                 if (isEmptyUsage(finalUsage)) {

package/dist/pass-through-openai.js

@@ -3,6 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import OpenAI from 'openai';
+import { EmptyStreamError, GatewayResponseError } from './stream-errors.js';
 import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIFinishReason, mapOpenAIUsage, normalizeToolArgsString, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
@@ -118,11 +119,19 @@ async function doStream(ctx, options) {
             const toolCallById = new Map();
             let sawToolCalls = false;
             let terminalEmitted = false;
+            // 8a false-success guard — see the Anthropic builder. The Responses
+            // wire carries usage only on the terminal `response.completed` /
+            // `response.incomplete` chunks (which return early), so here "content" is
+            // the whole signal: set on any text delta or completed tool call. A clean
+            // iterator exhaustion having seen none surfaces a classified `error`, not
+            // an empty `finish`.
+            let sawContent = false;
             try {
                 for await (const event of sdkStream) {
                     switch (event.type) {
                         case 'response.output_text.delta': {
                             textSpan.delta(controller, event.delta);
+                            sawContent = true;
                             break;
                         }
                         case 'response.output_item.added': {
@@ -151,6 +160,7 @@ async function doStream(ctx, options) {
                                 const tc = toolCallById.get(item.id ?? item.call_id);
                                 const finalArgs = item.arguments ?? tc?.argsBuffer ?? '';
                                 sawToolCalls = true;
+                                sawContent = true;
                                 controller.enqueue({
                                     type: 'tool-call',
                                     toolCallId: item.call_id,
@@ -175,19 +185,33 @@ async function doStream(ctx, options) {
                             controller.close();
                             return;
                         }
-                        case 'response.failed':
+                        case 'response.failed': {
+                            // A genuine failure — surface it as a classified `error`
+                            // carrying the structured `response.error` (`code` +
+                            // `message`) so the actionable reason (`rate_limit_exceeded`,
+                            // `invalid_prompt`, …) reaches consumers instead of an opaque
+                            // `finish('error')` that drops it (8c). Mirrors `case 'error'`
+                            // below: an error chunk + close, no synthesized `finish`.
+                            textSpan.closeIfOpen(controller);
+                            const responseError = event.response.error;
+                            controller.enqueue({
+                                type: 'error',
+                                error: new GatewayResponseError({
+                                    code: responseError?.code,
+                                    message: responseError?.message ?? 'OpenAI Responses API request failed',
+                                }),
+                            });
+                            terminalEmitted = true;
+                            controller.close();
+                            return;
+                        }
                         case 'response.incomplete': {
+                            // Truncation, not a failure — `incomplete_details.reason`
+                            // (`max_output_tokens` / `content_filter`) maps to a normal
+                            // `finish` with `unified='length'` / `'content-filter'`.
                             textSpan.closeIfOpen(controller);
                             const response = event.response;
-                            const rawStatus = response.status;
-                            // For `response.failed`, `status` is authoritative — drop any
-                            // `incomplete_details.reason` the upstream may have populated so
-                            // the mapper lands on its `status === 'failed'` arm and resolves
-                            // `unified='error'`. Forwarding the reason unconditionally would
-                            // demote `'error'` to `'length'` / `'content-filter'` on a
-                            // malformed-but-possible upstream shape.
-                            const incompleteReason = rawStatus === 'failed' ? undefined : response.incomplete_details?.reason;
-                            const finishReason = mapOpenAIFinishReason(rawStatus, sawToolCalls, incompleteReason);
+                            const finishReason = mapOpenAIFinishReason(response.status, sawToolCalls, response.incomplete_details?.reason);
                             const usage = finalizeUsage(response.usage, ctx, finishReason.raw);
                             controller.enqueue({ type: 'finish', finishReason, usage });
                             terminalEmitted = true;
@@ -195,9 +219,16 @@ async function doStream(ctx, options) {
                             return;
                         }
                         case 'error': {
+                            // Attach the upstream's structured `code` / `message` / `param`
+                            // onto the emitted error part so consumers get an actionable
+                            // reason instead of a bare message (8c).
                             controller.enqueue({
                                 type: 'error',
-                                error: new Error(event.message ?? 'OpenAI Responses API error'),
+                                error: new GatewayResponseError({
+                                    code: event.code,
+                                    message: event.message ?? 'OpenAI Responses API error',
+                                    param: event.param,
+                                }),
                             });
                             terminalEmitted = true;
                             controller.close();
@@ -208,10 +239,21 @@ async function doStream(ctx, options) {
                         // ignored — they're not in the V3 ChatEvent surface today.
                     }
                 }
-                // Stream ended without an explicit terminal event — synthesize one so
-                // V3 consumers see exactly one `finish`.
+                // Stream ended without an explicit terminal event. Seen ≥1 recognized
+                // content event ⇒ synthesize a `finish` so V3 consumers see exactly one.
+                // Seen NONE (and not aborted) ⇒ a clean-but-empty body: surface a
+                // classified `error` rather than a false-success empty `finish` (8a).
                 if (!terminalEmitted) {
                     textSpan.closeIfOpen(controller);
+                    if (!sawContent && !options.abortSignal?.aborted) {
+                        controller.enqueue({
+                            type: 'error',
+                            error: new EmptyStreamError('LLM Gateway pass-through (OpenAI Responses) stream closed without any content, usage, or terminal event'),
+                        });
+                        terminalEmitted = true;
+                        controller.close();
+                        return;
+                    }
                     const finishReason = mapOpenAIFinishReason(undefined, sawToolCalls, undefined);
                     const usage = finalizeUsage(undefined, ctx, finishReason.raw);
                     controller.enqueue({ type: 'finish', finishReason, usage });

package/dist/stream-errors.d.ts

@@ -1,8 +1,74 @@
 export declare const NETWORK_ERROR_CODE: 'network-error';
-export declare class NetworkStreamError extends Error {
+export declare const EMPTY_STREAM_ERROR_CODE: 'empty-stream';
+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';
+/**
+ * Base for every error the pass-through builders classify onto a V3 `error`
+ * stream part. It carries a stable, machine-readable `code` that
+ * `MastraEventAdapter` copies onto the consumer-visible `error` ChatEvent (see
+ * the "mid-stream errors are yielded as `error` chunks" Critical Invariant), so
+ * consumers branch on `error.code` instead of string-matching the message. A
+ * raw provider error that isn't classified surfaces uncoded, exactly as before.
+ */
+export declare abstract class ClassifiedStreamError extends Error {
+    abstract readonly code: string;
+}
+/** Transport-level truncation / socket blip (see {@link isStreamTransportError}); `network-error`. */
+export declare class NetworkStreamError extends ClassifiedStreamError {
     readonly name = "NetworkStreamError";
     readonly code: "network-error";
     constructor(cause: Error);
 }
+/** 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";
+    readonly code: "empty-stream";
+    constructor(message: string);
+}
+/**
+ * A structured provider-response error (8c). The provider's own `code` becomes
+ * {@link code} (falling back to `gateway-error`); `message` / optional `param`
+ * are preserved.
+ */
+export declare class GatewayResponseError extends ClassifiedStreamError {
+    readonly name = "GatewayResponseError";
+    readonly code: string;
+    readonly param?: string;
+    constructor(opts: {
+        code?: string | null;
+        message: string;
+        param?: string | null;
+    });
+}
+/** A Bedrock `ValidationException` (8d); `context-window-exceeded` for an overflow shape, else `validation-error`. */
+export declare class ValidationStreamError extends ClassifiedStreamError {
+    readonly name = "ValidationStreamError";
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Whether `error` (or any error in its `cause` chain) is a recognized
+ * transport-level truncation / socket fault. Walks the cause chain guarding
+ * against cycles. `AbortError` is included because an undici socket-abort under
+ * a hung read surfaces with that name (a user-initiated cancel never reaches
+ * here — the provider SDK `Stream` swallows it, see the abort Critical
+ * Invariant).
+ */
 export declare function isStreamTransportError(error: unknown): error is Error;
-export declare function isNetworkStreamError(error: unknown): error is NetworkStreamError;
+/**
+ * Recognizes the Bedrock `ValidationException` shape (8d), walking the `cause`
+ * chain and duck-typing the several ways `@anthropic-ai/bedrock-sdk` /
+ * `@aws-sdk` surface it (an `APIError` with a parsed `.error` body, an AWS
+ * `__type` tag, or the name / message text). Returns a {@link ValidationStreamError}
+ * carrying the extracted message + a typed code (`context-window-exceeded` for a
+ * context-overflow shape, else `validation-error`), or `undefined` when the
+ * error isn't a `ValidationException`.
+ */
+export declare function recognizeBedrockValidationError(error: unknown): ValidationStreamError | undefined;
+/**
+ * Whether `error` is any harness-classified stream error (network, empty,
+ * gateway-response, validation, …). The event adapter uses this to copy the
+ * error's `code` onto the ChatEvent regardless of which classifier produced it.
+ */
+export declare function isClassifiedStreamError(error: unknown): error is ClassifiedStreamError;

package/dist/stream-errors.js

@@ -3,31 +3,171 @@
  * See LICENSE.txt for license terms.
  */
 export const NETWORK_ERROR_CODE = 'network-error';
-export class NetworkStreamError extends Error {
+export const EMPTY_STREAM_ERROR_CODE = 'empty-stream';
+export const CONTEXT_OVERFLOW_ERROR_CODE = 'context-window-exceeded';
+export const VALIDATION_ERROR_CODE = 'validation-error';
+export const GATEWAY_RESPONSE_ERROR_CODE = 'gateway-error';
+/**
+ * Base for every error the pass-through builders classify onto a V3 `error`
+ * stream part. It carries a stable, machine-readable `code` that
+ * `MastraEventAdapter` copies onto the consumer-visible `error` ChatEvent (see
+ * the "mid-stream errors are yielded as `error` chunks" Critical Invariant), so
+ * consumers branch on `error.code` instead of string-matching the message. A
+ * raw provider error that isn't classified surfaces uncoded, exactly as before.
+ */
+export class ClassifiedStreamError extends Error {
+}
+/** Transport-level truncation / socket blip (see {@link isStreamTransportError}); `network-error`. */
+export class NetworkStreamError extends ClassifiedStreamError {
     name = 'NetworkStreamError';
     code = NETWORK_ERROR_CODE;
     constructor(cause) {
         super(cause.message, { cause });
     }
 }
+/** 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';
+    code = EMPTY_STREAM_ERROR_CODE;
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * A structured provider-response error (8c). The provider's own `code` becomes
+ * {@link code} (falling back to `gateway-error`); `message` / optional `param`
+ * are preserved.
+ */
+export class GatewayResponseError extends ClassifiedStreamError {
+    name = 'GatewayResponseError';
+    code;
+    param;
+    constructor(opts) {
+        super(opts.message);
+        this.code = opts.code != null && opts.code.trim() !== '' ? opts.code : GATEWAY_RESPONSE_ERROR_CODE;
+        if (opts.param != null)
+            this.param = opts.param;
+    }
+}
+/** A Bedrock `ValidationException` (8d); `context-window-exceeded` for an overflow shape, else `validation-error`. */
+export class ValidationStreamError extends ClassifiedStreamError {
+    name = 'ValidationStreamError';
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Node / undici transport-fault codes that mean "the socket dropped mid-flight,"
+ * not "the model failed." A stream failing with one of these is a transient blip
+ * a retry could recover — tagging it `network-error` is what lets a
+ * classification-keyed retry fire (8e).
+ */
+const TRANSPORT_ERROR_CODES = new Set([
+    'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'EPIPE',
+]);
+/**
+ * Exact (punctuation-stripped, lower-cased) messages undici / the provider SDKs
+ * use for the same transport truncations. Kept as an exact-match allowlist —
+ * substring matching would mis-tag a provider error that merely *mentions* a
+ * transport phrase (guarded by a regression test).
+ */
+const TRANSPORT_ERROR_MESSAGES = new Set([
+    'terminated',
+    'other side closed',
+    'truncated event message received',
+]);
+/**
+ * Whether `error` (or any error in its `cause` chain) is a recognized
+ * transport-level truncation / socket fault. Walks the cause chain guarding
+ * against cycles. `AbortError` is included because an undici socket-abort under
+ * a hung read surfaces with that name (a user-initiated cancel never reaches
+ * here — the provider SDK `Stream` swallows it, see the abort Critical
+ * Invariant).
+ */
 export function isStreamTransportError(error) {
     const seen = new Set();
     let current = error;
     while (current instanceof Error && !seen.has(current)) {
         seen.add(current);
-        if ('code' in current && current.code === 'UND_ERR_SOCKET')
+        const code = current.code;
+        if (typeof code === 'string' && TRANSPORT_ERROR_CODES.has(code))
+            return true;
+        if (current.name === 'AbortError')
             return true;
         const message = current.message.toLowerCase().replace(/[.!]$/, '');
-        if (message === 'terminated' ||
-            message === 'other side closed' ||
-            message === 'truncated event message received') {
+        if (TRANSPORT_ERROR_MESSAGES.has(message))
             return true;
-        }
         current = current.cause;
     }
     return false;
 }
-export function isNetworkStreamError(error) {
-    return error instanceof NetworkStreamError;
+/**
+ * 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` /
+ * `@aws-sdk` surface it (an `APIError` with a parsed `.error` body, an AWS
+ * `__type` tag, or the name / message text). Returns a {@link ValidationStreamError}
+ * carrying the extracted message + a typed code (`context-window-exceeded` for a
+ * context-overflow shape, else `validation-error`), or `undefined` when the
+ * error isn't a `ValidationException`.
+ */
+export function recognizeBedrockValidationError(error) {
+    const seen = new Set();
+    let current = error;
+    while (current instanceof Error && !seen.has(current)) {
+        seen.add(current);
+        const message = extractValidationExceptionMessage(current);
+        if (message !== undefined) {
+            const code = CONTEXT_OVERFLOW_PATTERNS.test(message) ? CONTEXT_OVERFLOW_ERROR_CODE : VALIDATION_ERROR_CODE;
+            return new ValidationStreamError(message, code);
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
+/**
+ * Returns the human-readable message when `err` is a Bedrock `ValidationException`,
+ * else `undefined`. Recognizes: the error `name`, an AWS `__type` tag, or a
+ * parsed `.error` body carrying `type` / `__type` — preferring the body's
+ * `message` when present so the actionable detail survives.
+ */
+function extractValidationExceptionMessage(err) {
+    const body = err.error;
+    const bodyObj = typeof body === 'object' && body !== null ? body : undefined;
+    const isValidationException = err.name === 'ValidationException' ||
+        typeMatchesValidationException(err.__type) ||
+        (bodyObj !== undefined &&
+            (typeMatchesValidationException(bodyObj['type']) ||
+                typeMatchesValidationException(bodyObj['__type']) ||
+                typeMatchesValidationException(bodyObj['name']))) ||
+        /validationexception/i.test(err.message);
+    if (!isValidationException)
+        return undefined;
+    const bodyMessage = bodyObj !== undefined && typeof bodyObj['message'] === 'string' ? bodyObj['message'] : undefined;
+    return bodyMessage ?? err.message;
+}
+function typeMatchesValidationException(value) {
+    return typeof value === 'string' && value.includes('ValidationException');
+}
+/**
+ * Whether `error` is any harness-classified stream error (network, empty,
+ * gateway-response, validation, …). The event adapter uses this to copy the
+ * error's `code` onto the ChatEvent regardless of which classifier produced it.
+ */
+export function isClassifiedStreamError(error) {
+    return error instanceof ClassifiedStreamError;
 }
 //# sourceMappingURL=stream-errors.js.map

package/package.json

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