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

package/dist/cjs/common/settings.js

@@ -30,8 +30,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.236";
-const BUILD_COMMIT = "08b0c831175e1332396a44bcf769cd4a101c3e28";
+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/cjs/common/transient-retry.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATEWAY_ERROR_STATUSES = void 0;
+exports.isRetryableGatewayError = isRetryableGatewayError;
 exports.isTransientResetError = isTransientResetError;
 exports.backoffDelayMs = backoffDelayMs;
 exports.retryOnTransientReset = retryOnTransientReset;
@@ -22,6 +24,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.
+exports.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.
@@ -56,19 +66,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.
+ */
+function isRetryableGatewayError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const status = getHttpResponseStatus(error);
+    return status !== null && exports.GATEWAY_ERROR_STATUSES.has(status);
 }
 /**
  * True only for transport-level resets/drops that are safe to retry on an
@@ -104,6 +131,11 @@ 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
@@ -123,20 +155,38 @@ 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.
  */
 async function retryOnTransientReset(fn, options = {}) {
     const retries = options.retries ?? settings_js_1.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/cjs/sandbox/action.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxAction = exports.ResponseError = void 0;
+exports.SandboxAction = exports.SandboxGatewayError = exports.ResponseError = void 0;
+exports.isGatewayError = isGatewayError;
+exports.isGatewayTimeout = isGatewayTimeout;
 const client_fetch_1 = require("@hey-api/client-fetch");
 const interceptors_js_1 = require("../client/interceptors.js");
 const responseInterceptor_js_1 = require("../client/responseInterceptor.js");
@@ -8,32 +10,87 @@ const h2fetch_js_1 = require("../common/h2fetch.js");
 const h2pool_js_1 = require("../common/h2pool.js");
 const internal_js_1 = require("../common/internal.js");
 const settings_js_1 = require("../common/settings.js");
+const transient_retry_js_1 = require("../common/transient-retry.js");
 const client_gen_js_1 = require("./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;
+    }
+}
 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;
     }
 }
 exports.ResponseError = ResponseError;
