@inflexa-ai/harness 0.18.0 → 0.19.1

package/dist/providers/ai-sdk.js

@@ -1,12 +1,13 @@
-import { generateText, streamText, wrapLanguageModel } from "ai";
+import { generateText, streamText, wrapLanguageModel, } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { APICallError } from "@ai-sdk/provider";
 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
@@ -28,6 +29,11 @@ export const RETRY_MAX_DELAY_MS = 30_000;
  *
  * Lower it per-config for servers that validate `prompt + max_tokens <= context`
  * (vLLM and similar) against a small-context model.
+ *
+ * The openai arm takes no value from this default. `@ai-sdk/openai` clamps
+ * nothing per model, and it puts the number on the wire as it is. Thus a model
+ * whose own cap is smaller answers 400 on each call. That arm sends no ceiling,
+ * and the server then enforces the true cap of the model.
  */
 export const DEFAULT_MAX_OUTPUT_TOKENS = 64_000;
 /**
@@ -189,15 +195,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 +340,63 @@ 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 capabilities = {
+        toolCalling: deps.capabilities?.toolCalling ?? true,
+        // Propagate a picture flag only when the caller states it. An absent
+        // flag stays absent, thus the loop degrades to the next placement for a
+        // wire that carries no picture there.
+        ...(deps.capabilities?.imageToolResults !== undefined ? { imageToolResults: deps.capabilities.imageToolResults } : {}),
+        ...(deps.capabilities?.imageUserMessages !== undefined ? { imageUserMessages: deps.capabilities.imageUserMessages } : {}),
+    };
     const logger = (deps.logger ?? createNoopLogger()).named("providers.ai-sdk");
     const maxOutputTokens = deps.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    // The sentinel hands the SDK no ceiling, thus the request carries none and the
+    // server enforces the cap of the model. One binding feeds the call and the
+    // stream, thus the two cannot disagree about the ceiling of a request.
+    const outputCeiling = maxOutputTokens === "provider-maximum" ? {} : { maxOutputTokens };
+    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 () => {
@@ -350,13 +409,17 @@ export function createAiSdkProvider(deps) {
                         messages: sanitizeMessages(req.messages),
                         tools: req.tools,
                         toolChoice: req.toolChoice ?? "auto",
-                        maxOutputTokens,
+                        ...outputCeiling,
                         stopWhen: [],
                         // The harness envelope owns retries; leaving the SDK default in
                         // place would multiply attempts (10 outer × 3 inner).
                         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 +434,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
@@ -390,16 +453,29 @@ export function createAiSdkProvider(deps) {
                     messages: sanitizeMessages(req.messages),
                     tools: req.tools,
                     toolChoice: req.toolChoice ?? "auto",
-                    maxOutputTokens,
+                    ...outputCeiling,
                     stopWhen: [],
                     maxRetries: 0,
                     headers,
                     abortSignal: signal,
+                    // The fetch guard bounds the wait until the headers. Past the
+                    // headers the SDK owns two bounds: `firstChunkMs` covers the wait
+                    // for the first content chunk, and `chunkMs` covers each later
+                    // gap. The two take the same value, thus each silent interval of
+                    // the stream has the one configured bound. A chunk that carries
+                    // no content, for example a keep-alive comment, produces no part,
+                    // thus it feeds neither bound.
+                    ...(requestTimeoutMs !== undefined ? { timeout: { firstChunkMs: requestTimeoutMs, 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 +484,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 +494,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 +514,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 +542,85 @@ 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();
+        }
+    };
+}
+/**
+ * Bind one explicit `store` directive onto each call of a model.
+ *
+ * The middleware merges the value into the `openai` namespace of
+ * `providerOptions`. It keeps each other namespace, and it keeps each other key
+ * of the `openai` namespace, thus a cache directive of a different vendor rides
+ * through untouched. The arm value wins over a request-level `store`, because
+ * the retention mode belongs to the connection and not to one turn. A thread
+ * that mixes the two modes replays a reference onto an item that the server
+ * never stored.
+ */
+function withStoreDirective(model, store) {
+    return wrapLanguageModel({
+        model,
+        middleware: {
+            transformParams: async ({ params }) => ({
+                ...params,
+                providerOptions: { ...params.providerOptions, openai: { ...params.providerOptions?.openai, store } },
+            }),
+        },
+    });
 }
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
@@ -469,28 +628,78 @@ 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,
         });
