@salesforce/sfdx-agent-harness-mastra 0.96.0 → 0.97.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.97.0] - 2026-10-05
+
+### Features
+- **harness-mastra,agent-sdk**: retry transient LLM failures before first token @W-24236393@ ([#856](https://github.com/forcedotcom/agentic-dx/pull/856))
+
 ## [0.96.0] - 2026-10-03
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -29,8 +29,9 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 This in-process harness emits structured `llm-request` / `llm-response` wire events. Matching events carry the
 harness-generated `correlationId`; `llm-response` provides best-effort `responseText` and `timeToFirstTokenMs` after the
 streaming body terminates. It also emits the debug-only `mcp-tool-call-completed` event; its `durationMs` is an
-adapter/coordinator-observed window and can include a model round-trip. It does **not** emit `llm-retry` telemetry
-because its stateless fetch layer has no observable retry attempt counter. See the SDK README's
+adapter/coordinator-observed window and can include a model round-trip. It emits numeric-only, PII-free `llm-retry`
+telemetry when `withPreFirstTokenRetry` re-issues a turn after a transient establishment or in-band failure before the
+first consumer-visible part. The fetch wrapper itself stays stateless. See the SDK README's
 [cross-harness coverage table](../sfdx-agent-sdk/README.md#cross-harness-coverage) for the complete contract and
 cross-harness comparison.
 

package/dist/index.d.ts

@@ -11,7 +11,9 @@ export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSe
  * `MastraHarnessFactoryConfig.languageModelBuilders`. The shape mirrors what
  * `MastraHarness.buildLanguageModel` currently hands its internal builders, so an
  * injected builder receives the same context bag and can compose wire monitoring +
- * proxy routing identically to the native pass-through builders.
+ * proxy routing identically to the native pass-through builders. The harness wraps
+ * the returned model with pre-first-token retry while preserving `specificationVersion`,
+ * `provider`, `modelId`, and `supportedUrls`.
  *
  * @remarks
  * All fields come from the harness:
@@ -37,7 +39,13 @@ export type MastraLanguageModelBuilderContext = {
  * (e.g. a temporary GovCloud `chat/generations` fallback). The builder receives the
  * same context bag the harness's built-in pass-through builders get, so an injected
  * builder can emit `WireCommunicationEvent`s and honor `HTTPS_PROXY` routing without
- * duplicating the harness's own fetch wrapper / wire-monitoring plumbing.
+ * duplicating the harness's own fetch wrapper / wire-monitoring plumbing. The
+ * returned model is decorated with pre-first-token retry (W-24236393). Transient
+ * errors the builder throws from `doStream` / `doGenerate` (HTTP 429/5xx, classified
+ * network-error, rate-limit bodies) may be retried before any consumer-visible part.
+ * The wrapper adds up to three outer attempts; the harness disables native retries only on its
+ * built-in provider clients, so disable retries inside an injected builder to avoid
+ * multiplicative requests.
  *
  * @example
  * ```ts

package/dist/mastra-harness.d.ts

@@ -9,7 +9,7 @@ import { type HttpErrorCapture } from './mcp-config-mapper.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
 import { type MultimodalFile } from '@salesforce/sfdx-agent-sdk';
 import type { LanguageModelV3 } from '@ai-sdk/provider';
-import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
+import { Clock, type LogRecord, type BackoffRetryerDeps, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
 /**
@@ -254,6 +254,11 @@ export interface MastraHarnessOptions {
      * handle a custom hint without editing the harness's internal switch.
      */
     languageModelBuilders?: Readonly<Record<string, (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3>>;
+    /**
+     * Clock / sleep / RNG for the pre-first-token LLM retry loop (W-24236393), whose policy is
+     * `PRE_FIRST_TOKEN_RETRY_OPTIONS`. Tests inject a no-sleep `sleep`.
+     */
+    llmRetryerDeps?: Partial<BackoffRetryerDeps>;
 }
 export declare class MastraHarness implements MastraAgentHarness {
     private readonly storageRootFolder;
@@ -314,6 +319,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly innerFetch;
     private readonly wireObserverAbortController;
     private readonly languageModelBuilders?;
+    private readonly llmRetryerDeps;
     /**
      * Per-turn, per-thread consumer/frontend tool-args retry counters (S1,
      * W-24023028): `agentId → threadId → (toolName → consecutive-failure count)`.
@@ -531,6 +537,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      */
     private resolveToolArgsRetryCounts;
     private buildLanguageModel;
+    private wrapLanguageModel;
     private destroyThreadBestEffort;
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -30,6 +30,7 @@ import { buildOpenAILanguageModel } from './pass-through-openai.js';
 import { readToolArgsRetryScope, TOOL_ARGS_RETRY_SCOPE_AGENT_ID, TOOL_ARGS_RETRY_SCOPE_PROVIDER, TOOL_ARGS_RETRY_SCOPE_THREAD_ID, } from './v3-stream-mapping.js';
 import { ToolResultRedactionProcessor } from './mastra-tool-result-redaction-processor.js';
 import { backfillCreatedAt, buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
+import { withPreFirstTokenRetry } from './retry-pre-first-token.js';
 import { makeAbortable } from './utils.js';
 import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, } from '@mastra/core/workspace';
 /**
@@ -486,6 +487,7 @@ export class MastraHarness {
     innerFetch;
     wireObserverAbortController = new AbortController();
     languageModelBuilders;
+    llmRetryerDeps;
     /**
      * Per-turn, per-thread consumer/frontend tool-args retry counters (S1,
      * W-24023028): `agentId → threadId → (toolName → consecutive-failure count)`.
@@ -516,6 +518,7 @@ export class MastraHarness {
         this.idleReadTimeoutMs = opts.idleReadTimeoutMs ?? DEFAULT_IDLE_READ_TIMEOUT_MS;
         this.innerFetch = opts.innerFetch ?? globalThis.fetch;
         this.languageModelBuilders = opts.languageModelBuilders;
+        this.llmRetryerDeps = { clock: this.clock, ...opts.llmRetryerDeps };
         this.storage = new LibSQLStore({
             id: 'mastra-storage',
             url: `file:${this.storageRootFolder}/mastra.db`,
@@ -1615,7 +1618,7 @@ export class MastraHarness {
         switch (initial.providerHint) {
             case 'bedrock-anthropic':
                 // Salesforce LLM Gateway's `/invoke-with-response-stream` (Bedrock pass-through).
-                return buildAnthropicLanguageModel({
+                return this.wrapLanguageModel(buildAnthropicLanguageModel({
                     getInfo,
                     logBus,
                     wireHooks,
@@ -1624,11 +1627,11 @@ export class MastraHarness {
                     getConsumerToolSchemas,
                     getToolArgsRetryCounts,
                     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({
+                return this.wrapLanguageModel(buildAnthropicDirectLanguageModel({
                     getInfo,
                     logBus,
                     wireHooks,
@@ -1637,13 +1640,13 @@ export class MastraHarness {
                     getConsumerToolSchemas,
                     getToolArgsRetryCounts,
                     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({
+                return this.wrapLanguageModel(buildOpenAILanguageModel({
                     getInfo,
                     logBus,
                     wireHooks,
@@ -1652,12 +1655,12 @@ export class MastraHarness {
                     getConsumerToolSchemas,
                     getToolArgsRetryCounts,
                     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({
+                return this.wrapLanguageModel(buildOpenAIChatCompletionsLanguageModel({
                     getInfo,
                     logBus,
                     wireHooks,
@@ -1666,7 +1669,7 @@ export class MastraHarness {
                     getConsumerToolSchemas,
                     getToolArgsRetryCounts,
                     idleReadTimeoutMs,
-                });
+                }));
             default: {
                 // Consult the injected builders map before throwing. This is the
                 // extension point for consumer-registered wire shapes (e.g. a temporary
@@ -1674,7 +1677,7 @@ export class MastraHarness {
                 // the same context bag the built-in builders get.
                 const custom = this.languageModelBuilders?.[initial.providerHint];
                 if (custom) {
-                    return custom({ getInfo, logBus, emitWireCommunication, innerFetch });
+                    return this.wrapLanguageModel(custom({ getInfo, logBus, emitWireCommunication, innerFetch }));
                 }
                 // Defensive — manager-side G8 should have caught this before
                 // we got here. Make the error typed so consumers can branch
@@ -1683,6 +1686,21 @@ export class MastraHarness {
             }
         }
     }
+    wrapLanguageModel(inner) {
+        return withPreFirstTokenRetry(inner, {
+            retryerDeps: this.llmRetryerDeps,
+            logBus: this.buses.getLogBus(),
+            emitTelemetry: (event) => {
+                try {
+                    this.buses.emitTelemetry({ ...event, timestamp: this.clock.now() });
+                }
+                catch (err) {
+                    if (!isDisposedError(err))
+                        throw err;
+                }
+            },
+        });
+    }
     async destroyThreadBestEffort(agentId, threadId) {
         try {
             await this.destroyThread(agentId, threadId);

package/dist/pass-through-anthropic.js

@@ -35,6 +35,8 @@ export function buildAnthropicLanguageModel(opts) {
         buildClient: (info) => new AnthropicBedrock({
             baseURL: info.baseUrl,
             skipAuth: true,
+            // `withPreFirstTokenRetry` is the single retry owner; the SDK's built-in retries would multiply with it.
+            maxRetries: 0,
             // 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.
@@ -96,6 +98,8 @@ export function buildAnthropicDirectLanguageModel(opts) {
         new Anthropic({
             apiKey: 'anthropic-direct-resolver-managed',
             baseURL: info.baseUrl,
+            // `withPreFirstTokenRetry` is the single retry owner; the SDK's built-in retries would multiply with it.
+            maxRetries: 0,
             fetch: createGatewayFetch(() => translateBearerToXApiKey(info), ctx.wireHooks ?? buildWireHooks(ctx), innerFetch, idleReadTimeoutMs, logBus),
         }),
     };

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

@@ -65,6 +65,8 @@ async function buildRequest(ctx, options) {
             : undefined);
     const client = new OpenAI({
         baseURL: info.baseUrl,
+        // `withPreFirstTokenRetry` is the single retry owner; the SDK's built-in retries would multiply with it.
+        maxRetries: 0,
         // The custom fetch injects the resolver-built `Authorization` header per
         // request. The SDK still wants a non-empty `apiKey` at construction;
         // an opaque sentinel keeps it from reading `process.env['OPENAI_API_KEY']`.

package/dist/pass-through-openai.js

@@ -61,6 +61,8 @@ async function buildOpenAIRequest(ctx, options) {
             : undefined);
     const client = new OpenAI({
         baseURL: info.baseUrl,
+        // `withPreFirstTokenRetry` is the single retry owner; the SDK's built-in retries would multiply with it.
+        maxRetries: 0,
         // The custom fetch injects the resolver-built `Authorization` header per
         // request. The SDK still wants a non-empty `apiKey` in case the fetch
         // doesn't override the SDK-set Authorization; passing an opaque sentinel

package/dist/retry-pre-first-token.d.ts

@@ -0,0 +1,29 @@
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+import { type BackoffRetryerDeps, type LogBus, type RetryOptions } from '@salesforce/agentic-common';
+import type { LlmRetryEvent } from '@salesforce/sfdx-agent-sdk';
+export declare const PRE_FIRST_TOKEN_RETRY_OPTIONS: {
+    readonly maxAttempts: 3;
+    readonly maxTotalElapsedMs: 30000;
+    readonly initialDelayMs: 1000;
+    readonly maxDelayMs: 8000;
+};
+/** The single retry policy: builds the production retryer, bounds the hard deadline, and labels telemetry. */
+export type PreFirstTokenRetryPolicy = RetryOptions & {
+    maxAttempts: number;
+    maxTotalElapsedMs: number;
+};
+export type PreFirstTokenRetryOptions = {
+    /** Default: {@link PRE_FIRST_TOKEN_RETRY_OPTIONS}. `maxTotalElapsedMs` is also the hard pre-first-token deadline. */
+    policy?: PreFirstTokenRetryPolicy;
+    /** Test seam for the retryer's clock / sleep / RNG. */
+    retryerDeps?: Partial<BackoffRetryerDeps>;
+    /** Must swallow its own expected failures (e.g. a disposed bus); anything thrown propagates into the retry loop. */
+    emitTelemetry?: (event: Omit<LlmRetryEvent, 'timestamp'>) => void;
+    logBus?: LogBus;
+};
+/**
+ * Whether `err` is a transient LLM failure worth re-issuing before any consumer-visible part. Shared by
+ * establishment throws and in-band `error` stream parts, which carry the same wire-level shapes.
+ */
+export declare function isTransientLlmError(err: unknown): boolean;
+export declare function withPreFirstTokenRetry(inner: LanguageModelV3, opts?: PreFirstTokenRetryOptions): LanguageModelV3;

package/dist/retry-pre-first-token.js

@@ -0,0 +1,356 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { BackoffRetryer, getErrorMessage, isAbortError, RealClock, } from '@salesforce/agentic-common';
+import { CONTEXT_OVERFLOW_ERROR_CODE, EMPTY_STREAM_ERROR_CODE, isClassifiedStreamError, isStreamTransportError, NETWORK_ERROR_CODE, PreFirstTokenDeadlineError, VALIDATION_ERROR_CODE, } from './stream-errors.js';
+/**
+ * Mirrors the retryable set of the provider SDKs (`openai`, `@anthropic-ai/sdk`) whose native retries this wrapper
+ * replaces (`maxRetries: 0`): 408 timeout, 409 lock timeout, 429, and every 5xx. Keep in step with those SDKs'
+ * `shouldRetry`.
+ */
+function isRetryableStatus(status) {
+    return status === 408 || status === 409 || status === 429 || (status >= 500 && status < 600);
+}
+/** Provider-SDK connection failures (no HTTP status); the SDKs retry these natively. */
+const SDK_CONNECTION_ERROR_NAMES = new Set(['APIConnectionError', 'APIConnectionTimeoutError']);
+const RETRYABLE_TERMINAL_CODES = new Set([
+    'rate_limit_exceeded',
+    'server_error',
+    'overloaded_error',
+    'PROVIDER_ERROR',
+    EMPTY_STREAM_ERROR_CODE,
+    NETWORK_ERROR_CODE,
+]);
+const PERMANENT_TERMINAL_CODES = new Set([
+    VALIDATION_ERROR_CODE,
+    CONTEXT_OVERFLOW_ERROR_CODE,
+    'invalid_prompt',
+    'content-filter',
+]);
+const RATE_LIMIT_BODY = /rate limit reached/i;
+const OVERLOADED_BODY = /overloaded/i;
+export const PRE_FIRST_TOKEN_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    maxTotalElapsedMs: 30_000,
+    initialDelayMs: 1_000,
+    maxDelayMs: 8_000,
+};
+const PRELUDE_PART_TYPES = new Set(['stream-start', 'response-metadata', 'raw']);
+/**
+ * Cap on buffered prelude parts. A model that emits this many without any real content is treated as committed
+ * rather than buffered further: retry is disabled for that turn (fail safe) instead of growing without bound.
+ */
+const MAX_PRELUDE_PARTS = 32;
+/** Largest delay `setTimeout` honors (2^31 - 1 ms); larger values fire almost immediately. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * Whether `err` is a transient LLM failure worth re-issuing before any consumer-visible part. Shared by
+ * establishment throws and in-band `error` stream parts, which carry the same wire-level shapes.
+ */
+export function isTransientLlmError(err) {
+    if (isAbortError(err))
+        return false;
+    if (isClassifiedStreamError(err)) {
+        if (PERMANENT_TERMINAL_CODES.has(err.code))
+            return false;
+        if (RETRYABLE_TERMINAL_CODES.has(err.code))
+            return true;
+    }
+    // The provider SDKs let the server override their status heuristics with `x-should-retry`; keep that parity.
+    const hint = readErrorHeader(err, 'x-should-retry')?.trim().toLowerCase();
+    if (hint === 'false')
+        return false;
+    if (hint === 'true')
+        return true;
+    return (hasRetryableStatus(err) || isSdkConnectionError(err) || isStreamTransportError(err) || bodyLooksTransient(err));
+}
+function isSdkConnectionError(err) {
+    return walkErrorObjects(err).some((rec) => SDK_CONNECTION_ERROR_NAMES.has(rec.constructor?.name));
+}
+/** First value of `name` from the `headers` of `err` or anything in its `cause` chain. */
+function readErrorHeader(err, name) {
+    for (const rec of walkErrorObjects(err)) {
+        const value = readHeader(rec.headers, name);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+function readHeader(headers, name) {
+    if (headers === undefined || headers === null)
+        return undefined;
+    let raw;
+    if (typeof headers.get === 'function') {
+        raw = headers.get(name);
+    }
+    else if (typeof headers === 'object') {
+        raw = Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+    }
+    return typeof raw === 'string' && raw.trim() !== '' ? raw : undefined;
+}
+/** `maxTotalElapsedMs` is a real timer here (not just a backoff budget), so it must be a usable `setTimeout` delay. */
+function assertValidPolicy(policy) {
+    const { maxAttempts, maxTotalElapsedMs, initialDelayMs, maxDelayMs } = policy;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error(`Invalid pre-first-token retry policy: maxAttempts must be an integer >= 1 (got ${maxAttempts}).`);
+    }
+    if (!Number.isFinite(maxTotalElapsedMs) || maxTotalElapsedMs <= 0 || maxTotalElapsedMs > MAX_TIMER_MS) {
+        throw new Error(`Invalid pre-first-token retry policy: maxTotalElapsedMs must be in (0, ${MAX_TIMER_MS}] (got ${maxTotalElapsedMs}).`);
+    }
+    const { backoffFactor, maxRetryAfterMs } = policy;
+    if (backoffFactor !== undefined && (!Number.isFinite(backoffFactor) || backoffFactor < 1)) {
+        throw new Error(`Invalid pre-first-token retry policy: backoffFactor must be a finite number >= 1 (got ${backoffFactor}).`);
+    }
+    if (maxRetryAfterMs !== undefined && (Number.isNaN(maxRetryAfterMs) || maxRetryAfterMs < 0)) {
+        throw new Error(`Invalid pre-first-token retry policy: maxRetryAfterMs must be a number >= 0 (got ${maxRetryAfterMs}).`);
+    }
+    for (const [name, value] of [
+        ['initialDelayMs', initialDelayMs],
+        ['maxDelayMs', maxDelayMs],
+    ]) {
+        if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+            throw new Error(`Invalid pre-first-token retry policy: ${name} must be a finite number >= 0 (got ${value}).`);
+        }
+    }
+}
+export function withPreFirstTokenRetry(inner, opts = {}) {
+    const policy = opts.policy ?? PRE_FIRST_TOKEN_RETRY_OPTIONS;
+    assertValidPolicy(policy);
+    const ctx = {
+        policy,
+        retryer: new BackoffRetryer(policy, opts.retryerDeps),
+        clock: opts.retryerDeps?.clock ?? new RealClock(),
+        emitTelemetry: opts.emitTelemetry,
+        logBus: opts.logBus,
+    };
+    return {
+        specificationVersion: inner.specificationVersion,
+        provider: inner.provider,
+        modelId: inner.modelId,
+        supportedUrls: inner.supportedUrls,
+        doGenerate: (options) => retryDoGenerate(inner, options, ctx),
+        doStream: (options) => retryDoStream(inner, options, ctx),
+    };
+}
+async function retryDoGenerate(inner, options, ctx) {
+    return withPreCommitDeadline(options, ctx, (bounded) => ctx.retryer.execute(
+    // `abortable` bounds the caller even if the model ignores the signal; it cannot stop that work.
+    () => abortable(Promise.resolve(inner.doGenerate(bounded)), bounded.abortSignal), {
+        signal: bounded.abortSignal,
+        isRetryableError: isTransientLlmError,
+        getRetryAfterMsFromError: (err) => extractRetryAfterMs(err, ctx.clock),
+        onRetry: (info) => emitRetry(ctx, info.attempt, info.delayMs, info.error),
+    }));
+}
+async function retryDoStream(inner, options, ctx) {
+    return withPreCommitDeadline(options, ctx, async (bounded) => {
+        const attempt = await ctx.retryer.execute(() => readUntilCommitOrRetryableError(inner, bounded), {
+            signal: bounded.abortSignal,
+            isRetryableError: isTransientLlmError,
+            getRetryAfterMsFromError: (err) => extractRetryAfterMs(err, ctx.clock),
+            isRetryableResult: (result) => result.retryable,
+            getRetryAfterMs: (result) => extractRetryAfterMs(bufferedError(result), ctx.clock),
+            onRetry: (info) => emitRetry(ctx, info.attempt, info.delayMs, info.error ?? bufferedError(info.result)),
+        });
+        return attempt.result;
+    });
+}
+/**
+ * Runs `run` with `options.abortSignal` composed with a deadline timer, then disarms the timer. The timer
+ * only lives for the pre-commit window: once `run` settles (a committed stream or a result), later stream
+ * consumption is governed solely by the caller's own signal. A deadline abort surfaces as
+ * {@link PreFirstTokenDeadlineError}; a caller abort propagates unchanged.
+ */
+async function withPreCommitDeadline(options, ctx, run) {
+    const deadlineMs = ctx.policy.maxTotalElapsedMs;
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), deadlineMs);
+    const abortSignal = options.abortSignal === undefined ? deadline.signal : AbortSignal.any([options.abortSignal, deadline.signal]);
+    try {
+        return await run({ ...options, abortSignal });
+    }
+    catch (err) {
+        if (deadline.signal.aborted && options.abortSignal?.aborted !== true) {
+            throw new PreFirstTokenDeadlineError(deadlineMs);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Rejects with the signal's reason as soon as it aborts, even if `promise` (a non-cooperating model) never
+ * settles. Racing only bounds the caller: the underlying work keeps running, so callers that own a resource
+ * (the `doStream` result) must release a late settlement themselves.
+ */
+function abortable(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+async function readUntilCommitOrRetryableError(inner, options) {
+    const signal = options.abortSignal;
+    signal?.throwIfAborted();
+    const pending = Promise.resolve(inner.doStream(options));
+    let result;
+    try {
+        result = await abortable(pending, signal);
+    }
+    catch (err) {
+        // The model may still resolve after we gave up on it; release that late stream.
+        pending.then((late) => late.stream.cancel()).catch(() => undefined);
+        throw err;
+    }
+    const reader = result.stream.getReader();
+    const buffered = [];
+    try {
+        for (;;) {
+            const { done, value } = await abortable(reader.read(), signal);
+            if (done) {
+                reader.releaseLock();
+                return { result: { ...result, stream: replayBuffered(buffered) }, buffered, retryable: false };
+            }
+            if (value === undefined)
+                continue;
+            buffered.push(value);
+            if (value.type === 'error' && isTransientLlmError(value.error)) {
+                // Release the upstream body now, whether or not another attempt follows (the final attempt
+                // is replayed from `buffered`). Not awaited: a non-cooperating cancel() must not stall the retry.
+                reader.cancel().catch(() => undefined);
+                return { result: { ...result, stream: replayBuffered(buffered) }, buffered, retryable: true };
+            }
+            if (commitsAttempt(value, buffered.length)) {
+                return {
+                    result: { ...result, stream: replayBuffered(buffered, reader) },
+                    buffered,
+                    retryable: false,
+                };
+            }
+        }
+    }
+    catch (err) {
+        // A rejected read before commit (e.g. ECONNRESET) propagates to the retryer, which classifies it.
+        // Don't await the cancel: a non-cooperating stream may never settle it.
+        reader.cancel().catch(() => undefined);
+        throw err;
+    }
+}
+/** The commit boundary: retry is only allowed while every part so far is prelude and the buffer is under its cap. */
+function commitsAttempt(part, bufferedCount) {
+    return part.type === 'error' || !PRELUDE_PART_TYPES.has(part.type) || bufferedCount >= MAX_PRELUDE_PARTS;
+}
+function replayBuffered(buffered, reader) {
+    let index = 0;
+    return new ReadableStream({
+        async pull(controller) {
+            if (index < buffered.length) {
+                controller.enqueue(buffered[index]);
+                index += 1;
+                return;
+            }
+            if (reader === undefined) {
+                controller.close();
+                return;
+            }
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(next.value);
+            }
+            catch (err) {
+                controller.error(err);
+            }
+        },
+        cancel(reason) {
+            return reader?.cancel(reason);
+        },
+    });
+}
+function bufferedError(attempt) {
+    const part = attempt?.buffered.find((item) => item.type === 'error');
+    return part?.type === 'error' ? part.error : undefined;
+}
+function emitRetry(ctx, attempt, retryDelayMs, cause) {
+    const errorStatus = extractStatus(cause);
+    const maxRetries = ctx.policy.maxAttempts;
+    ctx.emitTelemetry?.({
+        type: 'llm-retry',
+        attempt,
+        maxRetries,
+        retryDelayMs,
+        ...(errorStatus !== undefined ? { errorStatus } : {}),
+    });
+    ctx.logBus?.warn('LLM retry', {
+        attempt,
+        maxRetries,
+        retryDelayMs,
+        ...(errorStatus !== undefined ? { errorStatus } : {}),
+        error: getErrorMessage(cause),
+    });
+}
+function hasRetryableStatus(err) {
+    const status = extractStatus(err);
+    return status !== undefined && isRetryableStatus(status);
+}
+function extractStatus(err) {
+    for (const rec of walkErrorObjects(err)) {
+        for (const value of [rec.status, rec.statusCode]) {
+            if (typeof value === 'number' && Number.isInteger(value))
+                return value;
+        }
+    }
+    return undefined;
+}
+function extractRetryAfterMs(value, clock) {
+    for (const rec of walkErrorObjects(value)) {
+        const fromHeaders = parseRetryAfterHeaders(rec.headers, clock);
+        if (fromHeaders !== undefined)
+            return fromHeaders;
+        if (typeof rec.retryAfterMs === 'number' && Number.isFinite(rec.retryAfterMs))
+            return rec.retryAfterMs;
+    }
+    return undefined;
+}
+/** Same precedence as the provider SDKs: `retry-after-ms`, then `Retry-After` as delta-seconds or an HTTP date. */
+function parseRetryAfterHeaders(headers, clock) {
+    const ms = Number(readHeader(headers, 'retry-after-ms'));
+    if (Number.isFinite(ms) && ms >= 0)
+        return Math.round(ms);
+    const raw = readHeader(headers, 'retry-after');
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.round(seconds * 1000);
+    const date = Date.parse(raw);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - clock.now().getTime());
+}
+function walkErrorObjects(value) {
+    const seen = new Set();
+    const out = [];
+    let current = value;
+    while (current !== undefined && current !== null && typeof current === 'object' && !seen.has(current)) {
+        seen.add(current);
+        out.push(current);
+        current = current.cause;
+    }
+    return out;
+}
+function bodyLooksTransient(err) {
+    const message = getErrorMessage(err);
+    return RATE_LIMIT_BODY.test(message) || OVERLOADED_BODY.test(message);
+}
+//# sourceMappingURL=retry-pre-first-token.js.map

package/dist/stream-errors.d.ts

@@ -53,6 +53,16 @@ export declare class IdleReadTimeoutError extends ClassifiedStreamError {
     readonly code: "network-error";
     constructor(idleMs: number);
 }
+/**
+ * The pre-first-token retry deadline (`withPreFirstTokenRetry`, W-24236393) elapsed before any consumer-visible
+ * part arrived, across all attempts and backoff sleeps. Like {@link IdleReadTimeoutError} it classifies as
+ * {@link NETWORK_ERROR_CODE}; the wrapper has already stopped retrying by the time it is thrown.
+ */
+export declare class PreFirstTokenDeadlineError extends ClassifiedStreamError {
+    readonly name = "PreFirstTokenDeadlineError";
+    readonly code: "network-error";
+    constructor(deadlineMs: 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

@@ -62,6 +62,18 @@ export class IdleReadTimeoutError extends ClassifiedStreamError {
             'treating as a transport fault and tearing down the connection.');
     }
 }
+/**
+ * The pre-first-token retry deadline (`withPreFirstTokenRetry`, W-24236393) elapsed before any consumer-visible
+ * part arrived, across all attempts and backoff sleeps. Like {@link IdleReadTimeoutError} it classifies as
+ * {@link NETWORK_ERROR_CODE}; the wrapper has already stopped retrying by the time it is thrown.
+ */
+export class PreFirstTokenDeadlineError extends ClassifiedStreamError {
+    name = 'PreFirstTokenDeadlineError';
+    code = NETWORK_ERROR_CODE;
+    constructor(deadlineMs) {
+        super(`LLM produced no first token within ${deadlineMs}ms across retries; giving up.`);
+    }
+}
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -37,17 +37,17 @@
     "@mastra/mcp": "^1.18.0",
     "@mastra/memory": "^1.30.0",
     "@mastra/schema-compat": "^1.3.10",
-    "@salesforce/agentic-common": "0.23.0",
+    "@salesforce/agentic-common": "0.24.0",
     "@smithy/eventstream-codec": "^4.5.2",
     "openai": "^7.23.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.97.0"
+    "@salesforce/sfdx-agent-sdk": "0.98.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.97.0",
+    "@salesforce/sfdx-agent-sdk": "0.98.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^5.0.1",
     "@vitest/eslint-plugin": "^1.6.27",