@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/providers/ai-sdk.d.ts

@@ -32,6 +32,16 @@ export interface AiSdkProviderDeps {
     readonly logger?: Logger;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /** The retry limit of the harness envelope. Defaults to {@link RETRY_MAX_RETRIES}. */
+    readonly maxRetries?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in milliseconds.
+     * The provider hands the value to the SDK as the bound for each gap between
+     * two content chunks of a stream. The value also names itself in the error of
+     * a stream that the bound stopped. When the field is absent, the provider
+     * hands the SDK no bound.
+     */
+    readonly requestTimeoutMs?: number;
 }
 /**
  * Connection + model configuration for one `ChatProvider`, discriminated by
@@ -52,6 +62,27 @@ export type AiSdkProviderConfig = {
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
 } | {
     readonly kind: "openai-compatible";
     readonly name: string;
@@ -62,6 +93,27 @@ export type AiSdkProviderConfig = {
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
 };
 export interface ConfiguredAiSdkProviderDeps {
     readonly config: AiSdkProviderConfig;
@@ -78,11 +130,36 @@ export interface ConfiguredAiSdkProviderDeps {
  */
 export declare function computeRetryDelayMs(error: unknown, exponentialBackoffDelay: number, random?: () => number): number;
 export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
+/**
+ * Wrap a fetch so that the wait until the response starts does not exceed
+ * `requestTimeoutMs`. The wrapper arms one timer for each fetch call. The timer
+ * runs from the send until the fetch promise settles, and the headers of the
+ * response settle it. On expiry the wrapper aborts a dedicated controller with a
+ * `RequestTimeoutError` reason, and it composes that controller with the caller
+ * signal through `AbortSignal.any`. Thus the caller signal keeps its normal
+ * effect, and a caller abort stays a cancellation.
+ *
+ * The guard bounds the response start only. The SDK bounds each later gap of a
+ * streamed body with its own `chunkMs` setting, thus no timer of the wrapper
+ * survives the headers. Thus a stream with steady content does not trip the
+ * guard, whatever its total length. One fetch call is one attempt, because the
+ * SDK retries are off, thus the window is per attempt.
+ *
+ * When the field is absent, `createConfiguredAiSdkProvider` installs no wrapper,
+ * and the behavior stays byte-identical.
+ */
+export declare function wrapFetchWithRequestTimeout(fetchImpl: FetchLike, requestTimeoutMs: number): FetchLike;
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
  * connection and model. The model is closed into the returned provider here (it
  * is never passed per `ChatRequest`), so N models require N provider
  * instances over one shared connection configuration — one instance serves the
  * single model it was built with.
+ *
+ * When the config sets `requestTimeoutMs`, the provider wraps the effective fetch
+ * (`config.fetch ?? globalThis.fetch`) with the response-start guard, it hands
+ * the value to the stream call as the SDK chunk bound, and it advertises the
+ * value on the returned instance. When the field is absent, it installs no
+ * wrapper, it hands the SDK no bound, and it advertises no value.
  */
 export declare function createConfiguredAiSdkProvider(deps: ConfiguredAiSdkProviderDeps): ChatProvider;

package/dist/providers/ai-sdk.js

@@ -1,4 +1,4 @@
-import { generateText, streamText, wrapLanguageModel } from "ai";
+import { generateText, streamText, wrapLanguageModel, } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { APICallError } from "@ai-sdk/provider";
@@ -6,7 +6,7 @@ import { retryWithExponentialBackoff } from "@ai-sdk/provider-utils";
 import { ResultAsync, err, ok } from "neverthrow";
 import { scopeWorkloadId } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { classifyProviderError, toProviderError } from "./errors.js";
+import { classifyProviderError, RequestTimeoutError, toProviderError } from "./errors.js";
 /**
  * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
  * count: its 2s initial delay and ×2 factor are fixed, it caps neither the
@@ -189,15 +189,20 @@ function unwrapForClassification(e) {
  * that, once retries are exhausted, `toProviderError`'s status walk reaches the
  * true HTTP status instead of stopping at a synthetic wrapper. The attempt
  * counter is per-instance because each call builds its own retry.
+ *
+ * An aborted caller signal also stops the retry. A wall-clock guard of a caller
+ * aborts with a `TimeoutError` reason, which the taxonomy marks as a retryable
+ * timeout. Without this guard the envelope would loop an expiry that the caller
+ * itself declared.
  */