+        // The Anthropic Messages wire renders an image block inside a
+        // tool_result, thus the loop can send a picture. A custom baseURL can
+        // front a different backend that stringifies the block. Thus the
+        // harness asserts the capability only for the default endpoint. An
+        // absent flag means "cannot carry", thus a config with a custom baseURL
+        // must declare the capability. A config value overrides this default in
+        // both directions.
+        const pictureDefault = config.baseURL === undefined ? { imageToolResults: true } : {};
         return createAiSdkProvider({
             model: provider.chat(config.model),
             resolveBilling: deps.resolveBilling,
-            capabilities: config.capabilities,
+            capabilities: { ...pictureDefault, ...config.capabilities },
             logger: deps.logger,
             ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
+            ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
+            ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
+        });
+    }
+    if (config.kind === "openai") {
+        const provider = createOpenAI({
+            baseURL: config.baseURL,
+            apiKey: config.apiKey,
+            fetch: effectiveFetch,
+        });
+        // The Responses wire renders an image block inside a function-call
+        // output, thus the loop can send a picture. A custom baseURL can front
+        // a different backend that stringifies the block. Thus the harness
+        // asserts the capability only for the default endpoint. An absent flag
+        // means "cannot carry", thus a config with a custom baseURL must
+        // declare the capability. A config value overrides this default in both
+        // directions.
+        const pictureDefault = config.baseURL === undefined ? { imageToolResults: true } : {};
+        return createAiSdkProvider({
+            // The explicit Responses binding pins the wire here. The bare
+            // factory callable of the package resolves to the same path today,
+            // but nothing in the package holds it there.
+            model: withStoreDirective(provider.responses(config.model), config.store ?? false),
+            resolveBilling: deps.resolveBilling,
+            capabilities: { ...pictureDefault, ...config.capabilities },
+            logger: deps.logger,
+            // The package puts this number on the wire as it is, and it clamps
+            // nothing per model. Thus the shared default of 64000 breaks each call
+            // to a model with a smaller cap, with a 400 that no retry can pass. An
+            // unset config sends no ceiling, and the server holds the reply at the
+            // cap of the model.
+            maxOutputTokens: config.maxOutputTokens ?? "provider-maximum",
+            ...(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 +707,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

@@ -13,6 +13,23 @@ import type { ProviderError } from "./errors.js";
 export type { FinishReason, LanguageModel, ModelMessage, ProviderOptions, ToolSet };
 export interface ProviderCapabilities {
     readonly toolCalling: boolean;
+    /**
+     * Whether the wire can carry a picture inside a tool result. The loop moves a
+     * tool's picture into an image content block on the tool-result message. A
+     * wire that renders that block sets this flag. A wire that stringifies the
+     * block into text leaves it absent, and the loop then drops the picture and
+     * keeps the text, because base64 text floods the context and the model cannot
+     * see it. Absent means "cannot carry", never "unknown".
+     */
+    readonly imageToolResults?: boolean;
+    /**
+     * Whether the wire can carry a picture inside a user message. The loop uses
+     * this placement only when the tool result cannot carry the picture. The tool
+     * result then keeps its JSON text, and one user message after the tool message
+     * of the round carries the bytes. Absent means "cannot carry", never
+     * "unknown".
+     */
+    readonly imageUserMessages?: boolean;
 }
 export interface ChatRequest {
     readonly system: string;
@@ -109,7 +126,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);
+}