@aexhq/sdk 0.40.7 → 0.40.8

package/dist/_contracts/asset-upload-helper.d.ts

@@ -0,0 +1,38 @@
+import { type RetryBackoffConfig } from "./retry-core.js";
+export interface AssetUploadResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    readonly headers?: {
+        get(name: string): string | null;
+    };
+}
+/** Minimal fetch shape for direct-to-storage PUT requests. */
+export type AssetFetch = (input: string, init?: RequestInit) => Promise<AssetUploadResponse>;
+export declare const DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
+export declare const DIRECT_UPLOAD_INITIAL_DELAY_MS = 500;
+export declare const DIRECT_UPLOAD_MAX_DELAY_MS = 5000;
+export declare const DIRECT_UPLOAD_MAX_ELAPSED_MS = 30000;
+export type AssetUploadSleep = (ms: number, signal?: AbortSignal) => Promise<void>;
+export interface AssetUploadRetryOptions {
+    readonly maxAttempts?: number;
+    readonly initialDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly maxElapsedMs?: number;
+    readonly sleep?: AssetUploadSleep;
+    readonly random?: () => number;
+    readonly now?: () => number;
+}
+export interface ResolvedAssetUploadRetryConfig extends RetryBackoffConfig {
+    readonly maxAttempts: number;
+    readonly maxElapsedMs: number;
+}
+export declare function putDirectUploadWithRetry(fetchImpl: AssetFetch, uploadUrl: string, init: RequestInit, options?: AssetUploadRetryOptions): Promise<void>;
+export declare function resolveAssetUploadRetryConfig(options?: AssetUploadRetryOptions): ResolvedAssetUploadRetryConfig;
+export declare function directUploadRetryDelayMs(config: RetryBackoffConfig, attempt: number, random: () => number, retryAfterMs: number | undefined): number;
+export declare function withinDirectUploadRetryBudget(config: Pick<ResolvedAssetUploadRetryConfig, "maxElapsedMs">, startedAt: number, delayMs: number, now: () => number): boolean;
+export declare function isRetryableUploadStatus(status: number): boolean;
+export declare function isRetryableUploadError(err: unknown): boolean;
+export declare function directUploadNetworkError(uploadUrl: string, err: unknown, attempts: number): Error;
+export declare function directUploadResponseError(uploadUrl: string, status: number, detail: string, attempts: number): Error;
+export declare function sanitizeUploadText(text: string): string;

package/dist/_contracts/asset-upload-helper.js

