@aexhq/sdk 0.34.0 → 0.35.0

package/dist/retry.js

@@ -0,0 +1,320 @@
+/**
+ * Built-in transport resilience for the aex SDK.
+ *
+ * Every BFF-bound request the SDK makes goes through one {@link FetchLike}. This
+ * module wraps that fetch so a transient failure — an HTTP 429 (rate limited),
+ * a 500/502/503/504 (server hiccup), a 529 (upstream overloaded), or a network
+ * error — is retried with BOUNDED exponential backoff + full jitter, honoring
+ * the server's `Retry-After` header when present. Non-retryable 4xx responses
+ * (400/401/403/404/…) fail fast — retrying them only wastes the caller's time.
+ *
+ * Retries are SAFE to enable by default because the billable submits
+ * (`createSession` / `sendSessionMessage`) carry a stable `Idempotency-Key`
+ * header: re-sending the identical request de-duplicates server-side, so a retry
+ * never creates a duplicate billable turn.
+ *
+ * When retries are exhausted on a rate-limit / overloaded status the wrapper
+ * surfaces an {@link AexRateLimitError} — a structured, non-leaky throttle error
+ * carrying the parsed `retryAfterMs`, the attempt count, and (when the runtime
+ * supplies it) an upstream {@link ProviderFault}. All other exhausted retries
+ * fall through to the transport's usual `AexApiError` / network rejection.
+ */
+import { AexApiError } from "./_contracts/index.js";
+/**
+ * HTTP statuses that are transient and worth retrying. The billable submits
+ * carry an idempotency key, so re-issuing them is safe. Everything not in this
+ * set (400/401/403/404/409/422/…) is a definitive client error and fails fast.
+ */
+export const RETRYABLE_STATUS = [429, 500, 502, 503, 504, 529];
+/**
+ * The subset of {@link RETRYABLE_STATUS} the platform / upstream provider uses to
+ * say "slow down": 429 rate-limit, 503 unavailable, 529 overloaded. When retries
+ * for one of these run out, the wrapper raises an {@link AexRateLimitError}.
+ */
+export const RATE_LIMIT_STATUS = [429, 503, 529];
+const DEFAULT_RETRY = {
+    maxAttempts: 4,
+    initialDelayMs: 500,
+    maxDelayMs: 20_000,
+    maxElapsedMs: 120_000
+};
+/** Resolve caller options over the defaults, clamping to sane bounds. */
+export function resolveRetryConfig(options) {
+    const maxAttempts = Math.max(1, Math.floor(options?.maxAttempts ?? DEFAULT_RETRY.maxAttempts));
+    const initialDelayMs = Math.max(0, options?.initialDelayMs ?? DEFAULT_RETRY.initialDelayMs);
+    const maxDelayMs = Math.max(initialDelayMs, options?.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs);
+    const maxElapsedMs = Math.max(0, options?.maxElapsedMs ?? DEFAULT_RETRY.maxElapsedMs);
+    return { maxAttempts, initialDelayMs, maxDelayMs, maxElapsedMs };
+}
+export function isRetryableStatus(status) {
+    return RETRYABLE_STATUS.includes(status);
+}
+export function isRateLimitStatus(status) {
+    return RATE_LIMIT_STATUS.includes(status);
+}
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds. Per RFC 7231 the value
+ * is either a non-negative integer number of seconds or an HTTP-date; both are
+ * handled. Returns `undefined` for a missing or unparseable value.
+ */
+export function parseRetryAfterMs(headerValue, now = Date.now()) {
+    if (headerValue === null || headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - now);
+    }
+    return undefined;
+}
+/**
+ * Full-jitter exponential backoff (AWS-style): the nominal wait doubles per
+ * retry up to `maxDelayMs`, and the actual wait is a uniform sample in
+ * `[0, nominal]` to de-correlate concurrent clients. `attemptNumber` is the
+ * 1-based number of the attempt that just failed.
+ */
+export function computeBackoffDelayMs(config, attemptNumber, random) {
+    const exponent = Math.max(0, attemptNumber - 1);
+    const nominal = Math.min(config.maxDelayMs, config.initialDelayMs * 2 ** exponent);
+    return Math.round(random() * nominal);
+}
+/** Combine the server's `Retry-After` (a floor) with our jittered backoff. */
+function nextDelayMs(config, attemptNumber, random, retryAfterMs) {
+    const backoff = computeBackoffDelayMs(config, attemptNumber, random);
+    return retryAfterMs === undefined ? backoff : Math.max(retryAfterMs, backoff);
+}
+const THROTTLE_KINDS = new Set(["rate_limit", "overloaded", "quota_exceeded"]);
+/** True when a {@link ProviderFault} represents a "back off and retry" signal. */
+export function isThrottleFault(fault) {
+    return THROTTLE_KINDS.has(fault.kind);
+}
+/**
+ * Structured throttle error. Extends {@link AexApiError} so existing
+ * `catch (err instanceof AexApiError)` sites keep working, while callers that
+ * want the details narrow with {@link isRateLimited} and read `retryAfterMs`,
+ * `attempts`, `source`, and `providerFault`. The `message` is a fixed,
+ * non-leaky summary — it never echoes the raw error body (which is still
+ * available, redacted, on `.body`).
+ */
+export class AexRateLimitError extends AexApiError {
+    /** Milliseconds the server/provider asked us to wait, when known. */
+    retryAfterMs;
+    /** How many attempts were made before giving up. */
+    attempts;
+    /** Whether the throttle came from the aex API plane or the upstream provider. */
+    source;
+    /** The upstream provider fault, when the throttle originated there. */
+    providerFault;
+    constructor(args) {
+        super(args.status, args.message ?? defaultThrottleMessage(args), args.body);
+        this.attempts = args.attempts;
+        this.source = args.source ?? "api";
+        if (args.retryAfterMs !== undefined)
+            this.retryAfterMs = args.retryAfterMs;
+        if (args.providerFault !== undefined)
+            this.providerFault = args.providerFault;
+    }
+}
+/** Type guard for {@link AexRateLimitError}. */
+export function isRateLimited(err) {
+    return err instanceof AexRateLimitError;
+}
+function defaultThrottleMessage(args) {
+    const who = args.source === "provider" ? "upstream provider" : "aex API";
+    const label = args.status === 529 ? "overloaded" : "rate limit reached";
+    const attempts = `${args.attempts} attempt${args.attempts === 1 ? "" : "s"}`;
+    const wait = args.retryAfterMs !== undefined
+        ? `; retry after ~${Math.ceil(args.retryAfterMs / 1000)}s`
+        : "";
+    return `${who} ${label} (HTTP ${args.status}) after ${attempts}${wait}`;
+}
+/**
+ * Best-effort parse of an unknown value into a {@link ProviderFault}. Tolerant
+ * of two shapes so the SDK consumes the runtime fault the moment it starts
+ * emitting one, without a contracts change:
+ *
+ *   1. The canonical `{ provider?, kind, status?, retryAfterMs?, message? }`
+ *      (optionally nested under a `providerFault` key), OR
+ *   2. A raw upstream error `{ type: "rate_limit_error" | "overloaded_error"
+ *      | ..., message?, retry_after? | retryAfter? }` — `type` maps to `kind`
+ *      and `retry_after` (seconds) maps to `retryAfterMs`.
+ *
+ * Returns `undefined` when the value carries no recognizable fault.
+ */
+export function parseProviderFault(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const nested = record.providerFault ?? record.provider_fault;
+    if (nested !== undefined && nested !== value) {
+        const fromNested = parseProviderFault(nested);
+        if (fromNested)
+            return fromNested;
+    }
+    const kind = coerceFaultKind(record.kind ?? record.type ?? record.code);
+    if (kind === undefined)
+        return undefined;
+    const provider = typeof record.provider === "string" ? record.provider : undefined;
+    const status = coerceStatus(record.status ?? record.statusCode ?? record.httpStatus);
+    const retryAfterMs = coerceRetryAfterMs(record.retryAfterMs ?? record.retry_after_ms ?? record.retryAfter ?? record.retry_after);
+    const message = typeof record.message === "string" ? record.message : undefined;
+    return {
+        kind,
+        ...(provider !== undefined ? { provider } : {}),
+        ...(status !== undefined ? { status } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(message !== undefined ? { message } : {})
+    };
+}
+function coerceFaultKind(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const value = raw.toLowerCase();
+    if (value.includes("rate_limit") || value.includes("rate limit") || value === "429")
+        return "rate_limit";
+    if (value.includes("overload") || value === "529")
+        return "overloaded";
+    if (value.includes("quota") || value.includes("insufficient"))
+        return "quota_exceeded";
+    if (value.includes("provider_error") || value.includes("provider error") || value.includes("api_error")) {
+        return "provider_error";
+    }
+    return undefined;
+}
+function coerceStatus(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim()))
+        return Number(raw.trim());
+    return undefined;
+}
+/** Accept a ms number, a `<digits>` string, or seconds under a `retry_after` alias. */
+function coerceRetryAfterMs(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        // Heuristic: small integers are seconds (the upstream convention), large
+        // ones are already milliseconds.
+        return raw > 0 && raw < 1000 ? raw * 1000 : raw;
+    }
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim())) {
+        const n = Number(raw.trim());
+        return n > 0 && n < 1000 ? n * 1000 : n;
+    }
+    return undefined;
+}
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+function isAbortError(err) {
+    return err instanceof Error && err.name === "AbortError";
+}
+async function drain(response) {
+    try {
+        if (response.body && typeof response.body.cancel === "function") {
+            await response.body.cancel();
+            return;
+        }
+        await response.text();
+    }
+    catch {
+        // Draining is best-effort; a discarded retryable response never surfaces.
+    }
+}
+async function readBodyForError(response) {
+    try {
+        const text = await response.text();
+        if (text.length === 0)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { raw: text };
+        }
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Wrap a {@link FetchLike} with the bounded-retry loop. `retry === false`
+ * disables the layer entirely (the input fetch is returned unchanged). Otherwise
+ * the returned fetch retries transient failures per {@link RetryOptions} and, on
+ * an exhausted rate-limit/overloaded status, throws {@link AexRateLimitError}.
+ */
+export function withRetry(fetchImpl, retry, deps = {}) {
+    if (retry === false)
+        return fetchImpl;
+    const config = resolveRetryConfig(retry);
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const now = deps.now ?? Date.now;
+    return async (input, init) => {
+        const startedAt = now();
+        const signal = init?.signal ?? undefined;
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            let response;
+            try {
+                response = await fetchImpl(input, init);
+            }
+            catch (err) {
+                // A caller-initiated abort is terminal, never transient.
+                if (isAbortError(err))
+                    throw err;
+                if (attempt >= config.maxAttempts)
+                    throw err;
+                const delay = computeBackoffDelayMs(config, attempt, random);
+                if (now() - startedAt + delay > config.maxElapsedMs)
+                    throw err;
+                await sleep(delay, signal ?? undefined);
+                continue;
+            }
+            // Success or a definitive (non-retryable) response — hand straight back so
+            // the transport reads/throws exactly as it does without the retry layer.
+            if (!isRetryableStatus(response.status)) {
+                return response;
+            }
+            const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"), now());
+            const willRetry = attempt < config.maxAttempts &&
+                now() - startedAt + nextDelayMs(config, attempt, random, retryAfterMs) <= config.maxElapsedMs;
+            if (willRetry) {
+                await drain(response);
+                await sleep(nextDelayMs(config, attempt, random, retryAfterMs), signal ?? undefined);
+                continue;
+            }
+            // Retries exhausted (or budget spent). A rate-limit/overloaded status
+            // becomes a structured throttle error; any other transient status falls
+            // through to the transport's normal AexApiError.
+            if (isRateLimitStatus(response.status)) {
+                const body = await readBodyForError(response);
+                throw new AexRateLimitError({
+                    status: response.status,
+                    attempts: attempt,
+                    source: "api",
+                    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+                    body
+                });
+            }
+            return response;
+        }
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.34.0";
+export declare const SDK_VERSION = "0.35.0";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.34.0";
+export const SDK_VERSION = "0.35.0";
 //# sourceMappingURL=version.js.map

package/docs/retries.md

@@ -0,0 +1,129 @@
+---
+title: Retries and throttling
+---
+
+# Retries and throttling
+
+The SDK ships with built-in transport resilience. Every request it makes to the
+aex API is automatically retried on **transient** failures with bounded
+exponential backoff and jitter, honoring the server's `Retry-After` header. You
+get this by default — no wrapper code — and it is safe to leave on because the
+billable submits carry a stable idempotency key, so a retry never creates a
+duplicate run.
+
+## What gets retried
+
+Retried automatically:
+
+- HTTP `429` (rate limited)
+- HTTP `500`, `502`, `503`, `504` (server hiccups)
+- HTTP `529` (upstream provider overloaded)
+- Network errors (connection reset, DNS failure, timeout)
+
+Never retried — these fail fast so you see the real problem immediately:
+
+- `400` / `422` (bad request), `401` / `403` (auth), `404` (not found),
+  `409` (conflict), and every other non-transient `4xx`.
+- A request you aborted yourself (via an `AbortSignal`).
+
+## Tuning or disabling
+
+Pass a `retry` option when you construct the client:
+
+```ts
+import { Aex } from "@aexhq/sdk";
+
+const aex = new Aex({
+  apiToken: process.env.AEX_API_TOKEN!,
+  retry: {
+    maxAttempts: 4,        // total tries incl. the first (default 4)
+    initialDelayMs: 500,   // base backoff, doubles per retry (default 500)
+    maxDelayMs: 20_000,    // cap on any single wait (default 20s)
+    maxElapsedMs: 120_000  // overall wall-clock budget (default 2m)
+  }
+});
+```
+
+Turn it off entirely with `retry: false`, or make a single attempt with
+`retry: { maxAttempts: 1 }`.
+
+## Idempotent by construction
+
+Retries — whether the built-in transport retry or your own re-invocation of
+`run(...)` — never double-bill. The one-shot `run(...)` and `sessions.run(...)`
+derive the turn's idempotency key from the session-create key, so re-invoking
+either with the same `idempotencyKey` de-duplicates **both** the session create
+and the billable turn server-side:
+
+```ts
+// A retried call with the same idempotencyKey resolves to the same run,
+// not a second billable one.
+const result = await aex.run({
+  model: "claude-haiku-4-5",
+  message: "Write a short report and save it as a file.",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
+  idempotencyKey: "report-2026-07-01"
+});
+```
+
+## Replaying a throttled turn
+
+When a turn on a live session is interrupted by a throttle, replay the last
+message with `session.replayLast()`. It reuses the previous message's idempotency
+key by default, so if the original turn actually landed it de-duplicates instead
+of billing twice:
+
+```ts
+const session = await aex.openSession({
+  model: "claude-haiku-4-5",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+
+try {
+  await session.send("Summarize the attached dataset.").done();
+} catch (err) {
+  const { isRateLimited } = await import("@aexhq/sdk");
+  if (isRateLimited(err)) {
+    // Wait out the throttle, then replay the same message.
+    await new Promise((r) => setTimeout(r, err.retryAfterMs ?? 2_000));
+    await session.replayLast().done();
+  } else {
+    throw err;
+  }
+}
+```
+
+Pass a fresh key (`session.replayLast({ idempotencyKey: "..." })`) when you
+deliberately want a brand-new turn instead of a de-duplicated replay.
+
+## The throttle error
+
+When retries are exhausted on a rate-limit / overloaded status, the SDK throws an
+`AexRateLimitError`. It extends `AexApiError`, so existing `catch` sites keep
+working, and it carries structured, non-leaky detail:
+
+```ts
+import { isRateLimited } from "@aexhq/sdk";
+
+try {
+  await aex.run({ /* … */ });
+} catch (err) {
+  if (isRateLimited(err)) {
+    err.status;         // 429 | 503 | 529
+    err.attempts;       // how many tries were made
+    err.retryAfterMs;   // suggested wait, when the server supplied one
+    err.source;         // "api" (aex plane) or "provider" (upstream model)
+    err.providerFault;  // upstream fault detail, when the model provider throttled
+  }
+}
+```
+
+The `message` is a fixed summary (e.g. `aex API rate limit reached (HTTP 429)
+after 4 attempts; retry after ~2s`) — it never echoes the raw response body,
+which stays available, redacted, on `err.body`.
+
+When the throttle originated at the upstream model provider (rather than the aex
+API plane), `err.source` is `"provider"` and `err.providerFault` describes it:
+its `kind` (`rate_limit` / `overloaded` / `quota_exceeded` / `provider_error`),
+the upstream `status`, and a suggested `retryAfterMs`. Use `parseProviderFault`
+to read the same shape off a raw fault value yourself.