-function createRetry(signal, logger) {
+function createRetry(signal, logger, maxRetries) {
     let retryCount = 0;
     return retryWithExponentialBackoff({
-        maxRetries: RETRY_MAX_RETRIES,
+        maxRetries,
         initialDelayInMs: RETRY_INITIAL_DELAY_MS,
         backoffFactor: RETRY_BACKOFF_FACTOR,
         abortSignal: signal,
-        shouldRetry: (e) => !(e instanceof BillingSeamFailure) && classifyProviderError(e).retryable,
+        shouldRetry: (e) => !(e instanceof BillingSeamFailure) && signal?.aborted !== true && classifyProviderError(e).retryable,
         getDelayInMs: ({ error, exponentialBackoffDelay }) => {
             const delayMs = computeRetryDelayMs(error, exponentialBackoffDelay);
             retryCount += 1;
@@ -329,15 +334,52 @@ function sanitizeMessages(messages) {
     }
     return out;
 }
+/**
+ * Advance the SDK stream to the next text delta.
+ *
+ * The full stream carries one part for each event of a turn, and only a text
+ * part reaches the consumer of the harness. Thus the pull skips each other part.
+ * The `abort` part stops the pull, because the SDK closes the stream directly
+ * after it. Thus a timeout can never end the stream in silence with the text
+ * that arrived before it.
+ */
+async function pullNextDelta(iterator) {
+    for (let next = await iterator.next(); next.done !== true; next = await iterator.next()) {
+        const part = next.value;
+        if (part.type === "text-delta")
+            return { kind: "delta", text: part.text };
+        if (part.type === "abort")
+            return { kind: "aborted", reason: part.reason };
+    }
+    return { kind: "end" };
+}
+/**
+ * The failure that an `abort` part of the SDK stream stands for.
+ *
+ * The part carries a message only, thus the caller signal is the one thing that
+ * separates a cancellation from a timeout. When the caller signal is aborted,
+ * the reason of that signal rides out, and the cancellation path applies
+ * unchanged. Otherwise the SDK chunk bound stopped the stream, and the sentinel
+ * names the configured value for the classifier.
+ */
+function abortedStreamFailure(signal, reason, requestTimeoutMs) {
+    if (signal?.aborted === true)
+        return signal.reason;
+    if (requestTimeoutMs !== undefined)
+        return new RequestTimeoutError(requestTimeoutMs);
+    return new Error(reason ?? "The provider aborted the stream.");
+}
 export function createAiSdkProvider(deps) {
     const capabilities = { toolCalling: deps.capabilities?.toolCalling ?? true };
     const logger = (deps.logger ?? createNoopLogger()).named("providers.ai-sdk");
     const maxOutputTokens = deps.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    const maxRetries = deps.maxRetries ?? RETRY_MAX_RETRIES;
+    const requestTimeoutMs = deps.requestTimeoutMs;
     const requestedModelId = requestedModelIdOf(deps.model);
     routeSdkWarningsTo(logger);
     function chat(req, session, signal) {
         const run = async () => {
-            const retry = createRetry(signal, logger);
+            const retry = createRetry(signal, logger, maxRetries);
             const capture = captureServedModelId(deps.model);
             try {
                 const result = await retry(async () => {
@@ -357,6 +399,10 @@ export function createAiSdkProvider(deps) {
                         maxRetries: 0,
                         headers,
                         abortSignal: signal,
+                        // No SDK timeout rides here. `chunkMs` bounds a stream only,
+                        // thus it is inert on this call. The fetch guard is the full
+                        // bound, because the headers of a non-streaming response arrive
+                        // when the model completes.
                         providerOptions: req.providerOptions,
                     });
                 });
@@ -371,7 +417,7 @@ export function createAiSdkProvider(deps) {
         return new ResultAsync(run());
     }
     async function* chatStream(req, session, signal) {
-        const retry = createRetry(signal, logger);
+        const retry = createRetry(signal, logger, maxRetries);
         const capture = captureServedModelId(deps.model);
         try {
             // Retry covers only stream establishment: streamText defers wire errors
@@ -395,11 +441,22 @@ export function createAiSdkProvider(deps) {
                     maxRetries: 0,
                     headers,
                     abortSignal: signal,
+                    // The SDK bounds each gap between two content chunks of the body.
+                    // Its timer arms at the first part of the provider stream, thus the
+                    // wait until the response starts stays with the fetch guard. A
+                    // chunk that carries no content, for example a keep-alive comment,
+                    // produces no part, thus it does not reset this bound.
+                    ...(requestTimeoutMs !== undefined ? { timeout: { chunkMs: requestTimeoutMs } } : {}),
                     providerOptions: req.providerOptions,
                 });
-                const iterator = result.textStream[Symbol.asyncIterator]();
-                const first = await iterator.next();
-                if (first.done) {
+                const iterator = result.fullStream[Symbol.asyncIterator]();
+                const first = await pullNextDelta(iterator);
+                // The chunk bound can stop the stream before any content arrives. The
+                // throw carries the sentinel, thus the envelope gives the attempt a
+                // fresh window under the retry policy of a connection error.
+                if (first.kind === "aborted")
+                    throw abortedStreamFailure(signal, first.reason, requestTimeoutMs);
+                if (first.kind === "end") {
                     // A doStream promise rejection — the shape a real connection
                     // failure takes — does NOT surface at this first pull: streamText
                     // resolves it `{ done: true }` and defers the rejection to the
@@ -408,8 +465,8 @@ export function createAiSdkProvider(deps) {
                     // retried; a genuine text-less turn resolves them, and the terminal
                     // event is built from these already-resolved values without a
                     // second await. (These promises only settle once the stream is
-                    // fully drained, so they can be awaited here only because the first
-                    // pull already reported the stream done.)
+                    // fully drained, so they can be awaited here only because the pull
+                    // already reported the stream done.)
                     return {
                         kind: "completed",
                         messages: await result.responseMessages,
@@ -418,7 +475,7 @@ export function createAiSdkProvider(deps) {
                         usage: await result.usage,
                     };
                 }
-                return { kind: "streaming", result, iterator, firstDelta: first.value };
+                return { kind: "streaming", result, iterator, firstDelta: first.text };
             });
             if (opened.kind === "completed") {
                 const response = responseFromMessages({
@@ -438,9 +495,14 @@ export function createAiSdkProvider(deps) {
             yield { type: "text-delta", text: firstDelta };
             // Drain the same iterator: past the first delta, errors propagate
             // unchanged (no retry, no re-emit).
-            for (let next = await iterator.next(); !next.done; next = await iterator.next()) {
-                text += next.value;
-                yield { type: "text-delta", text: next.value };
+            for (let pull = await pullNextDelta(iterator); pull.kind !== "end"; pull = await pullNextDelta(iterator)) {
+                // A mid-stream abort ends the turn with an error, never with the
+                // partial text that arrived before it. The catch below builds the
+                // terminal `ProviderError` from the throwable.
+                if (pull.kind === "aborted")
+                    throw abortedStreamFailure(signal, pull.reason, requestTimeoutMs);
+                text += pull.text;
+                yield { type: "text-delta", text: pull.text };
             }
             const response = responseFromMessages({
                 messages: await result.responseMessages,
@@ -461,7 +523,63 @@ export function createAiSdkProvider(deps) {
             throw toProviderError(unwrapForClassification(e), workloadOf(session));
         }
     }
-    return { capabilities, chat, chatStream };
+    // The provider advertises the guard limit on its own instance, thus a
+    // consumer that scales a deadline reads it from the provider in its deps.
+    return { capabilities, chat, chatStream, ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}) };
+}
+/**
+ * Wrap a fetch so that the wait until the response starts does not exceed
+ * `requestTimeoutMs`. The wrapper arms one timer for each fetch call. The timer
+ * runs from the send until the fetch promise settles, and the headers of the
+ * response settle it. On expiry the wrapper aborts a dedicated controller with a
+ * `RequestTimeoutError` reason, and it composes that controller with the caller
+ * signal through `AbortSignal.any`. Thus the caller signal keeps its normal
+ * effect, and a caller abort stays a cancellation.
+ *
+ * The guard bounds the response start only. The SDK bounds each later gap of a
+ * streamed body with its own `chunkMs` setting, thus no timer of the wrapper
+ * survives the headers. Thus a stream with steady content does not trip the
+ * guard, whatever its total length. One fetch call is one attempt, because the
+ * SDK retries are off, thus the window is per attempt.
+ *
+ * When the field is absent, `createConfiguredAiSdkProvider` installs no wrapper,
+ * and the behavior stays byte-identical.
+ */
+export function wrapFetchWithRequestTimeout(fetchImpl, requestTimeoutMs) {
+    return async (input, init) => {
+        const controller = new AbortController();
+        const callerSignal = init?.signal ?? undefined;
+        const timer = setTimeout(() => controller.abort(new RequestTimeoutError(requestTimeoutMs)), requestTimeoutMs);
+        // The harness runs on Node, where a timer has `unref`. Unref the guard
+        // timer, thus an armed guard does not keep a short-lived process alive.
+        // The DOM type of `setTimeout` declares no `unref`, thus guard the call.
+        timer.unref?.();
+        const clear = () => {
+            clearTimeout(timer);
+            // The harness runs on Node, where a caller signal can outlive one fetch
+            // attempt. Remove the abort listener when the attempt settles, thus a
+            // long-lived signal does not retain this closure.
+            callerSignal?.removeEventListener("abort", clear);
+        };
+        // Compose the guard controller with the caller signal, thus either one
+        // can abort the wire, and the abort reason names its own source. A caller
+        // abort also clears the guard timer at once. Thus an armed timer does not
+        // reach a pointless expiry after the caller cancels.
+        const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+        callerSignal?.addEventListener("abort", clear, { once: true });
+        // `timeout: false` is an extension of the fetch init of Bun. Bun cuts a
+        // request that stays idle for 300 seconds, and this key lifts that cut. Node
+        // ignores an unknown member of the init, thus the key is inert there. A
+        // probe on Bun 1.3.14 proved both results. The `RequestInit` type declares
+        // no such member, thus the cast.
+        const forwarded = { ...init, signal, timeout: false };
+        try {
+            return await fetchImpl(input, forwarded);
+        }
+        finally {
+            clear();
+        }
+    };
 }
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
@@ -469,14 +587,22 @@ export function createAiSdkProvider(deps) {
  * is never passed per `ChatRequest`), so N models require N provider
  * instances over one shared connection configuration — one instance serves the
  * single model it was built with.
+ *
+ * When the config sets `requestTimeoutMs`, the provider wraps the effective fetch
+ * (`config.fetch ?? globalThis.fetch`) with the response-start guard, it hands
+ * the value to the stream call as the SDK chunk bound, and it advertises the
+ * value on the returned instance. When the field is absent, it installs no
+ * wrapper, it hands the SDK no bound, and it advertises no value.
  */
 export function createConfiguredAiSdkProvider(deps) {
     const config = deps.config;
+    const requestTimeoutMs = config.requestTimeoutMs;
+    const effectiveFetch = requestTimeoutMs === undefined ? config.fetch : wrapFetchWithRequestTimeout(config.fetch ?? globalThis.fetch, requestTimeoutMs);
     if (config.kind === "anthropic") {
         const provider = createAnthropic({
             baseURL: config.baseURL,
             apiKey: config.apiKey,
-            fetch: config.fetch,
+            fetch: effectiveFetch,
         });
         return createAiSdkProvider({
             model: provider.chat(config.model),
@@ -484,13 +610,15 @@ export function createConfiguredAiSdkProvider(deps) {
             capabilities: config.capabilities,
             logger: deps.logger,
             ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
+            ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
+            ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
         });
     }
     const provider = createOpenAICompatible({
         name: config.name,
         baseURL: config.baseURL,
         apiKey: config.apiKey,
-        fetch: config.fetch,
+        fetch: effectiveFetch,
     });
     return createAiSdkProvider({
         model: provider.chatModel(config.model),
@@ -498,5 +626,7 @@ export function createConfiguredAiSdkProvider(deps) {
         capabilities: config.capabilities,
         logger: deps.logger,
         ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
+        ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
+        ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
     });
 }

package/dist/providers/errors.d.ts

@@ -15,6 +15,20 @@
  * re-authenticating fixes it — which is a different remedy from every other
  * non-retryable 4xx, so it is a different kind.
  */
+/**
+ * The sentinel that the request-timeout guard uses as an abort reason. The guard
+ * arms a timer for each fetch attempt. On expiry the guard aborts the attempt
+ * with this value. The value rides the abort chain, thus the classifier finds it
+ * and marks the attempt as a retryable provider timeout.
+ *
+ * The name is not `AbortError`, thus the abort-detection paths do not swallow a
+ * guard abort as a caller cancellation. The message names the configured value.
+ */
+export declare class RequestTimeoutError extends Error {
+    /** The configured bound for one silent interval, in milliseconds. */
+    readonly requestTimeoutMs: number;
+    constructor(requestTimeoutMs: number);
+}
 export type ProviderErrorKind = "auth" | "budget" | "tenant-blocked" | "provider";
 /**
  * The provider error value channel — a `DomainError`-conforming

package/dist/providers/errors.js

@@ -16,6 +16,24 @@
  * non-retryable 4xx, so it is a different kind.
  */
 import { redactSecrets } from "../input-sanitization.js";
+/**
+ * The sentinel that the request-timeout guard uses as an abort reason. The guard
+ * arms a timer for each fetch attempt. On expiry the guard aborts the attempt
+ * with this value. The value rides the abort chain, thus the classifier finds it
+ * and marks the attempt as a retryable provider timeout.
+ *
+ * The name is not `AbortError`, thus the abort-detection paths do not swallow a
+ * guard abort as a caller cancellation. The message names the configured value.
+ */
+export class RequestTimeoutError extends Error {
+    /** The configured bound for one silent interval, in milliseconds. */
+    requestTimeoutMs;
+    constructor(requestTimeoutMs) {
+        super(`The provider sent no data within the request timeout of ${requestTimeoutMs} ms.`);
+        this.name = "RequestTimeoutError";
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+}
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
  * `ProviderError` is a plain object, not an `Error`, so it cannot be
@@ -46,6 +64,20 @@ export function isProviderError(value) {
 export function toProviderError(e, workload) {
     if (isProviderError(e))
         return e;
+    // A guard abort names the configured value in its message. Compose a message
+    // that also names the workload, thus a reader sees both. This runs before the
+    // status walk, because a guard abort carries no HTTP status. A timeout of the
+    // SDK carries no sentinel, thus it falls to the composed arm below, which
+    // forwards the message of the SDK.
+    const timeout = findRequestTimeout(e);
+    if (timeout !== undefined) {
+        return {
+            type: "provider",
+            retryable: true,
+            message: `The provider sent no data for ${workload} within the request timeout of ${timeout.requestTimeoutMs} ms.`,
+            cause: e,
+        };
+    }
     const { kind, retryable } = classifyProviderError(e);
     const detail = e instanceof Error ? e.message : String(e);
     if (kind === "auth") {
@@ -149,6 +181,22 @@ const CONNECTION_ERROR_CODES = new Set([
     "UND_ERR_SOCKET",
 ]);
 const CONNECTION_ERROR_PATTERN = /fetch failed|socket hang up|network error|connection (?:refused|reset|error|closed)|econnrefused|enotfound|etimedout|terminated/i;
+/**
+ * Walk the `cause` chain up to {@link MAX_CAUSE_HOPS} links, and return the first
+ * result that `probe` gives. `probe` gives a value for a link that matches, or
+ * `undefined` for a link that does not. The walk stops at the first match, at
+ * the hop cap, or at the end of the chain.
+ */
+function findInCauseChain(err, probe) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        const found = probe(cursor);
+        if (found !== undefined)
+            return found;
+        cursor = cursor.cause;
+    }
+    return undefined;
+}
 /**
  * Walk the `cause` chain for the first numeric HTTP status. The single status
  * walker: `classifyProviderError` keys on what this returns, so a caller asking
@@ -156,16 +204,14 @@ const CONNECTION_ERROR_PATTERN = /fetch failed|socket hang up|network error|conn
  * than re-implement the traversal.
  */
 export function extractStatus(err) {
-    let cursor = err;
-    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
-        const e = cursor;
+    return findInCauseChain(err, (link) => {
+        const e = link;
         if (typeof e.status === "number")
             return e.status;
         if (typeof e.statusCode === "number")
             return e.statusCode;
-        cursor = e.cause;
-    }
-    return undefined;
+        return undefined;
+    });
 }
 /**
  * Walk the `cause` chain for the first captured provider response body.
@@ -186,23 +232,54 @@ function extractResponseBody(err) {
     }
     return undefined;
 }
+/**
+ * Walk the `cause` chain for the request-timeout sentinel. The guard aborts a
+ * fetch with a `RequestTimeoutError`. The SDK carries the abort reason down the
+ * `cause` chain, thus the sentinel can sit one or more hops down.
+ */
+function findRequestTimeout(err) {
+    return findInCauseChain(err, (link) => {
+        if (link instanceof RequestTimeoutError)
+            return link;
+        // A duplicate class identity across a realm boundary fails `instanceof`,
+        // thus match the name and the field as a fallback.
+        const e = link;
+        if (e.name === "RequestTimeoutError" && typeof e.requestTimeoutMs === "number")
+            return link;
+        return undefined;
+    });
+}
+/**
+ * The name of the abort reason that the `timeout` setting of the SDK raises. The
+ * SDK bounds each gap between two content chunks of a stream. On expiry it
+ * aborts the call with a bare `DOMException` that has this name, no cause, and
+ * no HTTP status. The message of that `DOMException` names the configured value.
+ */
+const SDK_TIMEOUT_ERROR_NAME = "TimeoutError";
+/**
+ * Walk the `cause` chain for the timeout that the SDK raises. The `DOMException`
+ * carries no field of its own, thus the name is the one signal. The SDK carries
+ * an abort reason down the `cause` chain, thus the reason can sit one or more
+ * hops down.
+ */
+function findSdkTimeout(err) {
+    return findInCauseChain(err, (link) => {
+        const e = link;
+        return e.name === SDK_TIMEOUT_ERROR_NAME ? link : undefined;
+    });
+}
 /** Does any link of the `cause` chain look like a transport-level failure? */
 function looksLikeConnectionError(err) {
-    let cursor = err;
-    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
-        const e = cursor;
-        if (typeof e.code === "string" && CONNECTION_ERROR_CODES.has(e.code)) {
+    return (findInCauseChain(err, (link) => {
+        const e = link;
+        if (typeof e.code === "string" && CONNECTION_ERROR_CODES.has(e.code))
             return true;
-        }
-        if (typeof e.name === "string" && /^APIConnection/.test(e.name)) {
+        if (typeof e.name === "string" && /^APIConnection/.test(e.name))
             return true;
-        }
-        if (typeof e.message === "string" && CONNECTION_ERROR_PATTERN.test(e.message)) {
+        if (typeof e.message === "string" && CONNECTION_ERROR_PATTERN.test(e.message))
             return true;
-        }
-        cursor = e.cause;
-    }
-    return false;
+        return undefined;
+    }) ?? false);
 }
 /**
  * Classify a provider failure by origin.
@@ -214,6 +291,14 @@ function looksLikeConnectionError(err) {
  * - Other `4xx` and parse / unknown errors → `provider`, not retryable.
  */
 export function classifyProviderError(e) {
+    // The request-timeout guard aborts an attempt with a typed sentinel, and the
+    // chunk bound of the SDK aborts one with a `TimeoutError`. Each classifies as
+    // a retryable provider timeout, thus the envelope retries it under the same
+    // policy as a connection error. This runs before the status and the
+    // connection paths, because a timeout carries no HTTP status, and it must not
+    // fall to a non-retryable path.
+    if (findRequestTimeout(e) !== undefined || findSdkTimeout(e) !== undefined)
+        return { kind: "provider", retryable: true };
     const status = extractStatus(e);
     // `auth` is its own kind rather than a plain non-retryable 4xx because the
     // remedy is categorically different: the request was well-formed and the

package/dist/providers/types.d.ts

@@ -109,7 +109,23 @@ export interface AgentChat {
 }
 export interface ChatProvider extends AgentChat {
     chatStream(req: ChatRequest, session: AgentSession, signal?: AbortSignal): AsyncIterable<ChatStreamEvent>;
+    /**
+     * The request-timeout limit that this provider enforces, in milliseconds, or
+     * absent when it enforces none. The value bounds each silent interval of a
+     * request attempt: the wait until the response starts, and each gap between
+     * two content chunks of a stream. A consumer that scales a deadline reads this
+     * value from the provider instance, not from a harness constant.
+     */
+    readonly requestTimeoutMs?: number;
 }
+/**
+ * The effective deadline in milliseconds for a provider-bound operation.
+ *
+ * An explicit value wins. Absent an explicit value, the deadline is the maximum
+ * of `floorMs` and the request-timeout limit that the provider advertises. Thus
+ * a configured request timeout can raise the floor. It cannot lower the floor.
+ */
+export declare function effectiveDeadlineMs(provider: Pick<ChatProvider, "requestTimeoutMs">, floorMs: number, explicitMs?: number): number;
 export interface EmbeddingProvider {
     /**
      * Width of every vector `embed` returns. The write-side index paths create

package/dist/providers/types.js

@@ -6,4 +6,13 @@
  * attribution is resolved lazily at the provider wire boundary.
  */
 const _assertChatUsageFields = true;
-export {};
+/**
+ * The effective deadline in milliseconds for a provider-bound operation.
+ *
+ * An explicit value wins. Absent an explicit value, the deadline is the maximum
+ * of `floorMs` and the request-timeout limit that the provider advertises. Thus
+ * a configured request timeout can raise the floor. It cannot lower the floor.
+ */
+export function effectiveDeadlineMs(provider, floorMs, explicitMs) {
+    return explicitMs ?? Math.max(floorMs, provider.requestTimeoutMs ?? 0);
+}