@aexhq/sdk 0.40.10 → 0.40.11

package/dist/_contracts/http.d.ts

@@ -18,6 +18,17 @@ export interface HttpClientOptions {
     readonly fetch?: FetchLike;
     /** When set, every request emits a redacted one-line trace here. */
     readonly debug?: DebugSink;
+    /**
+     * Retry transient transport failures for idempotent GET/HEAD requests.
+     * Disabled by default; host CLIs enable this so a single dropped API
+     * connection does not fail read-only commands.
+     */
+    readonly retryTransientGets?: boolean | TransientGetRetryOptions;
+}
+export interface TransientGetRetryOptions {
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly sleep?: (ms: number) => Promise<void>;
 }
 /**
  * Thin transport used by every BFF-bound operation. The SDK class and

package/dist/_contracts/http.js

@@ -1,4 +1,4 @@
-import { AexError, AexNetworkError, redactUrl } from "./sdk-errors.js";
+import { AexError, AexNetworkError, extractErrorCode, redactUrl } from "./sdk-errors.js";
 import { apiErrorFromResponse } from "./error-factory.js";
 import { AEX_DEFAULT_BASE_URL } from "./stable.js";
 /**
@@ -12,6 +12,7 @@ export class HttpClient {
     #apiKey;
     #fetch;
     #debug;
+    #retryTransientGets;
     constructor(options) {
         if (!options.apiKey) {
             throw new Error("HttpClient: apiKey is required");
@@ -28,6 +29,7 @@ export class HttpClient {
         this.#apiKey = options.apiKey;
         this.#fetch = options.fetch ?? fetch;
         this.#debug = options.debug;
+        this.#retryTransientGets = resolveTransientGetRetry(options.retryTransientGets);
     }
     /** Emit a redacted round-trip trace (no auth header, body, or query). */
     #trace(method, url, status, startedMs) {
@@ -52,25 +54,34 @@ export class HttpClient {
                 headers["content-type"] = "application/json";
             }
         }
