@aexhq/sdk 0.37.2 → 0.37.4

package/dist/_contracts/event-stream-client.d.ts

@@ -71,6 +71,17 @@ export interface CoordinatorStreamOptions {
      * watchdog → quiet runs may reconnect).
      */
     readonly pingIntervalMs?: number;
+    /**
+     * Event-quiet recheck window. A pong proves the SOCKET is alive, not the
+     * delivery pipeline behind it — a server-side subscription that died (reaped
+     * connection row, wedged fan-out) keeps answering pings while never delivering
+     * another event, so the idle watchdog alone would hang one frame short of the
+     * terminal forever. If no REAL event frame arrives within this many ms the
+     * client silently reconnects (resume from cursor) — the replay-on-connect path
+     * reads the event store directly, so a dead subscription self-heals. Default
+     * 90s. Set 0 to disable.
+     */
+    readonly eventQuietRecheckMs?: number;
 }
 export declare function streamCoordinatorEvents(opts: CoordinatorStreamOptions): AsyncGenerator<AexEvent, void, void>;
 /** Async-iterable filter — keep only events matching the predicate. */

package/dist/_contracts/event-stream-client.js

@@ -41,6 +41,8 @@ const COORDINATOR_PING = "aex:ping";
 const DEFAULT_IDLE_TIMEOUT_MS = 45_000;
 /** Default client keep-alive ping cadence. */
 const DEFAULT_PING_INTERVAL_MS = 15_000;