@@ -0,0 +1,111 @@
+import { extractErrorCode, redactUrl } from "./sdk-errors.js";
+import { abortableSleep, computeRetryDelayMs, parseRetryAfterMs } from "./retry-core.js";
+export const DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
+export const DIRECT_UPLOAD_INITIAL_DELAY_MS = 500;
+export const DIRECT_UPLOAD_MAX_DELAY_MS = 5_000;
+export const DIRECT_UPLOAD_MAX_ELAPSED_MS = 30_000;
+export async function putDirectUploadWithRetry(fetchImpl, uploadUrl, init, options = {}) {
+    const config = resolveAssetUploadRetryConfig(options);
+    const sleep = options.sleep ?? abortableSleep;
+    const random = options.random ?? Math.random;
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+        let response;
+        try {
+            response = await fetchImpl(uploadUrl, init);
+        }
+        catch (err) {
+            if (attempt < config.maxAttempts && isRetryableUploadError(err)) {
+                const delay = directUploadRetryDelayMs(config, attempt, random, undefined);
+                if (!withinDirectUploadRetryBudget(config, startedAt, delay, now)) {
+                    throw directUploadNetworkError(uploadUrl, err, attempt);
+                }
+                await sleep(delay, init.signal ?? undefined);
+                continue;
+            }
+            throw directUploadNetworkError(uploadUrl, err, attempt);
+        }
+        if (response.ok)
+            return;
+        const retryAfterMs = parseRetryAfterMs(response.headers?.get("retry-after"), now());
+        if (attempt < config.maxAttempts && isRetryableUploadStatus(response.status)) {
+            const delay = directUploadRetryDelayMs(config, attempt, random, retryAfterMs);
+            if (!withinDirectUploadRetryBudget(config, startedAt, delay, now)) {
+                const detail = await response.text().catch(() => "");
+                throw directUploadResponseError(uploadUrl, response.status, detail, attempt);
+            }
+            await response.text().catch(() => "");
+            await sleep(delay, init.signal ?? undefined);
+            continue;
+        }
+        const detail = await response.text().catch(() => "");
+        throw directUploadResponseError(uploadUrl, response.status, detail, attempt);
+    }
+}
+export function resolveAssetUploadRetryConfig(options = {}) {
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? DIRECT_UPLOAD_MAX_ATTEMPTS));
+    const initialDelayMs = Math.max(0, options.initialDelayMs ?? DIRECT_UPLOAD_INITIAL_DELAY_MS);
+    const maxDelayMs = Math.max(initialDelayMs, options.maxDelayMs ?? DIRECT_UPLOAD_MAX_DELAY_MS);
+    const maxElapsedMs = Math.max(0, options.maxElapsedMs ?? DIRECT_UPLOAD_MAX_ELAPSED_MS);
+    return { maxAttempts, initialDelayMs, maxDelayMs, maxElapsedMs };
+}
+export function directUploadRetryDelayMs(config, attempt, random, retryAfterMs) {
+    return computeRetryDelayMs(config, attempt, random, retryAfterMs);
+}
+export function withinDirectUploadRetryBudget(config, startedAt, delayMs, now) {
+    return now() - startedAt + delayMs <= config.maxElapsedMs;
+}
+export function isRetryableUploadStatus(status) {
+    return status === 408 || status === 425 || status === 429 || (status >= 500 && status <= 599);
+}
+export function isRetryableUploadError(err) {
+    if (isNamedError(err, "AbortError"))
+        return false;
+    return true;
+}
+export function directUploadNetworkError(uploadUrl, err, attempts) {
+    const safeUrl = redactUrl(uploadUrl);
+    const code = extractErrorCode(err);
+    const detail = sanitizeUploadText(errorMessage(err)).slice(0, 500);
+    return new Error(`uploadAsset: direct upload PUT failed for ${safeUrl} after ${attemptsLabel(attempts)}` +
+        (code ? ` (${code})` : "") +
+        (detail ? `: ${detail}` : ""));
+}
+export function directUploadResponseError(uploadUrl, status, detail, attempts) {
+    const safeUrl = redactUrl(uploadUrl);
+    const safeDetail = sanitizeUploadText(detail).slice(0, 500);
+    return new Error(`uploadAsset: direct upload PUT failed for ${safeUrl} with status ${status}` +
+        (attempts > 1 ? ` after ${attemptsLabel(attempts)}` : "") +
+        (safeDetail ? `: ${safeDetail}` : ""));
+}
+export function sanitizeUploadText(text) {
+    return text
+        .replace(/https?:\/\/[^\s<>"'`]+/g, (raw) => redactUrlPreservingTrailingPunctuation(raw))
+        .replace(/\b(?:X-Amz-(?:Algorithm|Credential|Date|Expires|Security-Token|Signature|SignedHeaders)|AWSAccessKeyId|Signature|Credential|Security-Token|AccessKeyId|SecretAccessKey|SessionToken)=([^&\s<>"'`]+)/gi, "[redacted]")
+        .replace(/\bAKIA[0-9A-Z]{8,}\b/g, "[redacted]");
+}
+function attemptsLabel(attempts) {
+    return attempts === 1 ? "1 attempt" : `${attempts} attempts`;
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message || err.name;
+    if (typeof err === "string")
+        return err;
+    return String(err);
+}
+function isNamedError(err, name) {
+    return stringProperty(err, "name") === name;
+}
+function stringProperty(value, key) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const prop = value[key];
+    return typeof prop === "string" && prop.length > 0 ? prop : undefined;
+}
+function redactUrlPreservingTrailingPunctuation(raw) {
+    const trailing = raw.match(/[),.;:!?]+$/)?.[0] ?? "";
+    const candidate = trailing ? raw.slice(0, -trailing.length) : raw;
+    return `${redactUrl(candidate)}${trailing}`;
+}

package/dist/_contracts/internal.d.ts

@@ -1,6 +1,10 @@
+import { type AssetFetch, type AssetUploadRetryOptions } from "./asset-upload-helper.js";
 export * from "./models.js";
 export * from "./post-hook.js";
+export * from "./retry-core.js";
 export * from "./submission.js";
+export { DIRECT_UPLOAD_MAX_ATTEMPTS, DIRECT_UPLOAD_INITIAL_DELAY_MS, DIRECT_UPLOAD_MAX_DELAY_MS, DIRECT_UPLOAD_MAX_ELAPSED_MS, directUploadRetryDelayMs, directUploadNetworkError, directUploadResponseError, isRetryableUploadError, isRetryableUploadStatus, putDirectUploadWithRetry, resolveAssetUploadRetryConfig, withinDirectUploadRetryBudget, sanitizeUploadText } from "./asset-upload-helper.js";
+export type { AssetFetch, AssetUploadResponse, AssetUploadRetryOptions, AssetUploadSleep, ResolvedAssetUploadRetryConfig } from "./asset-upload-helper.js";
 /**
  * Subset of `HttpClient` needed by the asset uploader. Defined structurally so
  * SDK and CLI tests can supply thin stubs without dragging in the full client.
@@ -8,15 +12,6 @@ export * from "./submission.js";
 export interface AssetsHttpClient {
     request<T>(path: string, init?: RequestInit, query?: Record<string, string>): Promise<T>;
 }
-/** Minimal fetch shape for the direct-to-storage PUT. */
-export type AssetFetch = (input: string, init?: RequestInit) => Promise<{
-    readonly ok: boolean;
-    readonly status: number;
-    text(): Promise<string>;
-    readonly headers?: {
-        get(name: string): string | null;
-    };
-}>;
 export interface UploadAssetArgs {
     readonly http: AssetsHttpClient;
     readonly bytes: Uint8Array;
@@ -24,6 +19,7 @@ export interface UploadAssetArgs {
     readonly hash: string;
     readonly contentType?: string;
     readonly fetch?: AssetFetch;
+    readonly retry?: AssetUploadRetryOptions;
 }
 export interface UploadedAsset {
     readonly assetId: string;

package/dist/_contracts/internal.js

@@ -1,4 +1,4 @@
-import { extractErrorCode, redactUrl } from "./sdk-errors.js";
+import { putDirectUploadWithRetry } from "./asset-upload-helper.js";
 // Workspace-internal entry point. Re-exports submission building blocks and
 // hosts small shared helpers so public packages can avoid hand-mirroring
 // behavior. NOT part of the public `@aexhq/contracts` surface; do NOT add this
@@ -6,8 +6,9 @@ import { extractErrorCode, redactUrl } from "./sdk-errors.js";
 // `@aexhq/contracts/internal` subpath.
 export * from "./models.js";
 export * from "./post-hook.js";
+export * from "./retry-core.js";
 export * from "./submission.js";
-const DIRECT_UPLOAD_MAX_ATTEMPTS = 3;
+export { DIRECT_UPLOAD_MAX_ATTEMPTS, DIRECT_UPLOAD_INITIAL_DELAY_MS, DIRECT_UPLOAD_MAX_DELAY_MS, DIRECT_UPLOAD_MAX_ELAPSED_MS, directUploadRetryDelayMs, directUploadNetworkError, directUploadResponseError, isRetryableUploadError, isRetryableUploadStatus, putDirectUploadWithRetry, resolveAssetUploadRetryConfig, withinDirectUploadRetryBudget, sanitizeUploadText } from "./asset-upload-helper.js";
 /**
  * Upload `bytes` to the hosted API's content-addressable asset store via the
  * direct-to-storage presign flow shared by SDK and CLI callers.
@@ -42,11 +43,11 @@ export async function uploadAsset(args) {
         "content-type": args.contentType ?? "application/zip",
         ...(presign.requiredHeaders ?? {})
     };
-    await putWithRetry(doFetch, presign.uploadUrl, {
+    await putDirectUploadWithRetry(doFetch, presign.uploadUrl, {
         method: "PUT",
         headers: putHeaders,
         body: args.bytes
-    });
+    }, args.retry);
     const fin = await args.http.request("/assets/finalize", {
         method: "POST",
         headers: { "content-type": "application/json" },
@@ -73,81 +74,6 @@ function assetIdFromContentHash(contentHash) {
     const hex = contentHash.startsWith("sha256:") ? contentHash.slice("sha256:".length) : contentHash;
     return `asset_${hex}`;
 }
-async function putWithRetry(fetchImpl, uploadUrl, init) {
-    for (let attempt = 1; attempt <= DIRECT_UPLOAD_MAX_ATTEMPTS; attempt++) {
-        let response;
-        try {
-            response = await fetchImpl(uploadUrl, init);
-        }
-        catch (err) {
-            if (attempt < DIRECT_UPLOAD_MAX_ATTEMPTS && isRetryableUploadError(err)) {
-                continue;
-            }
-            throw directUploadNetworkError(uploadUrl, err, attempt);
-        }
-        if (response.ok)
-            return;
-        if (attempt < DIRECT_UPLOAD_MAX_ATTEMPTS && isRetryableUploadStatus(response.status)) {
-            await response.text().catch(() => "");
-            continue;
-        }
-        const detail = await response.text().catch(() => "");
-        throw directUploadResponseError(uploadUrl, response.status, detail, attempt);
-    }
-}
-function isRetryableUploadStatus(status) {
-    return status === 408 || status === 425 || status === 429 || (status >= 500 && status <= 599);
-}
-function isRetryableUploadError(err) {
-    if (isNamedError(err, "AbortError"))
-        return false;
-    return true;
-}
-function directUploadNetworkError(uploadUrl, err, attempts) {
-    const safeUrl = redactUrl(uploadUrl);
-    const code = extractErrorCode(err);
-    const detail = sanitizeUploadText(errorMessage(err)).slice(0, 500);
-    return new Error(`uploadAsset: direct upload PUT failed for ${safeUrl} after ${attemptsLabel(attempts)}` +
-        (code ? ` (${code})` : "") +
-        (detail ? `: ${detail}` : ""));
-}
-function directUploadResponseError(uploadUrl, status, detail, attempts) {
-    const safeUrl = redactUrl(uploadUrl);
-    const safeDetail = sanitizeUploadText(detail).slice(0, 500);
-    return new Error(`uploadAsset: direct upload PUT failed for ${safeUrl} with status ${status}` +
-        (attempts > 1 ? ` after ${attemptsLabel(attempts)}` : "") +
-        (safeDetail ? `: ${safeDetail}` : ""));
-}
-function attemptsLabel(attempts) {
-    return attempts === 1 ? "1 attempt" : `${attempts} attempts`;
-}
-function errorMessage(err) {
-    if (err instanceof Error)
-        return err.message || err.name;
-    if (typeof err === "string")
-        return err;
-    return String(err);
-}
-function isNamedError(err, name) {
-    return stringProperty(err, "name") === name;
-}
-function stringProperty(value, key) {
-    if (!value || typeof value !== "object")
-        return undefined;
-    const prop = value[key];
-    return typeof prop === "string" && prop.length > 0 ? prop : undefined;
-}
-function sanitizeUploadText(text) {
-    return text
-        .replace(/https?:\/\/[^\s<>"'`]+/g, (raw) => redactUrlPreservingTrailingPunctuation(raw))
-        .replace(/\b(?:X-Amz-(?:Algorithm|Credential|Date|Expires|Security-Token|Signature|SignedHeaders)|AWSAccessKeyId|Signature|Credential|Security-Token|AccessKeyId|SecretAccessKey|SessionToken)=([^&\s<>"'`]+)/gi, "[redacted]")
-        .replace(/\bAKIA[0-9A-Z]{8,}\b/g, "[redacted]");
-}
-function redactUrlPreservingTrailingPunctuation(raw) {
-    const trailing = raw.match(/[),.;:!?]+$/)?.[0] ?? "";
-    const candidate = trailing ? raw.slice(0, -trailing.length) : raw;
-    return `${redactUrl(candidate)}${trailing}`;
-}
 function bufferToHex(buffer) {
     const view = new Uint8Array(buffer);
     let out = "";

package/dist/_contracts/operations.d.ts

@@ -115,11 +115,18 @@ export declare function outputLink(http: HttpClient, runId: string, selectorOrQu
 export declare function createOutputLink(http: HttpClient, runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
 export declare function eventArchiveLink(http: HttpClient, runId: string, options?: OutputLinkOptions): Promise<OutputLink>;
 export declare function resolveOutputFileSelector(outputs: readonly Output[], selector: OutputFileSelector, runId?: string): Output;
-export declare function downloadOutput(http: HttpClient, runId: string, selector: OutputFileSelector): Promise<OutputFileDownload>;
+export declare function downloadOutput(http: HttpClient, runId: string, selector: OutputFileSelector, options?: OutputTransferOptions): Promise<OutputFileDownload>;
 /** Byte ceiling for {@link readOutputText} — a hard cap even if a caller asks for more. */
 export declare const READ_OUTPUT_TEXT_MAX_BYTES = 10000000;
 /** Default `maxBytes` for {@link readOutputText} — a chat-sized preview. */
 export declare const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50000;
+/** Default per-attempt timeout while fetching or reading one output body. */
+export declare const OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 15000;
+/** Idempotent output GETs retry once on a transfer timeout. */
+export declare const OUTPUT_FILE_TRANSFER_ATTEMPTS = 2;
+export interface OutputTransferOptions {
+    readonly timeoutMs?: number;
+}
 /**
  * Read ONE output file as byte-capped, decoded UTF-8 text. Built for handing a run
  * deliverable to an LLM tool: it streams the file body and STOPS at `maxBytes`, so
@@ -214,7 +221,7 @@ export declare function download(http: HttpClient, runId: string): Promise<Uint8
  * layout: `<rel>` per file plus a `manifest.json`
  * (`{ runId, namespace: "outputs", outputs[], errors[] }`).
  */
-export declare function downloadOutputs(http: HttpClient, runId: string): Promise<Uint8Array>;
+export declare function downloadOutputs(http: HttpClient, runId: string, options?: OutputTransferOptions): Promise<Uint8Array>;
 /**
  * Download only the event archive (the `events` namespace). Always includes
  * typed `events.jsonl`.

package/dist/_contracts/operations.js

@@ -1,7 +1,7 @@
 import { strToU8, zipSync } from "fflate";
 import { randomUUID } from "node:crypto";
 import { normalizeRunUnit } from "./run-unit.js";
-import { RunConfigValidationError, RunStateError } from "./sdk-errors.js";
+import { AexNetworkError, RunConfigValidationError, RunStateError } from "./sdk-errors.js";
 import { assertRunRecordArchivePublicSafeV1, buildRunRecordDownloadManifestV1 } from "./run-record.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -369,17 +369,22 @@ export function resolveOutputFileSelector(outputs, selector, runId) {
     }
     return { ...selector, id: selector.id };
 }
-export async function downloadOutput(http, runId, selector) {
+export async function downloadOutput(http, runId, selector, options) {
     const output = isPathSelector(selector)
         ? resolveOutputFileSelector(await listOutputs(http, runId), selector, runId)
         : resolveOutputFileSelector([], selector, runId);
-    const { response } = await http.download(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`);
-    return { output, bytes: new Uint8Array(await response.arrayBuffer()) };
+    const timeoutMs = normalizeOutputTransferTimeoutMs(options?.timeoutMs);
+    const path = `/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`;
+    return { output, bytes: await downloadOutputBytesWithRetry(http, path, timeoutMs) };
 }
 /** Byte ceiling for {@link readOutputText} — a hard cap even if a caller asks for more. */
 export const READ_OUTPUT_TEXT_MAX_BYTES = 10_000_000;
 /** Default `maxBytes` for {@link readOutputText} — a chat-sized preview. */
 export const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50_000;
+/** Default per-attempt timeout while fetching or reading one output body. */
+export const OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 15_000;
+/** Idempotent output GETs retry once on a transfer timeout. */
+export const OUTPUT_FILE_TRANSFER_ATTEMPTS = 2;
 /**
  * Read ONE output file as byte-capped, decoded UTF-8 text. Built for handing a run
  * deliverable to an LLM tool: it streams the file body and STOPS at `maxBytes`, so
@@ -394,25 +399,140 @@ export async function readOutputText(http, runId, selector, options) {
     const output = isPathSelector(selector)
         ? resolveOutputFileSelector(await listOutputs(http, runId), selector, runId)
         : resolveOutputFileSelector([], selector, runId);
-    const { response } = await http.download(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`);
-    const capped = await readCappedText(response, maxBytes);
+    const timeoutMs = normalizeOutputTransferTimeoutMs(options?.timeoutMs);
+    const path = `/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`;
+    const capped = await readOutputTextWithRetry(http, path, maxBytes, timeoutMs);
     const text = options?.grep === undefined ? capped.text : grepLines(capped.text, options.grep);
     return { output, text, truncated: capped.truncated, totalBytes: capped.totalBytes };
 }
+async function downloadOutputBytesWithRetry(http, path, timeoutMs) {
+    return outputTransferWithRetry(path, timeoutMs, async () => {
+        const response = await downloadOutputResponse(http, path, timeoutMs);
+        return readResponseBytes(response, timeoutMs);
+    });
+}
+async function readOutputTextWithRetry(http, path, maxBytes, timeoutMs) {
+    return outputTransferWithRetry(path, timeoutMs, async () => {
+        const response = await downloadOutputResponse(http, path, timeoutMs);
+        return readCappedText(response, maxBytes, timeoutMs);
+    });
+}
+async function downloadOutputResponse(http, path, timeoutMs) {
+    const controller = new AbortController();
+    const { response } = await withOutputTransferTimeout(http.download(path, { signal: controller.signal }), timeoutMs, () => controller.abort(), "output response");
+    return response;
+}
+async function outputTransferWithRetry(path, timeoutMs, action) {
+    const startedMs = Date.now();
+    let lastTimeout;
+    for (let attempt = 1; attempt <= OUTPUT_FILE_TRANSFER_ATTEMPTS; attempt += 1) {
+        try {
+            return await action();
+        }
+        catch (err) {
+            if (!(err instanceof OutputTransferTimeoutError))
+                throw err;
+            lastTimeout = err;
+        }
+    }
+    throw new AexNetworkError({
+        method: "GET",
+        host: "",
+        path,
+        cause: lastTimeout ?? new OutputTransferTimeoutError("output transfer", timeoutMs),
+        attempts: OUTPUT_FILE_TRANSFER_ATTEMPTS,
+        elapsedMs: Date.now() - startedMs
+    });
+}
+function normalizeOutputTransferTimeoutMs(value) {
+    if (value === undefined)
+        return OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RunConfigValidationError("outputs.download: timeoutMs must be a positive finite number", {
+            timeoutMs: value
+        });
+    }
+    return Math.max(1, Math.floor(value));
+}
+class OutputTransferTimeoutError extends Error {
+    code = "ETIMEDOUT";
+    constructor(label, timeoutMs) {
+        super(`${label} timed out after ${timeoutMs}ms`);
+        this.name = "OutputTransferTimeoutError";
+    }
+}
+async function withOutputTransferTimeout(promise, timeoutMs, abort, label) {
+    let timedOut = false;
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            timedOut = true;
+            reject(new OutputTransferTimeoutError(label, timeoutMs));
+            queueMicrotask(() => {
+                try {
+                    abort();
+                }
+                catch {
+                    // Best effort: the timeout itself is the user-facing failure.
+                }
+            });
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    catch (err) {
+        if (timedOut && isAbortLikeError(err))
+            throw new OutputTransferTimeoutError(label, timeoutMs);
+        throw err;
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+function isAbortLikeError(err) {
+    const name = err?.name;
+    return name === "AbortError";
+}
+async function readResponseBytes(response, timeoutMs) {
+    const body = response.body;
+    if (!body) {
+        const buffer = await withOutputTransferTimeout(response.arrayBuffer(), timeoutMs, () => { }, "output body");
+        return new Uint8Array(buffer);
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    try {
+        while (true) {
+            const { done, value } = await withOutputTransferTimeout(reader.read(), timeoutMs, () => {
+                void reader.cancel().catch(() => { });
+            }, "output body");
+            if (done)
+                break;
+            if (value && value.byteLength > 0)
+                chunks.push(value);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    return concatBytes(chunks);
+}
 /**
  * Read a streamed response body up to `maxBytes`, decode as UTF-8, and report
  * whether the file was larger than the cap. Prefers the `content-length` header
  * for `totalBytes`; falls back to the bytes actually read. Cancels the stream
  * once the cap is reached so the remainder is never transferred.
  */
-async function readCappedText(response, maxBytes) {
+async function readCappedText(response, maxBytes, timeoutMs) {
     const declaredRaw = response.headers.get("content-length");
     const declared = declaredRaw !== null && /^\d+$/.test(declaredRaw) ? Number(declaredRaw) : undefined;
     const decoder = new TextDecoder("utf-8");
     const body = response.body;
     if (!body) {
         // No streaming body (some fetch polyfills) — buffer, then slice to the cap.
-        const buf = new Uint8Array(await response.arrayBuffer());
+        const buf = new Uint8Array(await withOutputTransferTimeout(response.arrayBuffer(), timeoutMs, () => { }, "output body"));
         const total = declared ?? buf.byteLength;
         return {
             text: decoder.decode(buf.subarray(0, maxBytes)),
@@ -426,7 +546,9 @@ async function readCappedText(response, maxBytes) {
     let sawMore = false;
     try {
         while (read < maxBytes) {
-            const { done, value } = await reader.read();
+            const { done, value } = await withOutputTransferTimeout(reader.read(), timeoutMs, () => {
+                void reader.cancel().catch(() => { });
+            }, "output body");
             if (done)
                 break;
             if (value && value.byteLength > 0) {
@@ -436,13 +558,15 @@ async function readCappedText(response, maxBytes) {
         }
         if (read >= maxBytes) {
             // We hit the cap; peek once more to learn whether bytes remain, then stop.
-            const next = await reader.read();
+            const next = await withOutputTransferTimeout(reader.read(), timeoutMs, () => {
+                void reader.cancel().catch(() => { });
+            }, "output body");
             if (!next.done && next.value && next.value.byteLength > 0)
                 sawMore = true;
         }
     }
     finally {
-        await reader.cancel().catch(() => { });
+        void reader.cancel().catch(() => { });
     }
     const merged = concatBytes(chunks).subarray(0, maxBytes);
     const truncated = declared !== undefined ? declared > maxBytes : read > maxBytes || sawMore;
@@ -578,17 +702,17 @@ export async function getWebhookSigningSecret(http) {
  * surfaced (never silent) while a partially-available run still yields a
  * usable zip.
  */
-async function collectArtifactBytes(http, runId, items, zipPrefix, namespace) {
+async function collectArtifactBytes(http, runId, items, zipPrefix, namespace, timeoutMs = OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS) {
     const entries = [];
     const captured = [];
     const errors = [];
     for (const item of items) {
         const rel = item.filename ?? item.id;
         try {
-            const { response } = await http.download(`/api/runs/${encodeURIComponent(runId)}/${namespace}/${encodeURIComponent(item.id)}/download`);
+            const path = `/api/runs/${encodeURIComponent(runId)}/${namespace}/${encodeURIComponent(item.id)}/download`;
             entries.push({
                 path: `${zipPrefix}${rel}`,
-                bytes: new Uint8Array(await response.arrayBuffer()),
+                bytes: await downloadOutputBytesWithRetry(http, path, timeoutMs),
                 ...(item.contentType !== undefined ? { contentType: item.contentType } : {}),
                 customerContent: true
             });
@@ -843,9 +967,10 @@ export async function download(http, runId) {
  * layout: `<rel>` per file plus a `manifest.json`
  * (`{ runId, namespace: "outputs", outputs[], errors[] }`).
  */
-export async function downloadOutputs(http, runId) {
+export async function downloadOutputs(http, runId, options) {
     const outputs = await listOutputs(http, runId);
-    const { entries, captured, errors } = await collectArtifactBytes(http, runId, outputs, "", "outputs");
+    const timeoutMs = normalizeOutputTransferTimeoutMs(options?.timeoutMs);
+    const { entries, captured, errors } = await collectArtifactBytes(http, runId, outputs, "", "outputs", timeoutMs);
     return zipEntries([
         ...entries,
         jsonEntry("manifest.json", { runId, namespace: "outputs", outputs: captured, errors })

package/dist/_contracts/retry-core.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public-safe retry primitives shared by public packages through the
+ * `@aexhq/contracts/internal` subpath. Keep this module free of hosted
+ * implementation details and do not export it from the public contracts root.
+ */
+export declare const RETRYABLE_HTTP_STATUS: readonly number[];
+export declare const RATE_LIMIT_HTTP_STATUS: readonly number[];
+export interface RetryBackoffConfig {
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+}
+export type RetryRandom = () => number;
+export declare function isRetryableHttpStatus(status: number): boolean;
+export declare function isRateLimitHttpStatus(status: number): boolean;
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds. RFC 7231 permits either
+ * a non-negative integer number of seconds or an HTTP-date.
+ */
+export declare function parseRetryAfterMs(headerValue: string | null | undefined, now?: number): number | undefined;
+/**
+ * Full-jitter exponential backoff: the nominal wait doubles per failed attempt
+ * and the actual delay is sampled uniformly in `[0, nominal]`.
+ */
+export declare function computeRetryBackoffDelayMs(config: RetryBackoffConfig, attemptNumber: number, random: RetryRandom): number;
+/** Combine a server `Retry-After` floor with the jittered backoff delay. */
+export declare function computeRetryDelayMs(config: RetryBackoffConfig, attemptNumber: number, random: RetryRandom, retryAfterMs: number | undefined): number;
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;