@blaxel/core 0.3.9-preview.237 → 0.3.9-preview.238

package/dist/esm/common/settings.js

@@ -24,8 +24,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.9-preview.237";
-const BUILD_COMMIT = "8ec1775f74429ef5122d03f6b708a122c87ef880";
+const BUILD_VERSION = "0.3.9-preview.238";
+const BUILD_COMMIT = "e8e4a67eba43ee3946e0682f613efb0e50dd0320";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-28";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

package/dist/esm/common/transient-retry.js

@@ -17,6 +17,14 @@ const TRANSIENT_RESET_MARKERS = [
     "HTTP/2 session closed before response", // thrown by our own h2 transport
     "HTTP/2 session sent GOAWAY before response",
 ];
+// HTTP statuses the edge/CDN (e.g. CloudFront) returns when it — not the
+// sandbox — fails to get a usable response from origin: 502 Bad Gateway,
+// 503 Service Unavailable, 504 Gateway Timeout. On an IDEMPOTENT request these
+// are safe to retry (the sandbox is likely waking from standby, or the edge
+// briefly could not reach origin). Retried with a small, separate budget from
+// transport resets because each attempt can itself burn the edge's ~60s
+// origin-read timeout before failing.
+export const GATEWAY_ERROR_STATUSES = new Set([502, 503, 504]);
 // Node-level error codes (from `error.code` / `error.cause.code`) that mean
 // the connection itself dropped mid-flight and the request never completed.
 // These are safe to retry for an idempotent request.
