@alibaba-group/opensandbox 0.1.3 → 0.1.5

package/dist/cjs/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ConnectionConfig: () => ConnectionConfig,
+  DEFAULT_EGRESS_PORT: () => DEFAULT_EGRESS_PORT,
   DEFAULT_ENTRYPOINT: () => DEFAULT_ENTRYPOINT,
   DEFAULT_EXECD_PORT: () => DEFAULT_EXECD_PORT,
   DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS: () => DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
@@ -69,25 +70,26 @@ var SandboxException = class extends Error {
   name = "SandboxException";
   error;
   cause;
+  requestId;
   constructor(opts = {}) {
     super(opts.message);
     this.cause = opts.cause;
     this.error = opts.error ?? new SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR);
+    this.requestId = opts.requestId;
   }
 };
 var SandboxApiException = class extends SandboxException {
   name = "SandboxApiException";
   statusCode;
-  requestId;
   rawBody;
   constructor(opts) {
     super({
       message: opts.message,
       cause: opts.cause,
-      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message)
+      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message),
+      requestId: opts.requestId
     });
     this.statusCode = opts.statusCode;
-    this.requestId = opts.requestId;
     this.rawBody = opts.rawBody;
   }
 };
@@ -143,8 +145,19 @@ function createExecdClient(opts) {
   });
 }
 
-// src/openapi/lifecycleClient.ts
+// src/openapi/egressClient.ts
 var import_openapi_fetch2 = __toESM(require("openapi-fetch"), 1);
