@aexhq/sdk 0.40.6 → 0.40.8

package/README.md

@@ -1,159 +1,159 @@
----
-title: aex
----
-
-# @aexhq/sdk
-
-aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
-
-The package ships:
-
-- `Aex` for sessions, one-shot runs, inspect, download, cancel, and delete.
-- `sessions` / `openSession()` for durable, resumable agent sessions.
-- Typed run primitives: `Models`, `Providers`, `Sizes`, `Skill`, `Tool` / `Tools`, `AgentsMd`, `File`, `McpServer`, and `Secret`.
-- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, and whoami operations.
-
-## Install
-
-```bash
-npm i @aexhq/sdk
-```
-
-This installs the TypeScript SDK exports and the bundled `aex` CLI. The CLI
-ships inside the package — invoke it with `npx aex …` after a local install, or
-`npm i -g @aexhq/sdk` to put a bare `aex` on your PATH. Set both credentials
-before running the examples: `AEX_API_KEY` authenticates to aex, and
-`ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
-
-```bash
-export AEX_API_KEY="<your-aex-api-key>"
-export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
-```
-
-## First Session
-
-```ts
-import { Aex, Models, Sizes } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-
-const session = await aex.openSession({
-  model: Models.CLAUDE_HAIKU_4_5,
-  system: "You are a concise engineering assistant.",
-  runtime: Sizes.SHARED_0_25X_1GB,
-  // Default is "3m"; set it explicitly when you want a different idle window.
-  overrides: { idleTtl: "3m" },
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-
-// done() awaits settle by default, so status is the terminal outcome
-// ("succeeded"), and costUsd/usage are populated.
-const first = await session.send("Summarize this repo.").done();
-console.log(first.status, first.costUsd, first.text);
-
-const resumed = await aex.openSession(session.id);
-await resumed.send("Continue with the follow-up validation.").done();
-```
-
-Need a one-shot convenience? `run()` opens a session, sends `message` as one
-turn, and returns the collected result. The returned `runId` is the session id,
-so it can be resumed later with `openSession(runId)`.
-
-```ts
-const result = await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-  message: "Write the report and save outputs."
-});
-
-console.log(result.runId, result.status, result.text);
-```
-
-For multiple providers, include each BYOK key in `apiKeys`:
-
-```ts
-await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: {
-    anthropic: process.env.ANTHROPIC_API_KEY!,
-    openai: process.env.OPENAI_API_KEY!
-  },
-  message: "Delegate research to a subagent."
-});
-```
-
-The same request can run from the bundled CLI (`npx aex` on a local install):
-
-```bash
-npx aex run \
-  --api-key "$AEX_API_KEY" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --model claude-haiku-4-5 \
-  --prompt "Write the report and save outputs." \
-  --follow
-```
-
-## CLI: login, discovery, typed errors
-
-Stop re-passing `--api-key` on every command — log in once and the token (plus
-your default `--aex-url`) is persisted to a `0600` config file
-(`$XDG_CONFIG_HOME/aex/config.json` or `~/.config/aex/config.json`; `%APPDATA%\aex\config.json`
-on Windows). An explicit `--api-key` flag always overrides the stored one.
-
-```bash
-npx aex login --api-key "$AEX_API_KEY" [--aex-url https://api.aex.dev]
-npx aex whoami            # no --api-key needed after login
-npx aex whoami --json     # machine-readable workspace + scopes + limits
-npx aex auth status       # show the resolved config (the token value is never printed)
-npx aex logout            # clear the stored token
-```
-
-Discover the closed sets the platform accepts — no token, no network (human table
-by default, machine JSON under `--json`). Per-verb `--help` is also key-free:
-
-```bash
-npx aex models list           # canonical models + their default provider
-npx aex providers list        # providers + the models each serves
-npx aex tools list            # complete builtin tool set
-npx aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
-npx aex run --help            # flags for one verb (no API key required)
-```
-
-Errors are typed and actionable. Every `openSession()` / `run()` config-validation
-failure throws a `RunConfigValidationError` (`err.code === "RUN_CONFIG_INVALID"`)
-you can `catch` by code; CLI failures print a JSON envelope carrying the HTTP
-`status`, a one-line `remedy`, and the `runId` where known, and a wrong `--model`,
-`--provider`, or `--runtime-size` gets a "did you mean?" suggestion.
-
-## Continue with sessions
-
-Use sessions for conversational flows. `run()` is the one-shot convenience; a
-`SessionHandle` is the lower-level surface when you want multiple turns,
-streaming, messages, events, outputs, or downloads.
-
-```ts
-const session = await aex.openSession(result.runId);
-const next = await session.send("Turn this into a checklist.").done();
-console.log(next.text);
-
-const messages = await session.messages().list();
-const outputs = await aex.sessions.outputs(session.id).list();
-```
-
-## Feature Areas
-
-- **Agent runtime:** managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents.
-- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
-- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, environment variables, packages, and networking controls.
-- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
-- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
-- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes.
-
-## Docs
-
-- [Quickstart](docs/quickstart.md)
-- [Run configuration](docs/run-config.md)
-- [Composition](docs/concepts/composition.md)
-- [Secrets](docs/secrets.md)
-- [Limits](docs/limits.md)
-- [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)
+---
+title: aex
+---
+
+# @aexhq/sdk
+
+aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
+
+The package ships:
+
+- `Aex` for sessions, one-shot runs, inspect, download, cancel, and delete.
+- `sessions` / `openSession()` for durable, resumable agent sessions.
+- Typed run primitives: `Models`, `Providers`, `Sizes`, `Skill`, `Tool` / `Tools`, `AgentsMd`, `File`, `McpServer`, and `Secret`.
+- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, and whoami operations.
+
+## Install
+
+```bash
+npm i @aexhq/sdk
+```
+
+This installs the TypeScript SDK exports and the bundled `aex` CLI. The CLI
+ships inside the package — invoke it with `npx aex …` after a local install, or
+`npm i -g @aexhq/sdk` to put a bare `aex` on your PATH. Set both credentials
+before running the examples: `AEX_API_KEY` authenticates to aex, and
+`ANTHROPIC_API_KEY` is your BYOK provider key for Claude.
+
+```bash
+export AEX_API_KEY="<your-aex-api-key>"
+export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
+```
+
+## First Session
+
+```ts
+import { Aex, Models, Sizes } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_KEY!);
+
+const session = await aex.openSession({
+  model: Models.CLAUDE_HAIKU_4_5,
+  system: "You are a concise engineering assistant.",
+  runtime: Sizes.SHARED_0_25X_1GB,
+  // Default is "3m"; set it explicitly when you want a different idle window.
+  overrides: { idleTtl: "3m" },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+// done() awaits settle by default, so status is the terminal outcome
+// ("succeeded"), and costUsd/usage are populated.
+const first = await session.send("Summarize this repo.").done();
+console.log(first.status, first.costUsd, first.text);
+
+const resumed = await aex.openSession(session.id);
+await resumed.send("Continue with the follow-up validation.").done();
+```
+
+Need a one-shot convenience? `run()` opens a session, sends `message` as one
+turn, and returns the collected result. The returned `runId` is the session id,
+so it can be resumed later with `openSession(runId)`.
+
+```ts
+const result = await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
+  message: "Write the report and save outputs."
+});
+
+console.log(result.runId, result.status, result.text);
+```
+
+For multiple providers, include each BYOK key in `apiKeys`:
+
+```ts
+await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: {
+    anthropic: process.env.ANTHROPIC_API_KEY!,
+    openai: process.env.OPENAI_API_KEY!
+  },
+  message: "Delegate research to a subagent."
+});
+```
+
+The same request can run from the bundled CLI (`npx aex` on a local install):
+
+```bash
+npx aex run \
+  --api-key "$AEX_API_KEY" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --prompt "Write the report and save outputs." \
+  --follow
+```
+
+## CLI: login, discovery, typed errors
+
+Stop re-passing `--api-key` on every command — log in once and the token (plus
+your default `--aex-url`) is persisted to a `0600` config file
+(`$XDG_CONFIG_HOME/aex/config.json` or `~/.config/aex/config.json`; `%APPDATA%\aex\config.json`
+on Windows). An explicit `--api-key` flag always overrides the stored one.
+
+```bash
+npx aex login --api-key "$AEX_API_KEY" [--aex-url https://api.aex.dev]
+npx aex whoami            # no --api-key needed after login
+npx aex whoami --json     # machine-readable workspace + scopes + limits
+npx aex auth status       # show the resolved config (the token value is never printed)
+npx aex logout            # clear the stored token
+```
+
+Discover the closed sets the platform accepts — no token, no network (human table
+by default, machine JSON under `--json`). Per-verb `--help` is also key-free:
+
+```bash
+npx aex models list           # canonical models + their default provider
+npx aex providers list        # providers + the models each serves
+npx aex tools list            # complete builtin tool set
+npx aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
+npx aex run --help            # flags for one verb (no API key required)
+```
+
+Errors are typed and actionable. Every `openSession()` / `run()` config-validation
+failure throws a `RunConfigValidationError` (`err.code === "RUN_CONFIG_INVALID"`)
+you can `catch` by code; CLI failures print a JSON envelope carrying the HTTP
+`status`, a one-line `remedy`, and the `runId` where known, and a wrong `--model`,
+`--provider`, or `--runtime-size` gets a "did you mean?" suggestion.
+
+## Continue with sessions
+
+Use sessions for conversational flows. `run()` is the one-shot convenience; a
+`SessionHandle` is the lower-level surface when you want multiple turns,
+streaming, messages, events, outputs, or downloads.
+
+```ts
+const session = await aex.openSession(result.runId);
+const next = await session.send("Turn this into a checklist.").done();
+console.log(next.text);
+
+const messages = await session.messages().list();
+const outputs = await aex.sessions.outputs(session.id).list();
+```
+
+## Feature Areas
+
+- **Agent runtime:** managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents.
+- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
+- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, environment variables, packages, and networking controls.
+- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
+- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
+- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes.
+
+## Docs
+
+- [Quickstart](docs/quickstart.md)
+- [Run configuration](docs/run-config.md)
+- [Composition](docs/concepts/composition.md)
+- [Secrets](docs/secrets.md)
+- [Limits](docs/limits.md)
+- [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)

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`.