@salesforce/sfdx-agent-harness-mastra 0.60.0 → 0.62.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.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
+- **harness-mastra**: forward abortSignal into provider gateway fetch @W-23988781@ ([#779](https://github.com/forcedotcom/agentic-dx/pull/779))
+
 ## [0.60.0] - 2026-09-01
 
 ### Features

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/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
@@ -170,7 +170,17 @@ async function buildAnthropicRequest(ctx, options) {
 }
 async function doGenerate(ctx, options) {
     const { client, commonParams } = await buildAnthropicRequest(ctx, options);
-    const message = await client.messages.create({ ...commonParams, stream: false });
+    // 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;
     for (const block of message.content) {
@@ -201,7 +211,39 @@ async function doGenerate(ctx, options) {
 }
 async function doStream(ctx, options) {
     const { client, commonParams } = await buildAnthropicRequest(ctx, options);
-    const sdkStream = await client.messages.create({ ...commonParams, stream: true });
+    // See doGenerate: thread the AbortSignal into the SDK so a mid-stream abort
+    // tears down the live gateway socket (W-23988781).
+    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();
@@ -209,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;
@@ -220,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;
                         }
@@ -248,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);
@@ -263,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,
@@ -278,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': {
@@ -291,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 });
@@ -311,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
@@ -78,7 +79,10 @@ async function buildRequest(ctx, options) {
 async function doGenerate(ctx, options) {
     const { client, commonParams } = await buildRequest(ctx, options);
     const params = { ...commonParams };
-    const response = await client.chat.completions.create(params);
+    // 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).
+    const response = await client.chat.completions.create(params, { signal: options.abortSignal });
     const content = [];
     const choice = response.choices[0];
     let sawToolCalls = false;
@@ -120,7 +124,9 @@ async function doStream(ctx, options) {
         // to `undefined` `LanguageModelV3Usage` per the missing-usage contract.
         stream_options: { include_usage: true },
     };
-    const sdkStream = await client.chat.completions.create(params);
+    // 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.chat.completions.create(params, { signal: options.abortSignal });
     const stream = new ReadableStream({
         start: async (controller) => {
             const textSpan = new TextSpanLifecycle();
@@ -134,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
@@ -142,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)
@@ -149,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
@@ -159,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);
@@ -184,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.
@@ -221,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
@@ -76,7 +77,10 @@ async function buildOpenAIRequest(ctx, options) {
 async function doGenerate(ctx, options) {
     const { client, commonParams } = await buildOpenAIRequest(ctx, options);
     const params = { ...commonParams };
-    const response = await client.responses.create(params);
+    // 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).
+    const response = await client.responses.create(params, { signal: options.abortSignal });
     const content = [];
     let sawToolCalls = false;
     if (response.output_text && response.output_text.length > 0) {
@@ -103,7 +107,9 @@ async function doGenerate(ctx, options) {
 async function doStream(ctx, options) {
     const { client, commonParams } = await buildOpenAIRequest(ctx, options);
     const params = { ...commonParams, stream: true };
-    const sdkStream = await client.responses.create(params);
+    // 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.responses.create(params, { signal: options.abortSignal });
     const stream = new ReadableStream({
         start: async (controller) => {
             const textSpan = new TextSpanLifecycle();
@@ -113,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': {
@@ -146,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,
@@ -170,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;
@@ -190,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();
@@ -203,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.60.0",
+  "version": "0.62.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.61.0"
+    "@salesforce/sfdx-agent-sdk": "0.63.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.61.0",
+    "@salesforce/sfdx-agent-sdk": "0.63.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",