+function createEgressClient(opts) {
+  const createClientFn = import_openapi_fetch2.default.default ?? import_openapi_fetch2.default;
+  return createClientFn({
+    baseUrl: opts.baseUrl,
+    headers: opts.headers,
+    fetch: opts.fetch
+  });
+}
+
+// src/openapi/lifecycleClient.ts
+var import_openapi_fetch3 = __toESM(require("openapi-fetch"), 1);
 function readEnvApiKey() {
   const env = globalThis?.process?.env;
   const v = env?.OPEN_SANDBOX_API_KEY;
@@ -158,7 +171,7 @@ function createLifecycleClient(opts = {}) {
   if (apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
     headers["OPEN-SANDBOX-API-KEY"] = apiKey;
   }
-  const createClientFn = import_openapi_fetch2.default.default ?? import_openapi_fetch2.default;
+  const createClientFn = import_openapi_fetch3.default.default ?? import_openapi_fetch3.default;
   return createClientFn({
     baseUrl: opts.baseUrl ?? "http://localhost:8080/v1",
     headers,
@@ -322,11 +335,61 @@ function joinUrl(baseUrl, pathname) {
   return `${base}${path}`;
 }
 function toRunCommandRequest(command, opts) {
-  return {
+  if (opts?.gid != null && opts.uid == null) {
+    throw new Error("uid is required when gid is provided");
+  }
+  const body = {
     command,
     cwd: opts?.workingDirectory,
     background: !!opts?.background
   };
+  if (opts?.timeoutSeconds != null) {
+    body.timeout = Math.round(opts.timeoutSeconds * 1e3);
+  }
+  if (opts?.uid != null) {
+    body.uid = opts.uid;
+  }
+  if (opts?.gid != null) {
+    body.gid = opts.gid;
+  }
+  if (opts?.envs != null) {
+    body.envs = opts.envs;
+  }
+  return body;
+}
+function toRunInSessionRequest(command, opts) {
+  const body = {
+    command
+  };
+  if (opts?.workingDirectory != null) {
+    body.cwd = opts.workingDirectory;
+  }
+  if (opts?.timeout != null) {
+    body.timeout = opts.timeout;
+  }
+  return body;
+}
+function inferForegroundExitCode(execution) {
+  const errorValue = execution.error?.value?.trim();
+  const parsedExitCode = errorValue && /^-?\d+$/.test(errorValue) ? Number(errorValue) : Number.NaN;
+  return execution.error != null ? Number.isFinite(parsedExitCode) ? parsedExitCode : null : execution.complete ? 0 : null;
+}
+function assertNonBlank(value, field) {
+  if (!value.trim()) {
+    throw new Error(`${field} cannot be empty`);
+  }
+}
+function parseOptionalDate(value, field) {
+  if (value == null) return void 0;
+  if (value instanceof Date) return value;
+  if (typeof value !== "string") {
+    throw new Error(`Invalid ${field}: expected ISO string, got ${typeof value}`);
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(`Invalid ${field}: ${value}`);
+  }
+  return parsed;
 }
 var CommandsAdapter = class {
   constructor(client, opts) {
@@ -335,43 +398,172 @@ var CommandsAdapter = class {
     this.fetch = opts.fetch ?? fetch;
   }
   fetch;
-  async interrupt(sessionId) {
-    const { error, response } = await this.client.DELETE("/command", {
-      params: { query: { id: sessionId } }
-    });
-    throwOnOpenApiFetchError({ error, response }, "Interrupt command failed");
+  buildRunStreamSpec(command, opts) {
+    assertNonBlank(command, "command");
+    return {
+      pathname: "/command",
+      body: toRunCommandRequest(command, opts),
+      fallbackErrorMessage: "Run command failed"
+    };
   }
-  async *runStream(command, opts, signal) {
-    const url = joinUrl(this.opts.baseUrl, "/command");
-    const body = JSON.stringify(toRunCommandRequest(command, opts));
+  buildRunInSessionStreamSpec(sessionId, command, opts) {
+    assertNonBlank(sessionId, "sessionId");
+    assertNonBlank(command, "command");
+    return {
+      pathname: `/session/${encodeURIComponent(sessionId)}/run`,
+      body: toRunInSessionRequest(command, opts),
+      fallbackErrorMessage: "Run in session failed"
+    };
+  }
+  async *streamExecution(spec, signal) {
+    const url = joinUrl(this.opts.baseUrl, spec.pathname);
     const res = await this.fetch(url, {
       method: "POST",
       headers: {
-        "accept": "text/event-stream",
+        accept: "text/event-stream",
         "content-type": "application/json",
         ...this.opts.headers ?? {}
       },
-      body,
+      body: JSON.stringify(spec.body),
       signal
     });
-    for await (const ev of parseJsonEventStream(res, { fallbackErrorMessage: "Run command failed" })) {
+    for await (const ev of parseJsonEventStream(res, {
+      fallbackErrorMessage: spec.fallbackErrorMessage
+    })) {
       yield ev;
     }
   }
-  async run(command, opts, handlers, signal) {
+  async consumeExecutionStream(stream, handlers, inferExitCode = false) {
     const execution = {
       logs: { stdout: [], stderr: [] },
       result: []
     };
     const dispatcher = new ExecutionEventDispatcher(execution, handlers);
-    for await (const ev of this.runStream(command, opts, signal)) {
+    for await (const ev of stream) {
       if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
         ev.text = execution.id;
       }
       await dispatcher.dispatch(ev);
     }
+    if (inferExitCode) {
+      execution.exitCode = inferForegroundExitCode(execution);
+    }
     return execution;
   }
+  async interrupt(sessionId) {
+    const { error, response } = await this.client.DELETE("/command", {
+      params: { query: { id: sessionId } }
+    });
+    throwOnOpenApiFetchError({ error, response }, "Interrupt command failed");
+  }
+  async getCommandStatus(commandId) {
+    const { data, error, response } = await this.client.GET("/command/status/{id}", {
+      params: { path: { id: commandId } }
+    });
+    throwOnOpenApiFetchError({ error, response }, "Get command status failed");
+    const ok = data;
+    if (!ok || typeof ok !== "object") {
+      throw new Error("Get command status failed: unexpected response shape");
+    }
+    return {
+      id: ok.id,
+      content: ok.content,
+      running: ok.running,
+      exitCode: ok.exit_code ?? null,
+      error: ok.error,
+      startedAt: parseOptionalDate(ok.started_at, "startedAt"),
+      finishedAt: parseOptionalDate(ok.finished_at, "finishedAt") ?? null
+    };
+  }
+  async getBackgroundCommandLogs(commandId, cursor) {
+    const { data, error, response } = await this.client.GET("/command/{id}/logs", {
+      params: { path: { id: commandId }, query: cursor == null ? {} : { cursor } },
+      parseAs: "text"
+    });
+    throwOnOpenApiFetchError({ error, response }, "Get command logs failed");
+    const ok = data;
+    if (typeof ok !== "string") {
+      throw new Error("Get command logs failed: unexpected response shape");
+    }
+    const cursorHeader = response.headers.get("EXECD-COMMANDS-TAIL-CURSOR");
+    const parsedCursor = cursorHeader != null && cursorHeader !== "" ? Number(cursorHeader) : void 0;
+    return {
+      content: ok,
+      cursor: Number.isFinite(parsedCursor ?? NaN) ? parsedCursor : void 0
+    };
+  }
+  async *runStream(command, opts, signal) {
+    for await (const ev of this.streamExecution(
+      this.buildRunStreamSpec(command, opts),
+      signal
+    )) {
+      yield ev;
+    }
+  }
+  async run(command, opts, handlers, signal) {
+    return this.consumeExecutionStream(
+      this.runStream(command, opts, signal),
+      handlers,
+      !opts?.background
+    );
+  }
+  async createSession(options) {
+    const body = options?.workingDirectory != null ? { cwd: options.workingDirectory } : {};
+    const { data, error, response } = await this.client.POST("/session", {
+      body
+    });
+    throwOnOpenApiFetchError({ error, response }, "Create session failed");
+    const ok = data;
+    if (!ok || typeof ok.session_id !== "string") {
+      throw new Error("Create session failed: unexpected response shape");
+    }
+    return ok.session_id;
+  }
+  async *runInSessionStream(sessionId, command, opts, signal) {
+    for await (const ev of this.streamExecution(
+      this.buildRunInSessionStreamSpec(sessionId, command, opts),
+      signal
+    )) {
+      yield ev;
+    }
+  }
+  async runInSession(sessionId, command, options, handlers, signal) {
+    return this.consumeExecutionStream(
+      this.runInSessionStream(sessionId, command, options, signal),
+      handlers,
+      true
+    );
+  }
+  async deleteSession(sessionId) {
+    const { error, response } = await this.client.DELETE(
+      "/session/{sessionId}",
+      { params: { path: { sessionId } } }
+    );
+    throwOnOpenApiFetchError({ error, response }, "Delete session failed");
+  }
+};
+
+// src/adapters/egressAdapter.ts
+var EgressAdapter = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async getPolicy() {
+    const { data, error, response } = await this.client.GET("/policy");
+    throwOnOpenApiFetchError({ error, response }, "Get sandbox egress policy failed");
+    const raw = data;
+    if (!raw || typeof raw !== "object" || !raw.policy || typeof raw.policy !== "object") {
+      throw new Error("Get sandbox egress policy failed: unexpected response shape");
+    }
+    return raw.policy;
+  }
+  async patchRules(rules) {
+    const body = rules;
+    const { error, response } = await this.client.PATCH("/policy", {
+      body
+    });
+    throwOnOpenApiFetchError({ error, response }, "Patch sandbox egress rules failed");
+  }
 };
 
 // src/adapters/filesystemAdapter.ts
@@ -859,11 +1051,15 @@ var SandboxesAdapter = class {
     }
     return d;
   }
+  parseOptionalIsoDate(field, v) {
+    if (v == null) return null;
+    return this.parseIsoDate(field, v);
+  }
   mapSandboxInfo(raw) {
     return {
       ...raw ?? {},
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt)
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt)
     };
   }
   async createSandbox(req) {
@@ -879,7 +1075,7 @@ var SandboxesAdapter = class {
     return {
       ...raw ?? {},
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt)
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt)
     };
   }
   async getSandbox(sandboxId) {
@@ -950,9 +1146,9 @@ var SandboxesAdapter = class {
       expiresAt: raw?.expiresAt ? this.parseIsoDate("expiresAt", raw.expiresAt) : void 0
     };
   }
-  async getSandboxEndpoint(sandboxId, port) {
+  async getSandboxEndpoint(sandboxId, port, useServerProxy = false) {
     const { data, error, response } = await this.client.GET("/sandboxes/{sandboxId}/endpoints/{port}", {
-      params: { path: { sandboxId, port } }
+      params: { path: { sandboxId, port }, query: { use_server_proxy: useServerProxy } }
     });
     throwOnOpenApiFetchError({ error, response }, "Get sandbox endpoint failed");
     const ok = data;
@@ -976,9 +1172,13 @@ var DefaultAdapterFactory = class {
     return { sandboxes };
   }
   createExecdStack(opts) {
+    const headers = {
+      ...opts.connectionConfig.headers ?? {},
+      ...opts.endpointHeaders ?? {}
+    };
     const execdClient = createExecdClient({
       baseUrl: opts.execdBaseUrl,
-      headers: opts.connectionConfig.headers,
+      headers,
       fetch: opts.connectionConfig.fetch
     });
     const health = new HealthAdapter(execdClient);
@@ -986,12 +1186,12 @@ var DefaultAdapterFactory = class {
     const files = new FilesystemAdapter(execdClient, {
       baseUrl: opts.execdBaseUrl,
       fetch: opts.connectionConfig.fetch,
-      headers: opts.connectionConfig.headers
+      headers
     });
     const commands = new CommandsAdapter(execdClient, {
       baseUrl: opts.execdBaseUrl,
       fetch: opts.connectionConfig.sseFetch,
-      headers: opts.connectionConfig.headers
+      headers
     });
     return {
       commands,
@@ -1000,6 +1200,20 @@ var DefaultAdapterFactory = class {
       metrics
     };
   }
+  createEgressStack(opts) {
+    const headers = {
+      ...opts.connectionConfig.headers ?? {},
+      ...opts.endpointHeaders ?? {}
+    };
+    const egressClient = createEgressClient({
+      baseUrl: opts.egressBaseUrl,
+      headers,
+      fetch: opts.connectionConfig.fetch
+    });
+    return {
+      egress: new EgressAdapter(egressClient)
+    };
+  }
 };
 function createDefaultAdapterFactory() {
   return new DefaultAdapterFactory();
@@ -1007,6 +1221,7 @@ function createDefaultAdapterFactory() {
 
 // src/core/constants.ts
 var DEFAULT_EXECD_PORT = 44772;
+var DEFAULT_EGRESS_PORT = 18080;
 var DEFAULT_ENTRYPOINT = ["tail", "-f", "/dev/null"];
 var DEFAULT_RESOURCE_LIMITS = {
   cpu: "1",
@@ -1016,7 +1231,7 @@ var DEFAULT_TIMEOUT_SECONDS = 600;
 var DEFAULT_READY_TIMEOUT_SECONDS = 30;
 var DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS = 200;
 var DEFAULT_REQUEST_TIMEOUT_SECONDS = 30;
-var DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.1";
+var DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.5";
 
 // src/config/connection.ts
 function isNodeRuntime2() {
@@ -1168,6 +1383,10 @@ var ConnectionConfig = class _ConnectionConfig {
   requestTimeoutSeconds;
   debug;
   userAgent = DEFAULT_USER_AGENT;
+  /**
+   * Use sandbox server as proxy for endpoint requests (default false).
+   */
+  useServerProxy;
   _closeTransport;
   _closePromise = null;
   _transportInitialized = false;
@@ -1188,6 +1407,7 @@ var ConnectionConfig = class _ConnectionConfig {
     this.apiKey = opts.apiKey ?? envApiKey;
     this.requestTimeoutSeconds = typeof opts.requestTimeoutSeconds === "number" ? opts.requestTimeoutSeconds : 30;
     this.debug = !!opts.debug;
+    this.useServerProxy = !!opts.useServerProxy;
     const headers = { ...opts.headers ?? {} };
     if (this.apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
       headers["OPEN-SANDBOX-API-KEY"] = this.apiKey;
@@ -1251,7 +1471,8 @@ var ConnectionConfig = class _ConnectionConfig {
       apiKey: this.apiKey,
       headers: { ...this.headers },
       requestTimeoutSeconds: this.requestTimeoutSeconds,
-      debug: this.debug
+      debug: this.debug,
+      useServerProxy: this.useServerProxy
     });
     clone.initializeTransport();
     return clone;
@@ -1367,7 +1588,8 @@ var Sandbox = class _Sandbox {
     _Sandbox._priv.set(this, {
       adapterFactory: opts.adapterFactory,
       lifecycleBaseUrl: opts.lifecycleBaseUrl,
-      execdBaseUrl: opts.execdBaseUrl
+      execdBaseUrl: opts.execdBaseUrl,
+      egress: opts.egress
     });
     this.sandboxes = opts.sandboxes;
     this.commands = opts.commands;
@@ -1390,10 +1612,31 @@ var Sandbox = class _Sandbox {
       await connectionConfig.closeTransport();
       throw err;
     }
+    if (opts.volumes) {
+      for (const vol of opts.volumes) {
+        const backendsSpecified = [vol.host, vol.pvc, vol.ossfs].filter((b) => b != null).length;
+        if (backendsSpecified === 0) {
+          throw new Error(
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but none was provided.`
+          );
+        }
+        if (backendsSpecified > 1) {
+          throw new Error(
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but multiple were provided.`
+          );
+        }
+      }
+    }
+    const rawTimeout = opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const timeoutSeconds = opts.timeoutSeconds === null ? null : Math.floor(rawTimeout);
+    if (timeoutSeconds !== null && !Number.isFinite(timeoutSeconds)) {
+      throw new Error(
+        `timeoutSeconds must be a finite number, got ${opts.timeoutSeconds}`
+      );
+    }
     const req = {
       image: toImageSpec(opts.image),
       entrypoint: opts.entrypoint ?? DEFAULT_ENTRYPOINT,
-      timeout: Math.floor(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS),
       resourceLimits: opts.resource ?? DEFAULT_RESOURCE_LIMITS,
       env: opts.env ?? {},
       metadata: opts.metadata ?? {},
@@ -1401,20 +1644,37 @@ var Sandbox = class _Sandbox {
         ...opts.networkPolicy,
         defaultAction: opts.networkPolicy.defaultAction ?? "deny"
       } : void 0,
+      volumes: opts.volumes,
       extensions: opts.extensions ?? {}
     };
+    if (timeoutSeconds !== null) {
+      req.timeout = timeoutSeconds;
+    }
     let sandboxId;
     try {
       const created = await sandboxes.createSandbox(req);
       sandboxId = created.id;
       const endpoint = await sandboxes.getSandboxEndpoint(
         sandboxId,
-        DEFAULT_EXECD_PORT
+        DEFAULT_EXECD_PORT,
+        connectionConfig.useServerProxy
+      );
+      const egressEndpoint = await sandboxes.getSandboxEndpoint(
+        sandboxId,
+        DEFAULT_EGRESS_PORT,
+        connectionConfig.useServerProxy
       );
       const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+      const egressBaseUrl = `${connectionConfig.protocol}://${egressEndpoint.endpoint}`;
       const { commands, files, health, metrics } = adapterFactory.createExecdStack({
         connectionConfig,
-        execdBaseUrl
+        execdBaseUrl,
+        endpointHeaders: endpoint.headers
+      });
+      const { egress } = adapterFactory.createEgressStack({
+        connectionConfig,
+        egressBaseUrl,
+        endpointHeaders: egressEndpoint.headers
       });
       const sbx = new _Sandbox({
         id: sandboxId,
@@ -1426,7 +1686,8 @@ var Sandbox = class _Sandbox {
         commands,
         files,
         health,
-        metrics
+        metrics,
+        egress
       });
       if (!(opts.skipHealthCheck ?? false)) {
         await sbx.waitUntilReady({
@@ -1465,12 +1726,25 @@ var Sandbox = class _Sandbox {
     try {
       const endpoint = await sandboxes.getSandboxEndpoint(
         opts.sandboxId,
-        DEFAULT_EXECD_PORT
+        DEFAULT_EXECD_PORT,
+        connectionConfig.useServerProxy
+      );
+      const egressEndpoint = await sandboxes.getSandboxEndpoint(
+        opts.sandboxId,
+        DEFAULT_EGRESS_PORT,
+        connectionConfig.useServerProxy
       );
       const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+      const egressBaseUrl = `${connectionConfig.protocol}://${egressEndpoint.endpoint}`;
       const { commands, files, health, metrics } = adapterFactory.createExecdStack({
         connectionConfig,
-        execdBaseUrl
+        execdBaseUrl,
+        endpointHeaders: endpoint.headers
+      });
+      const { egress } = adapterFactory.createEgressStack({
+        connectionConfig,
+        egressBaseUrl,
+        endpointHeaders: egressEndpoint.headers
       });
       const sbx = new _Sandbox({
         id: opts.sandboxId,
@@ -1482,7 +1756,8 @@ var Sandbox = class _Sandbox {
         commands,
         files,
         health,
-        metrics
+        metrics,
+        egress
       });
       if (!(opts.skipHealthCheck ?? false)) {
         await sbx.waitUntilReady({
@@ -1570,11 +1845,21 @@ var Sandbox = class _Sandbox {
     ).toISOString();
     return await this.sandboxes.renewSandboxExpiration(this.id, { expiresAt });
   }
+  async getEgressPolicy() {
+    return await _Sandbox._priv.get(this).egress.getPolicy();
+  }
+  async patchEgressRules(rules) {
+    await _Sandbox._priv.get(this).egress.patchRules(rules);
+  }
   /**
    * Get sandbox endpoint for a port (STRICT: no scheme), e.g. "localhost:44772" or "domain/route/.../44772".
    */
   async getEndpoint(port) {
-    return await this.sandboxes.getSandboxEndpoint(this.id, port);
+    return await this.sandboxes.getSandboxEndpoint(
+      this.id,
+      port,
+      this.connectionConfig.useServerProxy
+    );
   }
   /**
    * Get absolute endpoint URL with scheme (convenience for HTTP clients).
@@ -1585,21 +1870,39 @@ var Sandbox = class _Sandbox {
   }
   async waitUntilReady(opts) {
     const deadline = Date.now() + opts.readyTimeoutSeconds * 1e3;
+    let attempt = 0;
+    let errorDetail = "Health check returned false continuously.";
+    const buildTimeoutMessage = () => {
+      const context = `domain=${this.connectionConfig.domain}, useServerProxy=${this.connectionConfig.useServerProxy}`;
+      let suggestion = "If this sandbox runs in Docker bridge or remote-network mode, consider enabling useServerProxy=true.";
+      if (!this.connectionConfig.useServerProxy) {
+        suggestion += " You can also configure server-side [docker].host_ip for direct endpoint access.";
+      }
+      return `Sandbox health check timed out after ${opts.readyTimeoutSeconds}s (${attempt} attempts). ${errorDetail} Connection context: ${context}. ${suggestion}`;
+    };
     while (true) {
       if (Date.now() > deadline) {
         throw new SandboxReadyTimeoutException({
-          message: `Sandbox not ready: timed out waiting for health check (timeoutSeconds=${opts.readyTimeoutSeconds})`
+          message: buildTimeoutMessage()
         });
       }
+      attempt++;
       try {
         if (opts.healthCheck) {
           const ok = await opts.healthCheck(this);
-          if (ok) return;
+          if (ok) {
+            return;
+          }
         } else {
           const ok = await this.health.ping();
-          if (ok) return;
+          if (ok) {
+            return;
+          }
         }
-      } catch {
+        errorDetail = "Health check returned false continuously.";
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errorDetail = `Last health check error: ${message}`;
       }
       await sleep(opts.pollingIntervalMillis);
     }
@@ -1608,6 +1911,7 @@ var Sandbox = class _Sandbox {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConnectionConfig,
+  DEFAULT_EGRESS_PORT,
   DEFAULT_ENTRYPOINT,
   DEFAULT_EXECD_PORT,
   DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,