+/**
+ * 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)`.
+ */
+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.`;
+    }
+}
+exports.SandboxGatewayError = SandboxGatewayError;
+/** True when `err` is a gateway status (502/503/504) from the edge. */
+function isGatewayError(err) {
+    return (err instanceof ResponseError &&
+        err.status !== undefined &&
+        transient_retry_js_1.GATEWAY_ERROR_STATUSES.has(err.status));
+}
+/** True when `err` is specifically an edge gateway timeout (504). */
+function isGatewayTimeout(err) {
+    return err instanceof ResponseError && err.status === 504;
+}
 class SandboxAction {
     sandbox;
     _h2Client = null;
@@ -123,6 +180,9 @@ class SandboxAction {
     }
     handleResponseError(response, data, error) {
         if (!response.ok || !data) {
+            if (transient_retry_js_1.GATEWAY_ERROR_STATUSES.has(response.status)) {
+                throw new SandboxGatewayError(response, data, error);
+            }
             throw new ResponseError(response, data, error);
         }
     }

package/dist/cjs/sandbox/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxDrive = exports.putFilesystemByPath = exports.postProcess = exports.postNetworkProcessByPidMonitor = exports.getProcessByIdentifierLogsStream = exports.getProcessByIdentifierLogs = exports.getProcessByIdentifier = exports.getProcess = exports.getCodegenRerankingByPath = exports.putCodegenFastapplyByPath = exports.getNetworkProcessByPidPorts = exports.getFilesystemByPath = exports.deleteProcessByIdentifierKill = exports.deleteProcessByIdentifier = exports.deleteNetworkProcessByPidMonitor = exports.deleteFilesystemByPath = void 0;
+exports.SandboxDrive = exports.isGatewayTimeout = exports.isGatewayError = exports.SandboxGatewayError = exports.ResponseError = exports.putFilesystemByPath = exports.postProcess = exports.postNetworkProcessByPidMonitor = exports.getProcessByIdentifierLogsStream = exports.getProcessByIdentifierLogs = exports.getProcessByIdentifier = exports.getProcess = exports.getCodegenRerankingByPath = exports.putCodegenFastapplyByPath = exports.getNetworkProcessByPidPorts = exports.getFilesystemByPath = exports.deleteProcessByIdentifierKill = exports.deleteProcessByIdentifier = exports.deleteNetworkProcessByPidMonitor = exports.deleteFilesystemByPath = void 0;
 var index_js_1 = require("./client/index.js");
 /* Export SDK functions */
 Object.defineProperty(exports, "deleteFilesystemByPath", { enumerable: true, get: function () { return index_js_1.deleteFilesystemByPath; } });
@@ -32,6 +32,11 @@ Object.defineProperty(exports, "getProcessByIdentifierLogsStream", { enumerable:
 Object.defineProperty(exports, "postNetworkProcessByPidMonitor", { enumerable: true, get: function () { return index_js_1.postNetworkProcessByPidMonitor; } });
 Object.defineProperty(exports, "postProcess", { enumerable: true, get: function () { return index_js_1.postProcess; } });
 Object.defineProperty(exports, "putFilesystemByPath", { enumerable: true, get: function () { return index_js_1.putFilesystemByPath; } });
+var action_js_1 = require("./action.js");
+Object.defineProperty(exports, "ResponseError", { enumerable: true, get: function () { return action_js_1.ResponseError; } });
+Object.defineProperty(exports, "SandboxGatewayError", { enumerable: true, get: function () { return action_js_1.SandboxGatewayError; } });
+Object.defineProperty(exports, "isGatewayError", { enumerable: true, get: function () { return action_js_1.isGatewayError; } });
+Object.defineProperty(exports, "isGatewayTimeout", { enumerable: true, get: function () { return action_js_1.isGatewayTimeout; } });
 __exportStar(require("./filesystem/index.js"), exports);
 __exportStar(require("./codegen/index.js"), exports);
 var index_js_2 = require("./drive/index.js");

package/dist/cjs/types/common/transient-retry.d.ts

@@ -1,3 +1,12 @@
+export declare const GATEWAY_ERROR_STATUSES: Set<number>;
+/**
+ * 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 declare function isRetryableGatewayError(error: unknown): boolean;
 /**
  * True only for transport-level resets/drops that are safe to retry on an
  * IDEMPOTENT request (transient HTTP/2 stream reset, GOAWAY, or a dropped
@@ -14,6 +23,12 @@ export declare function isTransientResetError(error: unknown): boolean;
 export declare function backoffDelayMs(attempt: number, baseDelayMs: number, maxDelayMs: number): number;
 export type RetryOptions = {
     retries?: number;
+    /**
+     * Retry budget for edge gateway statuses (502/503/504). Defaults to a small
+     * value (2) because each attempt can cost the edge's ~60s origin-read timeout.
+     * Set `0` to disable gateway retries.
+     */
+    gatewayRetries?: number;
     baseDelayMs?: number;
     maxDelayMs?: number;
 };
@@ -24,6 +39,11 @@ export type RetryOptions = {
  * 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.

package/dist/cjs/types/sandbox/action.d.ts

@@ -2,10 +2,29 @@ import { type Client } from "@hey-api/client-fetch";
 import { SandboxConfiguration } from "./types.js";
 export declare class ResponseError extends Error {
     response: Response;
-    data: unknown;
     error: unknown;
+    /** HTTP status code of the failing response, if any. */
+    readonly status?: number;
+    readonly statusText?: string;
+    /** Parsed response body, when the client managed to parse one. */
+    readonly data: unknown;
     constructor(response: Response, data: unknown, error: unknown);
 }
+/**
+ * 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 declare class SandboxGatewayError extends ResponseError {
+    constructor(response: Response, data: unknown, error: unknown);
+}
+/** True when `err` is a gateway status (502/503/504) from the edge. */
+export declare function isGatewayError(err: unknown): boolean;
+/** True when `err` is specifically an edge gateway timeout (504). */
+export declare function isGatewayTimeout(err: unknown): boolean;
 export declare class SandboxAction {
     protected sandbox: SandboxConfiguration;
     private _h2Client;

package/dist/cjs/types/sandbox/index.d.ts

@@ -1,4 +1,5 @@
 export { deleteFilesystemByPath, deleteNetworkProcessByPidMonitor, deleteProcessByIdentifier, deleteProcessByIdentifierKill, Directory, ErrorResponse, File, FileRequest, FileWithContent, getFilesystemByPath, getNetworkProcessByPidPorts, putCodegenFastapplyByPath, ApplyEditResponse, ApplyEditRequest, getCodegenRerankingByPath, RerankingResponse, getProcess, getProcessByIdentifier, getProcessByIdentifierLogs, getProcessByIdentifierLogsStream, PortMonitorRequest, postNetworkProcessByPidMonitor, postProcess, ProcessRequest, ProcessResponse, putFilesystemByPath, SuccessResponse } from "./client/index.js";
+export { ResponseError, SandboxGatewayError, isGatewayError, isGatewayTimeout } from "./action.js";
 export * from "./filesystem/index.js";
 export * from "./codegen/index.js";
 export { SandboxDrive, type DriveMountRequest, type DriveMountResponse, type DriveMountInfo, type DriveUnmountResponse } from "./drive/index.js";