tensorlake 0.5.135 → 0.5.136

package/dist/index.cjs

@@ -49,7 +49,7 @@ var init_defaults = __esm({
   "src/defaults.ts"() {
     "use strict";
     init_cjs_shims();
-    SDK_VERSION = "0.5.135";
+    SDK_VERSION = "0.5.136";
     API_URL = process.env.TENSORLAKE_API_URL ?? "https://api.tensorlake.ai";
     API_KEY = process.env.TENSORLAKE_API_KEY ?? void 0;
     NAMESPACE = process.env.INDEXIFY_NAMESPACE ?? "default";
@@ -82,7 +82,7 @@ function formatErrorDetails(errorDetails) {
   }
   return String(errorDetails);
 }
-var SandboxException, SandboxError, SandboxConnectionError, SandboxNotFoundError, PoolNotFoundError, PoolInUseError, RemoteAPIError, RequestNotFinishedError, RequestFailedError, RequestExecutionError;
+var SandboxException, SandboxError, SandboxPending, SandboxConnectionError, SandboxNotFoundError, PoolNotFoundError, PoolInUseError, RemoteAPIError, RequestNotFinishedError, RequestFailedError, RequestExecutionError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -94,9 +94,27 @@ var init_errors = __esm({
       }
     };
     SandboxError = class extends SandboxException {
-      constructor(message) {
+      reason;
+      sandboxId;
+      constructor(message, options) {
         super(message);
         this.name = "SandboxError";
+        if (options?.reason !== void 0) this.reason = options.reason;
+        if (options?.sandboxId !== void 0) this.sandboxId = options.sandboxId;
+      }
+    };
+    SandboxPending = class extends SandboxError {
+      pendingReason;
+      timeout;
+      constructor(sandboxId, options) {
+        let message = `Sandbox ${sandboxId} is still pending`;
+        if (options?.timeout !== void 0) message += ` after ${options.timeout}s`;
+        if (options?.pendingReason) message += ` (${options.pendingReason})`;
+        message += `; it keeps its place in the queue. Wait again with ready() or Sandbox.connect({ sandboxId: '${sandboxId}' }), or delete it to cancel.`;
+        super(message, { reason: options?.pendingReason, sandboxId });
+        this.name = "SandboxPending";
+        this.pendingReason = options?.pendingReason;
+        this.timeout = options?.timeout;
       }
     };
     SandboxConnectionError = class extends SandboxError {
@@ -107,11 +125,9 @@ var init_errors = __esm({
       }
     };
     SandboxNotFoundError = class extends SandboxError {
-      sandboxId;
       constructor(sandboxId) {
-        super(`Sandbox not found: ${sandboxId}`);
+        super(`Sandbox not found: ${sandboxId}`, { sandboxId });
         this.name = "SandboxNotFoundError";
-        this.sandboxId = sandboxId;
       }
     };
     PoolNotFoundError = class extends SandboxError {
@@ -135,9 +151,6 @@ var init_errors = __esm({
       statusCode;
       /** Original response body, retained for compatibility and diagnostics. */
       responseMessage;
-      sandboxId;
-      /** Server reason, including unknown future reasons. */
-      reason;
       errorDetails;
       constructor(statusCode, message) {
         let failure;
@@ -162,9 +175,10 @@ var init_errors = __esm({
           if (detail) displayMessage += `: ${detail}`;
           if (!reason && !detail) displayMessage = message;
         }
-        super(`API error (status ${statusCode}): ${displayMessage}`);
-        this.sandboxId = sandboxId;
-        this.reason = reason;
+        super(`API error (status ${statusCode}): ${displayMessage}`, {
+          reason,
+          sandboxId
+        });
         this.errorDetails = errorDetails;
         this.name = "RemoteAPIError";
         this.statusCode = statusCode;
@@ -460,7 +474,7 @@ var init_native_worker_client = __esm({
       }
     };
     runtimeKey = /* @__PURE__ */ Symbol.for(
-      `tensorlake.native.worker.${false ? "source" : "0.5.135"}.v1`
+      `tensorlake.native.worker.${false ? "source" : "0.5.136"}.v1`
     );
     runtimes = globalThis;
   }
@@ -612,6 +626,9 @@ var init_native_sandbox = __esm({
 });
 
 // src/models.ts
+function isSandboxPending(status) {
+  return String(status) === "pending" /* PENDING */;
+}
 function camelToSnake(str) {
   return str.replace(CAMEL_TO_SNAKE_RE, (ch) => "_" + ch.toLowerCase());
 }
@@ -668,7 +685,7 @@ function fromSnakeKeys(obj, idField) {
   }
   return obj;
 }
-var SandboxStatus, SnapshotStatus, ProcessStatus, StdinMode, OutputMode, ContainerState, CAMEL_TO_SNAKE_RE;
+var SandboxStatus, SandboxPendingReason, TERMINATION_REASON_NO_CAPACITY, TERMINATION_REASON_CANCELLED, SnapshotStatus, ProcessStatus, StdinMode, OutputMode, ContainerState, CAMEL_TO_SNAKE_RE;
 var init_models = __esm({
   "src/models.ts"() {
     "use strict";
@@ -684,6 +701,19 @@ var init_models = __esm({
       SandboxStatus2["FAILED"] = "failed";
       return SandboxStatus2;
     })(SandboxStatus || {});
+    SandboxPendingReason = /* @__PURE__ */ ((SandboxPendingReason2) => {
+      SandboxPendingReason2["SCHEDULING"] = "scheduling";
+      SandboxPendingReason2["WAITING_FOR_CONTAINER"] = "waiting_for_container";
+      SandboxPendingReason2["NO_EXECUTORS_AVAILABLE"] = "no_executors_available";
+      SandboxPendingReason2["NO_RESOURCES_AVAILABLE"] = "no_resources_available";
+      SandboxPendingReason2["POOL_AT_CAPACITY"] = "pool_at_capacity";
+      SandboxPendingReason2["MAX_CAPACITY_REACHED"] = "max_capacity_reached";
+      SandboxPendingReason2["NO_EXECUTOR_FOR_SNAPSHOT_LOCATION"] = "no_executor_for_snapshot_location";
+      SandboxPendingReason2["UNPLACEABLE"] = "unplaceable";
+      return SandboxPendingReason2;
+    })(SandboxPendingReason || {});
+    TERMINATION_REASON_NO_CAPACITY = "no_capacity";
+    TERMINATION_REASON_CANCELLED = "cancelled";
     SnapshotStatus = /* @__PURE__ */ ((SnapshotStatus2) => {
       SnapshotStatus2["IN_PROGRESS"] = "in_progress";
       SnapshotStatus2["LOCAL_READY"] = "local_ready";
@@ -717,6 +747,64 @@ var init_models = __esm({
   }
 });
 
+// src/pending-sandbox.ts
+var PendingSandbox;
+var init_pending_sandbox = __esm({
+  "src/pending-sandbox.ts"() {
+    "use strict";
+    init_cjs_shims();
+    PendingSandbox = class {
+      /** @internal */
+      constructor(record, binding) {
+        this.binding = binding;
+        this.sandboxId = record.sandboxId;
+        this.name = record.name;
+        this.state = record.state;
+        this.pendingReason = record.pendingReason;
+        this.routingHint = record.routingHint;
+        this.ingressEndpoint = record.ingressEndpoint;
+        this.sandboxUrl = record.sandboxUrl;
+        this.reason = record.reason;
+        this.terminationReason = record.terminationReason;
+        this.errorDetails = record.errorDetails;
+        this.traceId = binding.traceId;
+      }
+      sandboxId;
+      name;
+      state;
+      pendingReason;
+      routingHint;
+      ingressEndpoint;
+      sandboxUrl;
+      reason;
+      terminationReason;
+      errorDetails;
+      /** W3C trace id of the create request. */
+      traceId;
+      /** Fetch the sandbox's current state with one `GET`. */
+      async status() {
+        return this.binding.client.get(this.sandboxId);
+      }
+      /**
+       * Wait for the sandbox to be running and return a connected `Sandbox`.
+       *
+       * Polls `GET /sandboxes/{id}` every `pollInterval` seconds (default 2).
+       * Call it again after a `SandboxPending` to keep waiting.
+       *
+       * @throws {SandboxPending} `timeout` elapsed while the sandbox was still
+       *   pending. It keeps its place in the queue; the error carries
+       *   `sandboxId` and `pendingReason`.
+       * @throws {SandboxError} The sandbox settled somewhere else: `terminated`
+       *   or `failed` (`reason` is the server's, such as `no_capacity` or
+       *   `cancelled`), or `suspended`.
+       */
+      async ready(options) {
+        return this.binding.client._ready(this.sandboxId, this.binding, options);
+      }
+    };
+  }
+});
+
 // src/tunnel.ts
 async function openTunnelWebSocket(options) {
   const wsUrl = buildTunnelWsUrl(options.baseUrl, options.remotePort);
@@ -3638,17 +3726,10 @@ var init_sandbox = __esm({
         this.ownsSandbox = true;
         this.lifecycleClient = client;
       }
-      // --- Static factory methods ---
-      /**
-       * Create a new sandbox and return a connected, running handle.
-       *
-       * Covers both fresh sandbox creation and restore-from-snapshot (set
-       * `snapshotId`). Blocks until the sandbox is `Running`.
-       *
-       * When `name` is already claimed, the server rejects the create with
-       * HTTP 409 (`RemoteAPIError`). To attach to the existing sandbox
-       * instead, use {@link Sandbox.getOrCreate}.
-       */
+      /** @internal Used by PendingSandbox.ready for a non-owning handle. */
+      _setLifecycleClient(client) {
+        this.lifecycleClient = client;
+      }
       static async create(options) {
         const { SandboxClient: SandboxClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
         const client = new SandboxClient2(
@@ -3656,6 +3737,19 @@ var init_sandbox = __esm({
           /* _internal */
           true
         );
+        if (options?.wait === false) {
+          if (options.poolId != null) {
+            throw new SandboxError(
+              "wait: false cannot be combined with poolId: a pool claim is answered synchronously"
+            );
+          }
+          const requestTimeout = options.requestTimeout ?? options.startupTimeout ?? void 0;
+          return client.requestPending(options, {
+            proxyUrl: options.proxyUrl,
+            requestTimeout,
+            ownsSandbox: true
+          });
+        }
         return client.createAndConnect(options);
       }
       /**
@@ -3946,6 +4040,7 @@ var init_sandbox = __esm({
        */
       async refreshRoutingWhenRunning(deadline, pollInterval, timeout) {
         const client = this.requireLifecycleClient("refresh proxy routing");
+        let last;
         while (Date.now() < deadline) {
           const info = await client.get(this.lifecycleIdentifier);
           if (info.status === "running" /* RUNNING */ && (info.sandboxUrl != null || this.proxy.hasExplicitProxyUrl())) {
@@ -3954,13 +4049,22 @@ var init_sandbox = __esm({
           }
           if (info.status === "terminated" /* TERMINATED */) {
             throw new SandboxError(
-              `Sandbox ${this.lifecycleIdentifier} terminated while refreshing proxy routing`
+              `Sandbox ${this.lifecycleIdentifier} terminated while refreshing proxy routing`,
+              { reason: info.terminationReason, sandboxId: info.sandboxId }
             );
           }
+          last = info;
           await sleep(Math.min(pollInterval * 1e3, Math.max(0, deadline - Date.now())));
         }
+        if (last?.status === "pending" /* PENDING */) {
+          throw new SandboxPending(last.sandboxId, {
+            pendingReason: last.pendingReason,
+            timeout
+          });
+        }
         throw new SandboxError(
-          `Sandbox ${this.lifecycleIdentifier} did not provide refreshed proxy routing within ${timeout}s`
+          `Sandbox ${this.lifecycleIdentifier} did not provide refreshed proxy routing within ${timeout}s`,
+          { sandboxId: this.lifecycleIdentifier }
         );
       }
       /** Live-copy this running sandbox. */
@@ -4455,6 +4559,7 @@ var init_sandbox = __esm({
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
+  DEFAULT_WAIT_POLL_INTERVAL_SEC: () => DEFAULT_WAIT_POLL_INTERVAL_SEC,
   SandboxClient: () => SandboxClient
 });
 function requireReadOnlySnapshotPin(fileSystemId, mountPath, readOnly, snapshotId) {
@@ -4493,6 +4598,12 @@ function gpuRequest(gpu, gpus, gpuModel) {
   }
   return [{ count: gpus, model: gpuModel }];
 }
+function startupFailure(sandboxId, status, options) {
+  return new SandboxError(formatStartupFailureMessage(sandboxId, status, options), {
+    reason: options.terminationReason,
+    sandboxId
+  });
+}
 function resolveRequestTimeoutMs(options) {
   if (options?.requestTimeout != null) {
     return secondsToMillis3(options.requestTimeout);
@@ -4553,7 +4664,7 @@ function validateUserPort(port) {
 function dedupeAndSortPorts(ports) {
   return [...new Set(ports)].sort((a, b) => a - b);
 }
-var GPU_MODELS, SandboxClient, RESERVED_SANDBOX_MANAGEMENT_PORT;
+var DEFAULT_WAIT_POLL_INTERVAL_SEC, GPU_MODELS, SandboxClient, RESERVED_SANDBOX_MANAGEMENT_PORT;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
@@ -4563,9 +4674,11 @@ var init_client = __esm({
     init_native_worker_client();
     init_native_sandbox();
     init_models();
+    init_pending_sandbox();
     init_sandbox();
     init_sdk_timings();
     init_url();
+    DEFAULT_WAIT_POLL_INTERVAL_SEC = 2;
     GPU_MODELS = /* @__PURE__ */ new Set([
       "A100-40GB",
       "A100-80GB",
@@ -4668,9 +4781,155 @@ var init_client = __esm({
         const { json } = await callNative(fn, context);
         return fromSnakeKeys(JSON.parse(json), idField);
       }
-      // --- Sandbox CRUD ---
-      /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
       async create(options) {
+        if (options?.wait === false) {
+          return this.requestPending(options, { ownsSandbox: false });
+        }
+        const body = _SandboxClient.buildCreateRequestBody(options);
+        return this.tracedJson(
+          () => this.native.createSandbox(JSON.stringify(body)),
+          "sandboxId"
+        );
+      }
+      /**
+       * @internal Send the create with `wait: false` and return the pending
+       * handle, bound to this client so `ready()` / `status()` work.
+       */
+      async requestPending(options, binding) {
+        const body = _SandboxClient.buildCreateRequestBody({
+          ...options,
+          wait: false
+        });
+        const record = await this.tracedJson(
+          () => this.native.createSandboxNoWait(JSON.stringify(body))
+        );
+        return new PendingSandbox(record, {
+          client: this,
+          proxyUrl: binding.proxyUrl,
+          requestTimeout: binding.requestTimeout,
+          requestedName: options?.name ?? null,
+          ownsSandbox: binding.ownsSandbox,
+          traceId: record.traceId
+        });
+      }
+      /** @internal Implementation of `PendingSandbox.ready`. */
+      async _ready(sandboxId, binding, options) {
+        const budget = options?.timeout ?? this.requestTimeoutMs / 1e3;
+        const observed = await this.waitForSandbox(
+          sandboxId,
+          budget,
+          options?.pollInterval ?? DEFAULT_WAIT_POLL_INTERVAL_SEC
+        );
+        return this.settleWait(observed, {
+          budget,
+          proxyUrl: binding.proxyUrl,
+          requestTimeout: binding.requestTimeout,
+          cancelOnTimeout: options?.cancelOnTimeout ?? false,
+          requestedName: binding.requestedName,
+          ownsSandbox: binding.ownsSandbox,
+          traceId: binding.traceId
+        });
+      }
+      /**
+       * Poll `get` every `pollInterval` seconds until the sandbox leaves
+       * `pending` or `timeout` elapses, resolving with the last observation.
+       * Never rejects for a timeout and never deletes.
+       */
+      async waitForSandbox(sandboxId, timeout, pollInterval) {
+        if (!Number.isFinite(timeout) || timeout < 0) {
+          throw new SandboxError("timeout must be a non-negative number of seconds");
+        }
+        if (!Number.isFinite(pollInterval) || pollInterval <= 0) {
+          throw new SandboxError("pollInterval must be a positive number of seconds");
+        }
+        return this.tracedJson(
+          () => this.native.waitForSandbox(sandboxId, timeout, pollInterval),
+          "sandboxId",
+          { sandboxId, notFoundKind: "sandbox" }
+        );
+      }
+      /** Turn the last observed sandbox state into a handle or an error. */
+      async settleWait(observed, options) {
+        const { status, sandboxId } = observed;
+        if (isSandboxPending(status)) {
+          if (options.cancelOnTimeout) {
+            try {
+              await this.delete(sandboxId);
+            } catch {
+            }
+            throw new SandboxError(
+              `Sandbox ${sandboxId} did not start within ${options.budget}s`,
+              { reason: observed.pendingReason, sandboxId }
+            );
+          }
+          throw new SandboxPending(sandboxId, {
+            pendingReason: observed.pendingReason,
+            timeout: options.budget
+          });
+        }
+        if (status === "running" /* RUNNING */) {
+          const explicitProxyUrl = options.proxyUrl ?? explicitProxyUrlOverride() ?? void 0;
+          const selectedProxyUrl = await this.native.selectSandboxProxyUrl(
+            sandboxId,
+            observed.sandboxUrl ?? null,
+            observed.ingressEndpoint ?? null,
+            explicitProxyUrl ?? null
+          );
+          const sandbox = this.connect(
+            sandboxId,
+            selectedProxyUrl,
+            observed.routingHint,
+            options.requestTimeout,
+            explicitProxyUrl
+          );
+          if (options.ownsSandbox) sandbox._setOwner(this);
+          else sandbox._setLifecycleClient(this);
+          sandbox.traceId = options.traceId ?? observed.traceId;
+          sandbox._setLifecycleIdentifier(sandboxId);
+          sandbox._setName(observed.name ?? options.requestedName ?? null);
+          return sandbox;
+        }
+        if (status === "terminated" /* TERMINATED */ || status === "failed" /* FAILED */) {
+          throw startupFailure(sandboxId, status, {
+            errorDetails: observed.errorDetails,
+            terminationReason: observed.terminationReason
+          });
+        }
+        throw new SandboxError(
+          `Sandbox ${sandboxId} is ${status}, not running; ` + (status === "suspended" /* SUSPENDED */ ? "resume it to run it again" : "wait for it to settle"),
+          { reason: String(status), sandboxId }
+        );
+      }
+      /**
+       * Routing for a lazy `connect` handle. A sandbox that is still pending is
+       * waited on here rather than failing: readiness is a property of the
+       * sandbox, not of the create call that requested it.
+       */
+      async resolveRoutingInfo(identifier, requestTimeout) {
+        const info = await this.get(identifier);
+        if (info.status !== "pending" /* PENDING */) return info;
+        const budget = requestTimeout ?? this.requestTimeoutMs / 1e3;
+        const observed = await this.waitForSandbox(
+          info.sandboxId,
+          budget,
+          DEFAULT_WAIT_POLL_INTERVAL_SEC
+        );
+        if (isSandboxPending(observed.status)) {
+          throw new SandboxPending(observed.sandboxId, {
+            pendingReason: observed.pendingReason,
+            timeout: budget
+          });
+        }
+        if (observed.status === "terminated" /* TERMINATED */ || observed.status === "failed" /* FAILED */) {
+          throw startupFailure(observed.sandboxId, observed.status, {
+            errorDetails: observed.errorDetails,
+            terminationReason: observed.terminationReason
+          });
+        }
+        return observed;
+      }
+      /** @internal Build the create wire body; shared by `create` and `createAndConnect`. */
+      static buildCreateRequestBody(options) {
         const gpuResources = gpuRequest(
           options?.gpu,
           options?.gpus,
@@ -4700,10 +4959,14 @@ var init_client = __esm({
             deny_out: options?.denyOut ?? []
           };
         }
-        return this.tracedJson(
-          () => this.native.createSandbox(JSON.stringify(body)),
-          "sandboxId"
-        );
+        if (options?.maxPendingSecs != null) {
+          if (!Number.isInteger(options.maxPendingSecs) || options.maxPendingSecs < 0) {
+            throw new SandboxError("maxPendingSecs must be a non-negative integer");
+          }
+          body.max_pending_secs = options.maxPendingSecs;
+        }
+        if (options?.wait === false) body.wait = false;
+        return body;
       }
       /** Get current state and metadata for a sandbox by ID. */
       async get(sandboxId) {
@@ -5151,7 +5414,7 @@ var init_client = __esm({
           organizationId: this.organizationId,
           projectId: this.projectId,
           routingHint,
-          resolveProxyInfo: async (currentIdentifier) => this.get(currentIdentifier),
+          resolveProxyInfo: async (currentIdentifier) => this.resolveRoutingInfo(currentIdentifier, requestTimeout),
           requestTimeout,
           nativeClient: this.native
         });
@@ -5159,123 +5422,145 @@ var init_client = __esm({
       /**
        * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
        *
-       * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
-       * `Sandbox` auto-terminates when `terminate()` is called.
+       * This is `create({ wait: false })` followed by `PendingSandbox.ready()`
+       * polling every `pollInterval` seconds, with `requestTimeout` as the wait
+       * budget, in one call. The returned `Sandbox` auto-terminates when
+       * `terminate()` is called.
+       *
+       * **When the wait runs out the sandbox is not deleted.** A `SandboxPending`
+       * is thrown with the sandbox id, and the sandbox keeps its place in the
+       * queue and starts whenever capacity arrives; `connect` with that id to
+       * collect it, or `delete` it to give up. Pass
+       * `cancelOnTimeout: true` for the previous behaviour (delete, then throw
+       * `SandboxError`), or set `maxPendingSecs` to let the server fail it after
+       * a bound. A pool claim (`poolId`) answers from the server-side wait; a
+       * claim that is still starting is then waited on the same way.
        */
       async createAndConnect(options) {
         const opStart = nowMs();
         const requestTimeout = options?.requestTimeout ?? options?.startupTimeout ?? this.requestTimeoutMs / 1e3;
         const requestClient = this.withRequestTimeout(requestTimeout);
+        const deadline = Date.now() + secondsToMillis3(requestTimeout);
         logSdkTimingEvent("sandbox.create", "start", {
           request_timeout_s: requestTimeout,
           image: options?.image,
           pool_id: options?.poolId
         });
+        const requestedName = options?.poolId != null ? null : options?.name ?? null;
+        let sandboxId;
+        let traceId;
         const createStart = nowMs();
-        const result = options?.poolId != null ? await requestClient.claim(options.poolId, {
-          fileSystems: options.fileSystems
-        }) : await requestClient.create(options);
-        logSdkTiming(
-          "sandbox.create",
-          options?.poolId != null ? "claim_response" : "create_response",
-          createStart,
-          {
+        if (options?.poolId != null) {
+          const result = await requestClient.claim(options.poolId, {
+            fileSystems: options.fileSystems
+          });
+          logSdkTiming("sandbox.create", "claim_response", createStart, {
             sandbox_id: result.sandboxId,
             status: result.status,
             server_trace_id: result.traceId
-          }
-        );
-        const requestedName = options?.poolId != null ? null : options?.name ?? null;
-        const finishConnect = async (sandboxId, routingHint, name, ingressEndpoint, sandboxUrl) => {
-          const explicitProxyUrl = options?.proxyUrl ?? explicitProxyUrlOverride() ?? void 0;
-          const selectedProxyUrl = await this.native.selectSandboxProxyUrl(
-            sandboxId,
-            sandboxUrl ?? null,
-            ingressEndpoint ?? null,
-            explicitProxyUrl ?? null
-          );
-          const sandbox = requestClient.connect(
-            sandboxId,
-            selectedProxyUrl,
-            routingHint,
-            requestTimeout,
-            explicitProxyUrl
-          );
-          sandbox._setOwner(requestClient);
-          sandbox.traceId = result.traceId;
-          sandbox._setLifecycleIdentifier(sandboxId);
-          sandbox._setName(name ?? requestedName);
-          logSdkTiming("sandbox.create", "complete", opStart, {
-            sandbox_id: sandboxId,
-            status: "running" /* RUNNING */,
-            server_trace_id: result.traceId,
-            routing_hint: routingHint,
-            ingress_endpoint: ingressEndpoint,
-            sandbox_url: sandboxUrl
           });
-          return sandbox;
-        };
-        if (result.status === "running" /* RUNNING */) {
-          return finishConnect(
-            result.sandboxId,
-            result.routingHint,
-            result.name,
-            result.ingressEndpoint,
-            result.sandboxUrl
-          );
-        }
-        if (result.status === "suspended" /* SUSPENDED */ || result.status === "terminated" /* TERMINATED */ || result.status === "failed" /* FAILED */) {
-          throw new SandboxError(
-            formatStartupFailureMessage(result.sandboxId, result.status, {
+          if (result.status === "running" /* RUNNING */) {
+            const explicitProxyUrl = options?.proxyUrl ?? explicitProxyUrlOverride() ?? void 0;
+            const selectedProxyUrl = await this.native.selectSandboxProxyUrl(
+              result.sandboxId,
+              result.sandboxUrl ?? null,
+              result.ingressEndpoint ?? null,
+              explicitProxyUrl ?? null
+            );
+            const sandbox2 = requestClient.connect(
+              result.sandboxId,
+              selectedProxyUrl,
+              result.routingHint,
+              requestTimeout,
+              explicitProxyUrl
+            );
+            sandbox2._setOwner(requestClient);
+            sandbox2.traceId = result.traceId;
+            sandbox2._setLifecycleIdentifier(result.sandboxId);
+            sandbox2._setName(result.name ?? requestedName);
+            logSdkTiming("sandbox.create", "complete", opStart, {
+              sandbox_id: result.sandboxId,
+              status: "running" /* RUNNING */,
+              server_trace_id: result.traceId
+            });
+            return sandbox2;
+          }
+          if (result.status === "suspended" /* SUSPENDED */ || result.status === "terminated" /* TERMINATED */ || result.status === "failed" /* FAILED */) {
+            throw startupFailure(result.sandboxId, result.status, {
               errorDetails: result.errorDetails,
               terminationReason: result.terminationReason ?? result.reason
-            })
-          );
-        }
-        if (result.status === "timeout" /* TIMEOUT */) {
-          try {
-            await requestClient.delete(result.sandboxId);
-          } catch {
+            });
           }
-          throw new SandboxError(
-            `Sandbox ${result.sandboxId} did not start within ${requestTimeout}s`
-          );
-        }
-        const deadline = Date.now() + secondsToMillis3(requestTimeout);
-        while (Date.now() < deadline) {
-          const pollStart = nowMs();
-          const info = await requestClient.get(result.sandboxId);
-          logSdkTiming("sandbox.create", "poll_response", pollStart, {
-            sandbox_id: result.sandboxId,
-            status: info.status,
-            server_trace_id: info.traceId
+          sandboxId = result.sandboxId;
+          traceId = result.traceId;
+        } else {
+          const pending = await requestClient.requestPending(options, {
+            ownsSandbox: true
           });
-          if (info.status === "running" /* RUNNING */) {
-            return finishConnect(
-              info.sandboxId,
-              info.routingHint,
-              info.name,
-              info.ingressEndpoint,
-              info.sandboxUrl
+          logSdkTiming("sandbox.create", "create_response", createStart, {
+            sandbox_id: pending.sandboxId,
+            status: pending.state,
+            server_trace_id: pending.traceId
+          });
+          sandboxId = pending.sandboxId;
+          traceId = pending.traceId;
+          if (pending.state === "running" /* RUNNING */) {
+            const explicitProxyUrl = options?.proxyUrl ?? explicitProxyUrlOverride() ?? void 0;
+            const selectedProxyUrl = await this.native.selectSandboxProxyUrl(
+              sandboxId,
+              pending.sandboxUrl ?? null,
+              pending.ingressEndpoint ?? null,
+              explicitProxyUrl ?? null
             );
-          }
-          if (info.status === "suspended" /* SUSPENDED */ || info.status === "terminated" /* TERMINATED */) {
-            throw new SandboxError(
-              formatStartupFailureMessage(result.sandboxId, info.status, {
-                errorDetails: info.errorDetails,
-                terminationReason: info.terminationReason
-              })
+            const sandbox2 = requestClient.connect(
+              sandboxId,
+              selectedProxyUrl,
+              pending.routingHint,
+              requestTimeout,
+              explicitProxyUrl
             );
+            sandbox2._setOwner(requestClient);
+            sandbox2.traceId = traceId;
+            sandbox2._setLifecycleIdentifier(sandboxId);
+            sandbox2._setName(pending.name ?? requestedName);
+            logSdkTiming("sandbox.create", "complete", opStart, {
+              sandbox_id: sandboxId,
+              status: "running" /* RUNNING */,
+              server_trace_id: traceId
+            });
+            return sandbox2;
+          }
+          if (pending.state === "terminated" /* TERMINATED */ || pending.state === "failed" /* FAILED */) {
+            throw startupFailure(sandboxId, pending.state, {
+              errorDetails: pending.errorDetails,
+              terminationReason: pending.terminationReason ?? pending.reason
+            });
           }
-          await sleep2(500);
-        }
-        try {
-          await requestClient.delete(result.sandboxId);
-        } catch {
         }
-        throw new SandboxError(
-          `Sandbox ${result.sandboxId} did not start within ${requestTimeout}s`
+        const remaining = Math.max(0, (deadline - Date.now()) / 1e3);
+        const observed = await requestClient.waitForSandbox(
+          sandboxId,
+          remaining,
+          options?.pollInterval ?? DEFAULT_WAIT_POLL_INTERVAL_SEC
         );
+        const sandbox = await requestClient.settleWait(observed, {
+          budget: requestTimeout,
+          proxyUrl: options?.proxyUrl,
+          requestTimeout,
+          cancelOnTimeout: options?.cancelOnTimeout ?? false,
+          requestedName,
+          ownsSandbox: true,
+          traceId
+        });
+        logSdkTiming("sandbox.create", "complete", opStart, {
+          sandbox_id: sandboxId,
+          status: "running" /* RUNNING */,
+          server_trace_id: traceId,
+          routing_hint: observed.routingHint,
+          ingress_endpoint: observed.ingressEndpoint,
+          sandbox_url: observed.sandboxUrl
+        });
+        return sandbox;
       }
     };
     RESERVED_SANDBOX_MANAGEMENT_PORT = 9501;
@@ -6654,6 +6939,7 @@ __export(index_exports, {
   ImageBuildOperationType: () => ImageBuildOperationType,
   MountError: () => MountError,
   OutputMode: () => OutputMode,
+  PendingSandbox: () => PendingSandbox,
   PoolInUseError: () => PoolInUseError,
   PoolNotFoundError: () => PoolNotFoundError,
   ProcessStatus: () => ProcessStatus,
@@ -6672,9 +6958,13 @@ __export(index_exports, {
   SandboxError: () => SandboxError,
   SandboxException: () => SandboxException,
   SandboxNotFoundError: () => SandboxNotFoundError,
+  SandboxPending: () => SandboxPending,
+  SandboxPendingReason: () => SandboxPendingReason,
   SandboxStatus: () => SandboxStatus,
   SnapshotStatus: () => SnapshotStatus,
   StdinMode: () => StdinMode,
+  TERMINATION_REASON_CANCELLED: () => TERMINATION_REASON_CANCELLED,
+  TERMINATION_REASON_NO_CAPACITY: () => TERMINATION_REASON_NO_CAPACITY,
   TcpTunnel: () => TcpTunnel,
   createFileSystem: () => createFileSystem,
   createSandboxImage: () => createSandboxImage,
@@ -6683,6 +6973,7 @@ __export(index_exports, {
   dockerfileContent: () => dockerfileContent,
   findSandboxImageByName: () => findSandboxImageByName,
   importSandboxImage: () => importSandboxImage,
+  isSandboxPending: () => isSandboxPending,
   listFileSystems: () => listFileSystems,
   listSandboxImages: () => listSandboxImages,
   registerApplication: () => registerApplication,
@@ -6698,6 +6989,7 @@ module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
 init_client();
 init_sandbox();
+init_pending_sandbox();
 init_sandbox();
 init_desktop();
 init_tunnel();
@@ -9714,6 +10006,7 @@ init_models();
   ImageBuildOperationType,
   MountError,
   OutputMode,
+  PendingSandbox,
   PoolInUseError,
   PoolNotFoundError,
   ProcessStatus,
@@ -9732,9 +10025,13 @@ init_models();
   SandboxError,
   SandboxException,
   SandboxNotFoundError,
+  SandboxPending,
+  SandboxPendingReason,
   SandboxStatus,
   SnapshotStatus,
   StdinMode,
+  TERMINATION_REASON_CANCELLED,
+  TERMINATION_REASON_NO_CAPACITY,
   TcpTunnel,
   createFileSystem,
   createSandboxImage,
@@ -9743,6 +10040,7 @@ init_models();
   dockerfileContent,
   findSandboxImageByName,
   importSandboxImage,
+  isSandboxPending,
   listFileSystems,
   listSandboxImages,
   registerApplication,