@@ -51,19 +59,36 @@ function collectErrorText(error) {
 // like "GOAWAY" or "ERR_HTTP2". Guarding on this stops a marker-bearing 4xx/5xx
 // body from being misread as transient and retried (the over-match Codex flagged
 // for the now default-on idempotent-read retry).
-function hasHttpResponseStatus(error) {
+function getHttpResponseStatus(error) {
     let current = error;
     for (let depth = 0; depth < 5 && current && typeof current === "object"; depth++) {
         const node = current;
         if (typeof node.status === "number")
-            return true;
-        if (node.response && typeof node.response === "object" &&
-            typeof node.response.status === "number") {
-            return true;
+            return node.status;
+        if (node.response && typeof node.response === "object") {
+            const responseStatus = node.response.status;
+            if (typeof responseStatus === "number")
+                return responseStatus;
         }
         current = node.cause;
     }
-    return false;
+    return null;
+}
+function hasHttpResponseStatus(error) {
+    return getHttpResponseStatus(error) !== null;
+}
+/**
+ * True when the error carries an edge gateway status (502/503/504). Unlike a
+ * transport reset (see isTransientResetError), this DOES carry an HTTP status —
+ * it is the edge failing to reach origin, not the sandbox returning an
+ * application error — so it is retried on idempotent operations with its own
+ * small budget.
+ */
+export function isRetryableGatewayError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const status = getHttpResponseStatus(error);
+    return status !== null && GATEWAY_ERROR_STATUSES.has(status);
 }
 /**
  * True only for transport-level resets/drops that are safe to retry on an
@@ -99,6 +124,11 @@ export function isTransientResetError(error) {
 }
 const DEFAULT_BASE_DELAY_MS = 200;
 const DEFAULT_MAX_DELAY_MS = 2000;
+// Gateway (502/503/504) retries get their own small budget: each attempt can
+// burn the edge's ~60s origin-read timeout before failing, so a large budget
+// would stall a caller for minutes. Two extra attempts is enough to ride out a
+// standby wake without turning a hard outage into a multi-minute hang.
+const DEFAULT_GATEWAY_RETRIES = 2;
 // Exponential backoff with full-jitter on top of one base delay, capped so a
 // single wait never blocks unreasonably long. Exponential (rather than linear)
 // gives a later attempt room to span a multi-second sandbox cold-start/standby
@@ -118,20 +148,38 @@ export function backoffDelayMs(attempt, baseDelayMs, maxDelayMs) {
  * PUT of the same bytes) — never a non-idempotent POST such as process.exec,
  * which would duplicate the side effect (ENG-2340).
  *
+ * Also retries edge gateway statuses (502/503/504) on their own small budget
+ * (`gatewayRetries`, default 2): these carry an HTTP status but come from the
+ * edge failing to reach origin (a standby wake, not an application error), so
+ * they are safe to retry on an idempotent request.
+ *
  * Defaults to `settings.sandboxReadRetries` (the higher idempotent-read budget,
  * sized for a multi-second standby wake). The upload path passes
  * `{ retries: settings.fsPartRetries }` to keep its own (lower) budget.
  */
 export async function retryOnTransientReset(fn, options = {}) {
     const retries = options.retries ?? settings.sandboxReadRetries;
+    const gatewayRetries = options.gatewayRetries ?? DEFAULT_GATEWAY_RETRIES;
     const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
     const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
     let attempt = 0;
+    let gatewayAttempt = 0;
     for (;;) {
         try {
             return await fn();
         }
         catch (error) {
+            // Edge gateway timeouts carry an HTTP status, so they are handled here
+            // rather than by the transport-reset branch (which ignores anything with
+            // a status), on their own smaller budget.
+            if (isRetryableGatewayError(error)) {
+                gatewayAttempt++;
+                if (gatewayRetries <= 0 || gatewayAttempt > gatewayRetries) {
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, backoffDelayMs(gatewayAttempt, baseDelayMs, maxDelayMs)));
+                continue;
+            }
             attempt++;
             if (retries <= 0 || attempt > retries || !isTransientResetError(error)) {
                 throw error;

package/dist/esm/sandbox/action.js

@@ -5,31 +5,85 @@ import { createPoolBackedH2Fetch, h2RequestDirectFromPool } from "../common/h2fe
 import { h2Pool } from "../common/h2pool.js";
 import { getForcedUrl, getGlobalUniqueHash } from "../common/internal.js";
 import { settings } from "../common/settings.js";
+import { GATEWAY_ERROR_STATUSES } from "../common/transient-retry.js";
 import { client as defaultClient } from "./client/client.gen.js";
+const GATEWAY_STATUS_TEXT = {
+    502: "Bad Gateway",
+    503: "Gateway Service Unavailable",
+    504: "Gateway Timeout",
+};
+// Pull a short, human-readable detail out of the response payload, if any.
+function extractErrorDetail(data, error) {
+    const fromError = error && typeof error === "object" && "error" in error
+        ? error.error
+        : undefined;
+    const fromData = data && typeof data === "object" && "error" in data
+        ? data.error
+        : undefined;
+    const detail = fromError ?? fromData;
+    if (detail === undefined || detail === null)
+        return undefined;
+    if (typeof detail === "string")
+        return detail;
+    if (typeof detail === "number" || typeof detail === "boolean")
+        return String(detail);
+    try {
+        return JSON.stringify(detail);
+    }
+    catch {
+        return undefined;
+    }
+}
 export class ResponseError extends Error {
     response;
-    data;
     error;
+    /** HTTP status code of the failing response, if any. */
+    status;
+    statusText;
+    /** Parsed response body, when the client managed to parse one. */
+    data;
     constructor(response, data, error) {
-        let dataError = {};
-        if (data && typeof data === 'object' && 'error' in data) {
-            dataError = data;
-        }
-        if (error && typeof error === 'object' && 'error' in error) {
-            dataError['error'] = error.error;
-        }
-        if (response.status) {
-            dataError['status'] = response.status;
-        }
-        if (response.statusText) {
-            dataError['statusText'] = response.statusText;
-        }
-        super(JSON.stringify(dataError));
+        const status = response.status || undefined;
+        const statusText = response.statusText || undefined;
+        const detail = extractErrorDetail(data, error);
+        const label = status !== undefined ? String(status) : "unknown";
+        const suffix = statusText ? ` ${statusText}` : "";
+        const message = `Sandbox request failed with status ${label}${suffix}${detail ? `: ${detail}` : ""}`;
+        super(message);
         this.response = response;
-        this.data = data;
         this.error = error;
+        this.name = "ResponseError";
+        this.status = status;
+        this.statusText = statusText;
+        this.data = data;
+    }
+}
+/**
+ * Thrown when the edge/CDN in front of the sandbox returns a gateway status
+ * (502/503/504) — the request never got a usable answer from the sandbox
+ * itself (it is waking from standby, the command outran the edge's ~60s
+ * origin-read timeout, or the edge could not reach origin). Safe to retry on an
+ * idempotent operation. Catch it with `err instanceof SandboxGatewayError` or
+ * `isGatewayTimeout(err)`.
+ */
+export class SandboxGatewayError extends ResponseError {
+    constructor(response, data, error) {
+        super(response, data, error);
+        this.name = "SandboxGatewayError";
+        const known = this.status !== undefined ? GATEWAY_STATUS_TEXT[this.status] : undefined;
+        this.message = `Sandbox unreachable at the edge gateway (${this.status ?? "unknown"}${known ? ` ${known}` : ""}). The sandbox may be waking from standby or the request outran the edge timeout; retry an idempotent request or poll the sandbox.`;
     }
 }
+/** True when `err` is a gateway status (502/503/504) from the edge. */
+export function isGatewayError(err) {
+    return (err instanceof ResponseError &&
+        err.status !== undefined &&
+        GATEWAY_ERROR_STATUSES.has(err.status));
+}
+/** True when `err` is specifically an edge gateway timeout (504). */
+export function isGatewayTimeout(err) {
+    return err instanceof ResponseError && err.status === 504;
+}
 export class SandboxAction {
     sandbox;
     _h2Client = null;
@@ -119,6 +173,9 @@ export class SandboxAction {
     }
     handleResponseError(response, data, error) {
         if (!response.ok || !data) {
+            if (GATEWAY_ERROR_STATUSES.has(response.status)) {
+                throw new SandboxGatewayError(response, data, error);
+            }
             throw new ResponseError(response, data, error);
         }
     }

package/dist/esm/sandbox/index.js

@@ -1,6 +1,7 @@
 export { 
 /* Export SDK functions */
 deleteFilesystemByPath, deleteNetworkProcessByPidMonitor, deleteProcessByIdentifier, deleteProcessByIdentifierKill, getFilesystemByPath, getNetworkProcessByPidPorts, putCodegenFastapplyByPath, getCodegenRerankingByPath, getProcess, getProcessByIdentifier, getProcessByIdentifierLogs, getProcessByIdentifierLogsStream, postNetworkProcessByPidMonitor, postProcess, putFilesystemByPath } from "./client/index.js";
+export { ResponseError, SandboxGatewayError, isGatewayError, isGatewayTimeout } from "./action.js";
 export * from "./filesystem/index.js";
 export * from "./codegen/index.js";
 export { SandboxDrive } from "./drive/index.js";