+/** Default event-quiet recheck window (a silent reconnect, so the cost of a false positive is small). */
+const DEFAULT_EVENT_QUIET_RECHECK_MS = 90_000;
 export async function* streamCoordinatorEvents(opts) {
     const makeWs = opts.webSocketFactory ?? ((url) => new WebSocket(url));
     const isTerminal = opts.isTerminal ?? isTerminalType;
@@ -48,6 +50,7 @@ export async function* streamCoordinatorEvents(opts) {
     const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
     const idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
     const pingIntervalMs = opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+    const eventQuietRecheckMs = opts.eventQuietRecheckMs ?? DEFAULT_EVENT_QUIET_RECHECK_MS;
     let cursor = (opts.from ?? 0) - 1;
     let attempts = 0;
     let done = false;
@@ -70,6 +73,7 @@ export async function* streamCoordinatorEvents(opts) {
         };
         let idleTimer = null;
         let pingTimer = null;
+        let quietTimer = null;
         const stopTimers = () => {
             if (idleTimer !== null) {
                 clearTimeout(idleTimer);
@@ -79,6 +83,10 @@ export async function* streamCoordinatorEvents(opts) {
                 clearInterval(pingTimer);
                 pingTimer = null;
             }
+            if (quietTimer !== null) {
+                clearTimeout(quietTimer);
+                quietTimer = null;
+            }
         };
         // Re-arm on every inbound frame. On expiry the socket is presumed half-open
         // → close it and let the loop fall through to reconnect (resume from cursor).
@@ -97,6 +105,23 @@ export async function* streamCoordinatorEvents(opts) {
                 wake();
             }, idleTimeoutMs);
         };
+        // Re-arm only on REAL event frames. On expiry: silent reconnect (resume from
+        // cursor) — self-heals a dead server-side subscription a pong can't expose.
+        const armQuiet = () => {
+            if (eventQuietRecheckMs <= 0)
+                return;
+            if (quietTimer !== null)
+                clearTimeout(quietTimer);
+            quietTimer = setTimeout(() => {
+                quietTimer = null;
+                if (closed)
+                    return;
+                closed = true;
+                disconnectReason = "quiet_recheck";
+                closeQuietly(ws);
+                wake();
+            }, eventQuietRecheckMs);
+        };
         ws.addEventListener("open", () => {
             armIdle();
             if (pingIntervalMs > 0 && typeof ws.send === "function") {
@@ -117,9 +142,12 @@ export async function* streamCoordinatorEvents(opts) {
                 return;
             try {
                 const evt = JSON.parse(data);
-                if (typeof evt.sequence === "number" && evt.sequence > cursor) {
-                    queue.push(evt);
-                    wake();
+                if (typeof evt.sequence === "number") {
+                    armQuiet(); // a real event frame proves the delivery pipeline, not just the socket
+                    if (evt.sequence > cursor) {
+                        queue.push(evt);
+                        wake();
+                    }
                 }
             }
             catch {
@@ -152,8 +180,10 @@ export async function* streamCoordinatorEvents(opts) {
         };
         opts.signal?.addEventListener("abort", onAbort, { once: true });
         // Arm immediately: a connect that never reaches "open" (and fakes that
-        // never emit it) must still time out rather than hang forever.
+        // never emit it) must still time out rather than hang forever. The quiet
+        // recheck arms here too so a socket fed only by pongs still recycles.
         armIdle();
+        armQuiet();
         try {
             while (true) {
                 while (queue.length > 0) {
@@ -177,6 +207,12 @@ export async function* streamCoordinatorEvents(opts) {
         finally {
             stopTimers();
             opts.signal?.removeEventListener("abort", onAbort);
+            // A caller that `break`s the iterator triggers the generator's `return()`,
+            // which lands here with the socket still OPEN (the yield was suspended, no
+            // terminal/abort/transport-close ran). Close it so an early break never
+            // leaks a live WebSocket. Idempotent: the terminal/abort/reconnect paths
+            // have already closed it, and closeQuietly swallows a double close.
+            closeQuietly(ws);
         }
         if (done || opts.signal?.aborted)
             return;
@@ -188,7 +224,11 @@ export async function* streamCoordinatorEvents(opts) {
             console.warn(`[aex] event stream gave up after ${maxReconnects} reconnect attempt(s) (last: ${disconnectReason || "unknown"}); ended before a terminal event at seq ${cursor + 1}`);
             return;
         }
-        console.warn(`[aex] event stream disconnected (${disconnectReason || "unknown"}); reconnecting attempt ${attempts} from seq ${cursor + 1}`);
+        // The quiet recheck is a routine self-heal on a legitimately quiet stream —
+        // reconnecting silently keeps a long tool call from spamming the console.
+        if (disconnectReason !== "quiet_recheck") {
+            console.warn(`[aex] event stream disconnected (${disconnectReason || "unknown"}); reconnecting attempt ${attempts} from seq ${cursor + 1}`);
+        }
         await sleep(reconnectDelayMs, opts.signal);
     }
 }

package/dist/_contracts/http.js

@@ -1,4 +1,4 @@
-import { AexApiError } from "./sdk-errors.js";
+import { AexApiError, AexError, AexNetworkError, redactUrl } from "./sdk-errors.js";
 import { AEX_DEFAULT_BASE_URL } from "./stable.js";
 /**
  * Thin transport used by every BFF-bound operation. The SDK class and
@@ -17,7 +17,13 @@ export class HttpClient {
         }
         const raw = options.baseUrl ?? AEX_DEFAULT_BASE_URL;
         const normalized = raw.endsWith("/") ? raw : `${raw}/`;
-        this.#baseUrl = new URL(normalized);
+        try {
+            this.#baseUrl = new URL(normalized);
+        }
+        catch (err) {
+            throw new Error(`HttpClient: invalid aex baseUrl ${JSON.stringify(redactUrl(raw))} — ` +
+                `expected an absolute URL like "${AEX_DEFAULT_BASE_URL}"`, { cause: err });
+        }
         this.#apiToken = options.apiToken;
         this.#fetch = options.fetch ?? fetch;
         this.#debug = options.debug;
@@ -46,11 +52,18 @@ export class HttpClient {
             }
         }
         const startedMs = Date.now();
-        const response = await this.#fetch(url, { ...init, headers });
+        let response;
+        try {
+            response = await this.#fetch(url, { ...init, headers });
+        }
+        catch (err) {
+            throw toNetworkError(init.method, url, err);
+        }
         this.#trace(init.method, url, response.status, startedMs);
         const body = await readJson(response);
         if (!response.ok) {
-            throw new AexApiError(response.status, extractErrorMessage(body), body);
+            const errorBody = withResponseRequestId(body, response.headers);
+            throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
         }
         return body;
     }
@@ -64,15 +77,41 @@ export class HttpClient {
             ...normalizeHeaders(init.headers)
         };
         const startedMs = Date.now();
-        const response = await this.#fetch(url, { ...init, headers });
+        let response;
+        try {
+            response = await this.#fetch(url, { ...init, headers });
+        }
+        catch (err) {
+            throw toNetworkError(init.method, url, err);
+        }
         this.#trace(init.method, url, response.status, startedMs);
         if (!response.ok) {
             const body = await readJson(response);
-            throw new AexApiError(response.status, extractErrorMessage(body), body);
+            const errorBody = withResponseRequestId(body, response.headers);
+            throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
         }
         return { response };
     }
 }
+/**
+ * Wrap a fetch rejection into an {@link AexNetworkError} carrying the
+ * request's method + redacted host/path. Caller-initiated aborts and
+ * already-structured aex errors (e.g. a retry layer's AexRateLimitError or
+ * AexNetworkError) pass through untouched.
+ */
+function toNetworkError(method, url, err) {
+    if (err instanceof AexError)
+        return err;
+    // `DOMException` is not an `Error` subclass on every runtime, so match aborts by name.
+    if (err?.name === "AbortError")
+        return err;
+    return new AexNetworkError({
+        method: (method ?? "GET").toUpperCase(),
+        host: url.host,
+        path: url.pathname,
+        cause: err
+    });
+}
 function normalizeHeaders(headers) {
     if (!headers)
         return {};
@@ -93,11 +132,44 @@ async function readJson(response) {
         return { raw: text };
     }
 }
+function withResponseRequestId(body, headers) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return body;
+    const record = body;
+    if (typeof record.requestId === "string" && record.requestId.trim())
+        return body;
+    const requestId = responseRequestId(headers);
+    return requestId ? { ...record, requestId } : body;
+}
+function responseRequestId(headers) {
+    for (const name of ["x-request-id", "request-id"]) {
+        const value = headers.get(name)?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
 function extractErrorMessage(body) {
     if (body && typeof body === "object") {
         const obj = body;
-        if (typeof obj.error === "string")
+        if (typeof obj.error === "string") {
+            // A 409 `session_busy` body carries the session's CURRENT status.
+            // Surface it: a send to a deleted (or cancelling/suspending) session
+            // otherwise reads as merely "busy", which is misleading for a session
+            // that will never accept a turn again.
+            const status = body.status;
+            if (obj.error === "session_busy" && typeof status === "string") {
+                return `session_busy (session status: ${status})`;
+            }
+            // Most aex API rejections are `{error: <code>, message: <human detail>}`.
+            // Keep the stable code first, but don't drop the server's actionable
+            // detail (e.g. asset_snapshot_source_missing's "upload and finalize it
+            // before referencing it").
+            if (typeof obj.message === "string" && obj.message.length > 0 && obj.message !== obj.error) {
+                return `${obj.error}: ${obj.message}`;
+            }
             return obj.error;
+        }
         if (obj.error && typeof obj.error === "object" && "message" in obj.error) {
             const message = obj.error.message;
             if (typeof message === "string")

package/dist/_contracts/operations.js

@@ -54,7 +54,34 @@ export async function listRuns(http, query) {
         params.limit = String(query.limit);
     if (query?.cursor !== undefined)
         params.cursor = query.cursor;
-    return http.request("/api/runs", {}, params);
+    const page = await http.request("/api/runs", {}, params);
+    // Defensive contract enforcement: some deployed planes leak non-run marker
+    // rows (settle-time ledger/spendmark items) into the run-list index. Those
+    // phantoms carry only { id, createdAt } and would surface as duplicate,
+    // status-less RunSummary entries. Drop anything missing the fields
+    // RunSummary declares required, so callers can trust the published type.
+    // The same enforcement covers `costUsd`: deployed planes serve `null` for
+    // runs with no settled telemetry, but RunSummary declares `costUsd?: number`
+    // — normalize `null` to absent so typed callers never see it.
+    let changed = false;
+    const runs = [];
+    for (const run of page.runs) {
+        if (typeof run.id !== "string" ||
+            typeof run.status !== "string" ||
+            typeof run.createdAt !== "string" ||
+            typeof run.updatedAt !== "string") {
+            changed = true;
+            continue;
+        }
+        if (typeof run.costUsd !== "number" && run.costUsd !== undefined) {
+            const { costUsd: _dropped, ...rest } = run;
+            runs.push(rest);
+            changed = true;
+            continue;
+        }
+        runs.push(run);
+    }
+    return changed ? { ...page, runs } : page;
 }
 function idempotencyHeaders(options) {
     return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : undefined;
@@ -197,12 +224,22 @@ export async function outputLink(http, runId, selectorOrQuery, options) {
         method: "POST",
         body: JSON.stringify({ expiresInSeconds })
     });
+    const effectiveExpiresIn = result.expiresInSeconds ?? expiresInSeconds;
     return {
         ...result,
-        expiresInSeconds: result.expiresInSeconds ?? expiresInSeconds,
+        expiresInSeconds: effectiveExpiresIn,
+        expiresAt: result.expiresAt ?? syntheticExpiresAt(effectiveExpiresIn),
         output: result.output ?? output
     };
 }
+/**
+ * The hosted API returns `{ url, expiresInSeconds }` without an absolute
+ * timestamp; the documented `link.expiresAt` is synthesized client-side from
+ * the mint time so it is always present on a returned link.
+ */
+function syntheticExpiresAt(expiresInSeconds) {
+    return new Date(Date.now() + expiresInSeconds * 1000).toISOString();
+}
 export async function createOutputLink(http, runId, selectorOrQuery, options) {
     return outputLink(http, runId, selectorOrQuery, options);
 }
@@ -212,9 +249,11 @@ export async function eventArchiveLink(http, runId, options) {
         method: "POST",
         body: JSON.stringify({ expiresInSeconds })
     });
+    const effectiveExpiresIn = result.expiresInSeconds ?? expiresInSeconds;
     return {
         ...result,
-        expiresInSeconds: result.expiresInSeconds ?? expiresInSeconds
+        expiresInSeconds: effectiveExpiresIn,
+        expiresAt: result.expiresAt ?? syntheticExpiresAt(effectiveExpiresIn)
     };
 }
 export function resolveOutputFileSelector(outputs, selector, runId) {

package/dist/_contracts/provider-support.d.ts

@@ -35,11 +35,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
             readonly href: "../../../scripts/validate/capability-matrix.test.ts";
         }, {
             readonly label: "Installed-SDK Anthropic live user test";
-            readonly href: "../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts";
+            readonly href: "../../../apps/user-tests/test/live/providers/live-sdk-anthropic-managed.test.ts";
         }];
         readonly managedEvidence: readonly [{
             readonly label: "Installed-SDK Anthropic live user test";
-            readonly href: "../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts";
+            readonly href: "../../../apps/user-tests/test/live/providers/live-sdk-anthropic-managed.test.ts";
         }];
     };
     readonly deepseek: {

package/dist/_contracts/provider-support.js

@@ -9,7 +9,7 @@ const COMMON_EVIDENCE = [
 const ANTHROPIC_LIVE_USER_EVIDENCE = [
     {
         label: "Installed-SDK Anthropic live user test",
-        href: "../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts"
+        href: "../../../apps/user-tests/test/live/providers/live-sdk-anthropic-managed.test.ts"
     }
 ];
 const DEEPSEEK_LIVE_USER_EVIDENCE = [

package/dist/_contracts/run-unit.d.ts

@@ -135,7 +135,7 @@ export interface RunUnit {
  * must still render *something* for a buggy historical row rather than 500ing
  * the whole detail page.
  */
-export declare function parseRunUnitSubmission(input: unknown): RunUnitSubmission;
+export declare function parseRunUnitSubmission(input: unknown, fallbackModel?: unknown): RunUnitSubmission;
 /**
  * Normalize a `GET /api/runs/:runId` payload into a RunUnit whose type contract
  * holds AT RUNTIME. The managed (AWS) plane returns a LEAN record (scalars +

package/dist/_contracts/run-unit.js

@@ -34,19 +34,19 @@ import { PLATFORM_PACKAGE_ECOSYSTEMS } from "./submission.js";
  * must still render *something* for a buggy historical row rather than 500ing
  * the whole detail page.
  */
-export function parseRunUnitSubmission(input) {
+export function parseRunUnitSubmission(input, fallbackModel) {
     if (!input || typeof input !== "object" || Array.isArray(input)) {
-        return fallbackFlat();
+        return fallbackFlat(fallbackModel);
     }
     const value = input;
     if (value.kind === "submission") {
-        return parseFlatProjection(value);
+        return parseFlatProjection(value, fallbackModel);
     }
     // Snapshot exists but does not match the flat shape — surface as an
     // empty flat submission so consumers can still render lifecycle bits.
-    return fallbackFlat();
+    return fallbackFlat(fallbackModel);
 }
-function parseFlatProjection(value) {
+function parseFlatProjection(value, fallbackModel) {
     const submissionRaw = isRecord(value.submission) ? value.submission : {};
     const outputsRaw = isRecord(submissionRaw.outputs) ? submissionRaw.outputs : {};
     const allowedDirs = toOptionalStringArray(outputsRaw.allowedDirs);
@@ -56,7 +56,7 @@ function parseFlatProjection(value) {
     const maxTotalBytes = toOptionalPositiveInteger(outputsRaw.maxTotalBytes);
     const maxFiles = toOptionalPositiveInteger(outputsRaw.maxFiles);
     const submission = {
-        model: coerceRunUnitModel(submissionRaw.model),
+        model: coerceRunUnitModel(submissionRaw.model ?? fallbackModel),
         ...(typeof submissionRaw.system === "string" ? { system: submissionRaw.system } : {}),
         prompt: toStringArray(submissionRaw.prompt),
         agentsMd: [],
@@ -99,11 +99,11 @@ function parseSecurityProfile(value) {
 function toOptionalPositiveInteger(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
 }
-function fallbackFlat() {
+function fallbackFlat(fallbackModel) {
     return {
         kind: "submission",
         submission: {
-            model: Models.CLAUDE_HAIKU_4_5,
+            model: coerceRunUnitModel(fallbackModel),
             prompt: [],
             agentsMd: [],
             files: [],
@@ -154,7 +154,10 @@ export function normalizeRunUnit(raw) {
             : Array.isArray(r.attempts)
                 ? r.attempts.length
                 : 0,
-        submission: parseRunUnitSubmission(r.submission),
+        // Plane responses that project a flat record (no `submission` snapshot)
+        // still carry the run's `model` at the top level — prefer it over the
+        // static fallback so `unit()` never claims a model the run did not use.
+        submission: parseRunUnitSubmission(r.submission, r.model),
         ...(isRecord(r.capsSnapshot) ? { capsSnapshot: r.capsSnapshot } : {}),
         attempts: arr(r.attempts),
         events: {

package/dist/_contracts/runtime-types.d.ts

@@ -69,6 +69,12 @@ export interface Session {
     readonly usage?: UsageSummary;
     readonly costUsd?: number;
     readonly errorMessage?: string | null;
+    /**
+     * Settle-written failure taxonomy for an `error` session (e.g.
+     * `provider-permanent`, `budget_exhausted`) — the class a caller can branch
+     * on, complementing the human-readable `errorMessage`.
+     */
+    readonly failureClass?: string | null;
     readonly [key: string]: unknown;
 }
 export interface SessionSummary {
@@ -153,7 +159,7 @@ export interface UsageSummary {
     readonly totalTokens?: number;
 }
 /**
- * Filters for {@link import("./operations.js").listRuns} / `Aex.runs.list`.
+ * Filters for {@link import("./operations.js").listRuns} / the CLI's `aex runs`.
  * Every field is optional; omitting all of them lists the most recent runs in the
  * token's workspace. Workspace identity is derived server-side from the API token,
  * so there is no `workspaceId` here — a token can only ever enumerate its own runs.
@@ -187,7 +193,7 @@ export interface RunListPage {
     readonly nextCursor?: string;
 }
 /**
- * Cross-run output search query (`Aex.outputs.search`). Restrict to a
+ * Cross-run output search query (`Aex.sessions.searchOutputs`). Restrict to a
  * corpus with `runIds`; filter by filename substring / extension / content type.
  * The MVP composes this client-side (per-run `listOutputs` + filter) — a future
  * server-side `GET /api/outputs/search` can back the same contract with a real
@@ -322,7 +328,7 @@ export interface OutputFileDownload {
     readonly output: Output;
     readonly bytes: Uint8Array;
 }
-/** Options for `Aex.outputs.read` / {@link import("./operations.js").readOutputText}. */
+/** Options for `Aex.sessions.outputs(id).read` / {@link import("./operations.js").readOutputText}. */
 export interface ReadOutputTextOptions {
     /**
      * Stop reading after this many bytes. Defaults to 50_000; clamped server-side
@@ -338,7 +344,7 @@ export interface ReadOutputTextOptions {
 }
 /**
  * A byte-capped, decoded text read of one output file, as returned by
- * `Aex.outputs.read`. Built for feeding run deliverables to an LLM
+ * `Aex.sessions.outputs(id).read`. Built for feeding run deliverables to an LLM
  * without loading the whole (possibly very large) file into memory or context:
  * the read streams and stops at `maxBytes`, so `text` is at most that many bytes
  * decoded as UTF-8. Check {@link truncated} before treating `text` as complete.
@@ -368,7 +374,12 @@ export interface OutputLink {
     readonly [key: string]: unknown;
 }
 export interface WhoAmI {
-    readonly principalType: "api_token" | "user";
+    /**
+     * Kind of principal the bearer resolved to. OPTIONAL IN PRACTICE: current
+     * managed deployments do not serve it (`GET /whoami` returns only
+     * `workspaceId` + `scopes` + `limits`) — treat `undefined` as "api_token".
+     */
+    readonly principalType?: "api_token" | "user";
     readonly workspaceId?: string;
     readonly tokenId?: string;
     readonly tokenName?: string | null;
@@ -377,9 +388,10 @@ export interface WhoAmI {
      * Workspace-level caps the BFF will enforce on subsequent calls.
      * Surfaced so consumers (e.g. broll's app-side admission gate) can
      * decide whether to keep their own gate or rely on platform headers.
-     * All fields optional — older BFFs may omit. Numbers are concrete
-     * snapshots at the time of the `whoami` call; `null` means no app-visible
-     * cap is applied for that field.
+     * All fields optional — older BFFs may omit, and current managed
+     * deployments serve the newer {@link limits} block INSTEAD of `caps`.
+     * Numbers are concrete snapshots at the time of the `whoami` call;
+     * `null` means no app-visible cap is applied for that field.
      */
     readonly caps?: {
         /** Token-bucket cap on POST /api/runs per minute, per workspace. */

package/dist/_contracts/sdk-errors.d.ts

@@ -1,8 +1,10 @@
-export type AexErrorCode = "RUN_CONFIG_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR" | "RUNTIME_UNSUPPORTED" | "API_ERROR";
+export type AexErrorCode = "RUN_CONFIG_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR" | "RUNTIME_UNSUPPORTED" | "API_ERROR" | "NETWORK_ERROR";
 export declare class AexError extends Error {
     readonly code: AexErrorCode;
     readonly details?: unknown;
-    constructor(code: AexErrorCode, message: string, details?: unknown);
+    constructor(code: AexErrorCode, message: string, details?: unknown, options?: {
+        readonly cause?: unknown;
+    });
 }
 export declare class RunConfigValidationError extends AexError {
     constructor(message: string, details?: unknown);
@@ -32,3 +34,43 @@ export declare class AexApiError extends AexError {
     readonly body: unknown;
     constructor(status: number, message: string, body: unknown);
 }
+/**
+ * Thrown when a BFF-bound request fails BEFORE any HTTP response exists — DNS
+ * failure, connection refused, TLS error, socket reset. Wraps the raw fetch
+ * rejection (whose undici form is a bare `TypeError: fetch failed` with the
+ * useful code hidden on `cause.code`) into a message that names the request
+ * and the transport failure, e.g.
+ * `POST api.aex.dev/assets/presign failed: ECONNREFUSED (connect ECONNREFUSED 127.0.0.1:443)`.
+ * The original rejection is preserved on `cause`.
+ */
+export declare class AexNetworkError extends AexError {
+    readonly method: string;
+    /** Request host — never carries credentials or the query string. */
+    readonly host: string;
+    readonly path: string;
+    /** Transport failure code (e.g. `ECONNREFUSED`), when detectable. */
+    readonly causeCode: string | undefined;
+    /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
+    readonly attempts: number;
+    constructor(args: {
+        readonly method: string;
+        readonly host: string;
+        readonly path: string;
+        readonly cause: unknown;
+        /** Set by the retry layer when it gave up: appended to the message. */
+        readonly attempts?: number;
+        readonly elapsedMs?: number;
+    });
+}
+/**
+ * Best-effort transport error code (`ECONNREFUSED`, `ENOTFOUND`, …): checks
+ * `err.code`, then `err.cause.code` (where undici hides it), then falls back
+ * to an `E…`-shaped token in the message.
+ */
+export declare function extractErrorCode(err: unknown): string | undefined;
+/**
+ * Redact a URL down to protocol + host + path: credentials become
+ * `[redacted]@` and any query string becomes `?[redacted]` (presigned URLs
+ * carry signatures there). Tolerates unparseable input.
+ */
+export declare function redactUrl(url: string): string;