-        const startedMs = Date.now();
-        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) {
-            const errorBody = withResponseRequestId(body, response.headers);
-            throw apiErrorFromResponse({
-                status: response.status,
-                body: errorBody,
-                message: extractErrorMessage(errorBody)
-            });
+        const method = methodOf(init.method);
+        const retry = retryForMethod(method, this.#retryTransientGets);
+        const requestStartedMs = Date.now();
+        for (let attempt = 1; attempt <= retry.maxAttempts; attempt += 1) {
+            const startedMs = Date.now();
+            try {
+                const response = await this.#fetch(url, { ...init, headers });
+                this.#trace(method, url, response.status, startedMs);
+                const body = await readJson(response);
+                if (!response.ok) {
+                    const errorBody = withResponseRequestId(body, response.headers);
+                    throw apiErrorFromResponse({
+                        status: response.status,
+                        body: errorBody,
+                        message: extractErrorMessage(errorBody)
+                    });
+                }
+                return body;
+            }
+            catch (err) {
+                if (shouldRetryTransientRead(err, retry, attempt)) {
+                    await sleepBeforeRetry(this.#debug, method, url, err, retry, attempt);
+                    continue;
+                }
+                throw toNetworkError(method, url, err, retry.maxAttempts > 1 ? attempt : undefined, Date.now() - requestStartedMs);
+            }
         }
-        return body;
+        throw new Error("HttpClient.request retry loop exhausted");
     }
     async download(path, init = {}, query = {}) {
         const url = new URL(path.replace(/^\//, ""), this.#baseUrl);
@@ -81,26 +92,93 @@ export class HttpClient {
             authorization: `Bearer ${this.#apiKey}`,
             ...normalizeHeaders(init.headers)
         };
-        const startedMs = Date.now();
-        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);
-            const errorBody = withResponseRequestId(body, response.headers);
-            throw apiErrorFromResponse({
-                status: response.status,
-                body: errorBody,
-                message: extractErrorMessage(errorBody)
-            });
+        const method = methodOf(init.method);
+        const retry = retryForMethod(method, this.#retryTransientGets);
+        const requestStartedMs = Date.now();
+        for (let attempt = 1; attempt <= retry.maxAttempts; attempt += 1) {
+            const startedMs = Date.now();
+            try {
+                const response = await this.#fetch(url, { ...init, headers });
+                this.#trace(method, url, response.status, startedMs);
+                if (!response.ok) {
+                    const body = await readJson(response);
+                    const errorBody = withResponseRequestId(body, response.headers);
+                    throw apiErrorFromResponse({
+                        status: response.status,
+                        body: errorBody,
+                        message: extractErrorMessage(errorBody)
+                    });
+                }
+                return { response };
+            }
+            catch (err) {
+                if (shouldRetryTransientRead(err, retry, attempt)) {
+                    await sleepBeforeRetry(this.#debug, method, url, err, retry, attempt);
+                    continue;
+                }
+                throw toNetworkError(method, url, err, retry.maxAttempts > 1 ? attempt : undefined, Date.now() - requestStartedMs);
+            }
         }
-        return { response };
+        throw new Error("HttpClient.download retry loop exhausted");
+    }
+}
+const DEFAULT_TRANSIENT_GET_RETRY = {
+    maxAttempts: 3,
+    baseDelayMs: 250,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+const TRANSIENT_READ_CODES = new Set([
+    "ConnectionRefused",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "UND_ERR_BODY_TIMEOUT"
+]);
+function resolveTransientGetRetry(retry) {
+    if (!retry)
+        return null;
+    if (retry === true)
+        return DEFAULT_TRANSIENT_GET_RETRY;
+    return {
+        maxAttempts: Math.max(1, retry.maxAttempts ?? DEFAULT_TRANSIENT_GET_RETRY.maxAttempts),
+        baseDelayMs: Math.max(0, retry.baseDelayMs ?? DEFAULT_TRANSIENT_GET_RETRY.baseDelayMs),
+        sleep: retry.sleep ?? DEFAULT_TRANSIENT_GET_RETRY.sleep
+    };
+}
+function methodOf(method) {
+    return (method ?? "GET").toUpperCase();
+}
+function retryForMethod(method, retry) {
+    if (!retry || (method !== "GET" && method !== "HEAD")) {
+        return { ...DEFAULT_TRANSIENT_GET_RETRY, maxAttempts: 1 };
     }
+    return retry;
+}
+function shouldRetryTransientRead(err, retry, attempt) {
+    return attempt < retry.maxAttempts && transientReadErrorCode(err) !== undefined;
+}
+async function sleepBeforeRetry(debug, method, url, err, retry, attempt) {
+    const delayMs = retry.baseDelayMs * attempt;
+    debug?.(`[aex] ${method} ${url.pathname} transient ${transientReadErrorCode(err) ?? "network"} ` +
+        `attempt ${attempt}/${retry.maxAttempts}; retrying in ${delayMs}ms`);
+    await retry.sleep(delayMs);
+}
+function transientReadErrorCode(err) {
+    if (err instanceof AexError)
+        return undefined;
+    if (err?.name === "AbortError")
+        return undefined;
+    const code = extractErrorCode(err);
+    if (code && TRANSIENT_READ_CODES.has(code))
+        return code;
+    const text = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+    if (/fetch failed|socket hang up|other side closed|terminated|network.*reset/i.test(text))
+        return "fetch";
+    return undefined;
 }
 /**
  * Wrap a fetch rejection into an {@link AexNetworkError} carrying the
@@ -108,7 +186,7 @@ export class HttpClient {
  * already-structured aex errors (e.g. a retry layer's AexRateLimitError or
  * AexNetworkError) pass through untouched.
  */
-function toNetworkError(method, url, err) {
+function toNetworkError(method, url, err, attempts, elapsedMs) {
     if (err instanceof AexError)
         return err;
     // `DOMException` is not an `Error` subclass on every runtime, so match aborts by name.
@@ -118,7 +196,9 @@ function toNetworkError(method, url, err) {
         method: (method ?? "GET").toUpperCase(),
         host: url.host,
         path: url.pathname,
-        cause: err
+        cause: err,
+        ...(attempts !== undefined ? { attempts } : {}),
+        ...(elapsedMs !== undefined ? { elapsedMs } : {})
     });
 }
 function normalizeHeaders(headers) {

package/dist/cli.mjs

@@ -2104,6 +2104,7 @@ var HttpClient = class {
   #apiKey;
   #fetch;
   #debug;
+  #retryTransientGets;
   constructor(options) {
     if (!options.apiKey) {
       throw new Error("HttpClient: apiKey is required");
@@ -2118,6 +2119,7 @@ var HttpClient = class {
     this.#apiKey = options.apiKey;
     this.#fetch = options.fetch ?? fetch;
     this.#debug = options.debug;
+    this.#retryTransientGets = resolveTransientGetRetry(options.retryTransientGets);
   }
   /** Emit a redacted round-trip trace (no auth header, body, or query). */
   #trace(method, url, status, startedMs) {
@@ -2138,24 +2140,33 @@ var HttpClient = class {
         headers["content-type"] = "application/json";
       }
     }
-    const startedMs = Date.now();
-    let response;
-    try {
-      response = await this.#fetch(url, { ...init, headers });
-    } catch (err2) {
-      throw toNetworkError(init.method, url, err2);
-    }
-    this.#trace(init.method, url, response.status, startedMs);
-    const body = await readJson(response);
-    if (!response.ok) {
-      const errorBody = withResponseRequestId(body, response.headers);
-      throw apiErrorFromResponse({
-        status: response.status,
-        body: errorBody,
-        message: extractErrorMessage(errorBody)
-      });
+    const method = methodOf(init.method);
+    const retry = retryForMethod(method, this.#retryTransientGets);
+    const requestStartedMs = Date.now();
+    for (let attempt = 1; attempt <= retry.maxAttempts; attempt += 1) {
+      const startedMs = Date.now();
+      try {
+        const response = await this.#fetch(url, { ...init, headers });
+        this.#trace(method, url, response.status, startedMs);
+        const body = await readJson(response);
+        if (!response.ok) {
+          const errorBody = withResponseRequestId(body, response.headers);
+          throw apiErrorFromResponse({
+            status: response.status,
+            body: errorBody,
+            message: extractErrorMessage(errorBody)
+          });
+        }
+        return body;
+      } catch (err2) {
+        if (shouldRetryTransientRead(err2, retry, attempt)) {
+          await sleepBeforeRetry(this.#debug, method, url, err2, retry, attempt);
+          continue;
+        }
+        throw toNetworkError(method, url, err2, retry.maxAttempts > 1 ? attempt : void 0, Date.now() - requestStartedMs);
+      }
     }
-    return body;
+    throw new Error("HttpClient.request retry loop exhausted");
   }
   async download(path, init = {}, query = {}) {
     const url = new URL(path.replace(/^\//, ""), this.#baseUrl);
@@ -2166,27 +2177,93 @@ var HttpClient = class {
       authorization: `Bearer ${this.#apiKey}`,
       ...normalizeHeaders(init.headers)
     };
-    const startedMs = Date.now();
-    let response;
-    try {
-      response = await this.#fetch(url, { ...init, headers });
-    } catch (err2) {
-      throw toNetworkError(init.method, url, err2);
-    }
-    this.#trace(init.method, url, response.status, startedMs);
-    if (!response.ok) {
-      const body = await readJson(response);
-      const errorBody = withResponseRequestId(body, response.headers);
-      throw apiErrorFromResponse({
-        status: response.status,
-        body: errorBody,
-        message: extractErrorMessage(errorBody)
-      });
+    const method = methodOf(init.method);
+    const retry = retryForMethod(method, this.#retryTransientGets);
+    const requestStartedMs = Date.now();
+    for (let attempt = 1; attempt <= retry.maxAttempts; attempt += 1) {
+      const startedMs = Date.now();
+      try {
+        const response = await this.#fetch(url, { ...init, headers });
+        this.#trace(method, url, response.status, startedMs);
+        if (!response.ok) {
+          const body = await readJson(response);
+          const errorBody = withResponseRequestId(body, response.headers);
+          throw apiErrorFromResponse({
+            status: response.status,
+            body: errorBody,
+            message: extractErrorMessage(errorBody)
+          });
+        }
+        return { response };
+      } catch (err2) {
+        if (shouldRetryTransientRead(err2, retry, attempt)) {
+          await sleepBeforeRetry(this.#debug, method, url, err2, retry, attempt);
+          continue;
+        }
+        throw toNetworkError(method, url, err2, retry.maxAttempts > 1 ? attempt : void 0, Date.now() - requestStartedMs);
+      }
     }
-    return { response };
+    throw new Error("HttpClient.download retry loop exhausted");
   }
 };
-function toNetworkError(method, url, err2) {
+var DEFAULT_TRANSIENT_GET_RETRY = {
+  maxAttempts: 3,
+  baseDelayMs: 250,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+var TRANSIENT_READ_CODES = /* @__PURE__ */ new Set([
+  "ConnectionRefused",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_SOCKET",
+  "UND_ERR_BODY_TIMEOUT"
+]);
+function resolveTransientGetRetry(retry) {
+  if (!retry)
+    return null;
+  if (retry === true)
+    return DEFAULT_TRANSIENT_GET_RETRY;
+  return {
+    maxAttempts: Math.max(1, retry.maxAttempts ?? DEFAULT_TRANSIENT_GET_RETRY.maxAttempts),
+    baseDelayMs: Math.max(0, retry.baseDelayMs ?? DEFAULT_TRANSIENT_GET_RETRY.baseDelayMs),
+    sleep: retry.sleep ?? DEFAULT_TRANSIENT_GET_RETRY.sleep
+  };
+}
+function methodOf(method) {
+  return (method ?? "GET").toUpperCase();
+}
+function retryForMethod(method, retry) {
+  if (!retry || method !== "GET" && method !== "HEAD") {
+    return { ...DEFAULT_TRANSIENT_GET_RETRY, maxAttempts: 1 };
+  }
+  return retry;
+}
+function shouldRetryTransientRead(err2, retry, attempt) {
+  return attempt < retry.maxAttempts && transientReadErrorCode(err2) !== void 0;
+}
+async function sleepBeforeRetry(debug2, method, url, err2, retry, attempt) {
+  const delayMs = retry.baseDelayMs * attempt;
+  debug2?.(`[aex] ${method} ${url.pathname} transient ${transientReadErrorCode(err2) ?? "network"} attempt ${attempt}/${retry.maxAttempts}; retrying in ${delayMs}ms`);
+  await retry.sleep(delayMs);
+}
+function transientReadErrorCode(err2) {
+  if (err2 instanceof AexError)
+    return void 0;
+  if (err2?.name === "AbortError")
+    return void 0;
+  const code = extractErrorCode(err2);
+  if (code && TRANSIENT_READ_CODES.has(code))
+    return code;
+  const text = err2 instanceof Error ? `${err2.name}: ${err2.message}` : String(err2);
+  if (/fetch failed|socket hang up|other side closed|terminated|network.*reset/i.test(text))
+    return "fetch";
+  return void 0;
+}
+function toNetworkError(method, url, err2, attempts, elapsedMs) {
   if (err2 instanceof AexError)
     return err2;
   if (err2?.name === "AbortError")
@@ -2195,7 +2272,9 @@ function toNetworkError(method, url, err2) {
     method: (method ?? "GET").toUpperCase(),
     host: url.host,
     path: url.pathname,
-    cause: err2
+    cause: err2,
+    ...attempts !== void 0 ? { attempts } : {},
+    ...elapsedMs !== void 0 ? { elapsedMs } : {}
   });
 }
 function normalizeHeaders(headers) {
@@ -4202,6 +4281,7 @@ function makeHttpClient(io2, flags) {
   return new HttpClient({
     baseUrl: flags.aexUrl,
     apiKey: flags.apiKey,
+    retryTransientGets: true,
     fetch: io2.fetchImpl,
     // `--debug`: route the transport's redacted per-request traces to stderr.
     ...flags.debug ? { debug: (line) => io2.stderr(`${line}

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-feca3311d49affc9dd305e9c1a8da4faee1c604662ebb34abc142c8f1276635c  cli.mjs
+383e87cd6909a7a5eb73b90a77c12b6adf78491678cdc14612d5cc878971458e  cli.mjs

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.40.10";
+export declare const SDK_VERSION = "0.40.11";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.40.10",
+  "version": "0.40.11",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {