tensorlake 0.4.50 → 0.5.0

package/dist/index.cjs

@@ -31,10 +31,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/defaults.ts
-var API_URL, API_KEY, NAMESPACE, SANDBOX_PROXY_URL, DEFAULT_HTTP_TIMEOUT_MS, MAX_RETRIES, RETRY_BACKOFF_MS, RETRYABLE_STATUS_CODES;
+var SDK_VERSION, API_URL, API_KEY, NAMESPACE, SANDBOX_PROXY_URL, DEFAULT_HTTP_TIMEOUT_MS, MAX_RETRIES, RETRY_BACKOFF_MS, RETRYABLE_STATUS_CODES;
 var init_defaults = __esm({
   "src/defaults.ts"() {
     "use strict";
+    SDK_VERSION = "0.4.49";
     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";
@@ -132,6 +133,12 @@ var init_errors = __esm({
 });
 
 // src/http.ts
+function withTraceId(value, traceId) {
+  if (value == null) {
+    return { traceId };
+  }
+  return Object.assign(value, { traceId });
+}
 function hasHeader(headers, name) {
   const lowered = name.toLowerCase();
   return Object.keys(headers).some((key) => key.toLowerCase() === lowered);
@@ -201,7 +208,7 @@ var init_http = __esm({
         allowH2: true
       })
     );
-    HttpClient = class {
+    HttpClient = class _HttpClient {
       baseUrl;
       headers;
       maxRetries;
@@ -214,7 +221,9 @@ var init_http = __esm({
         this.maxRetries = options.maxRetries ?? MAX_RETRIES;
         this.retryBackoffMs = options.retryBackoffMs ?? RETRY_BACKOFF_MS;
         this.timeoutMs = options.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
-        this.headers = {};
+        this.headers = {
+          "User-Agent": `tensorlake-typescript-sdk/${SDK_VERSION}`
+        };
         if (options.apiKey) {
           this.headers["Authorization"] = `Bearer ${options.apiKey}`;
         }
@@ -243,8 +252,8 @@ var init_http = __esm({
           signal: options?.signal
         });
         const text = await response.text();
-        if (!text) return void 0;
-        return JSON.parse(text);
+        const data = text ? JSON.parse(text) : void 0;
+        return withTraceId(data, response.traceId);
       }
       /** Make a request returning raw bytes. */
       async requestBytes(method, path2, options) {
@@ -258,7 +267,7 @@ var init_http = __esm({
           signal: options?.signal
         });
         const buffer = await response.arrayBuffer();
-        return new Uint8Array(buffer);
+        return withTraceId(new Uint8Array(buffer), response.traceId);
       }
       /** Make a request and return the response body as an SSE stream. */
       async requestStream(method, path2, options) {
@@ -273,7 +282,7 @@ var init_http = __esm({
             "No response body for SSE stream"
           );
         }
-        return response.body;
+        return withTraceId(response.body, response.traceId);
       }
       /** Make a request and return the raw Response. */
       async requestResponse(method, path2, options) {
@@ -286,7 +295,7 @@ var init_http = __esm({
           headers["Content-Type"] = "application/json";
         }
         const body = hasJsonBody ? JSON.stringify(options?.json) : normalizeRequestBody(options?.body);
-        return this.doFetch(
+        const { response, traceId } = await this.doFetch(
           method,
           path2,
           body,
@@ -294,9 +303,18 @@ var init_http = __esm({
           options?.signal,
           options?.allowHttpErrors ?? false
         );
+        return withTraceId(response, traceId);
+      }
+      static makeTraceparent() {
+        const randomHex = (bytes) => Array.from(crypto.getRandomValues(new Uint8Array(bytes))).map((b) => b.toString(16).padStart(2, "0")).join("");
+        const traceId = randomHex(16);
+        const spanId = randomHex(8);
+        return { traceparent: `00-${traceId}-${spanId}-01`, traceId };
       }
       async doFetch(method, path2, body, headers, signal, allowHttpErrors = false) {
         const url = `${this.baseUrl}${path2}`;
+        const { traceparent, traceId } = _HttpClient.makeTraceparent();
+        headers["traceparent"] = traceparent;
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
           if (attempt > 0) {
@@ -317,7 +335,7 @@ var init_http = __esm({
               signal: combinedSignal
             });
             clearTimeout(timeoutId);
-            if (response.ok) return response;
+            if (response.ok) return { response, traceId };
             if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < this.maxRetries) {
               lastError = new RemoteAPIError(
                 response.status,
@@ -326,7 +344,7 @@ var init_http = __esm({
               continue;
             }
             if (allowHttpErrors) {
-              return response;
+              return { response, traceId };
             }
             const errorBody = await response.text().catch(() => "");
             throwMappedError(response.status, errorBody, path2);
@@ -396,20 +414,20 @@ var SandboxStatus, SnapshotStatus, ProcessStatus, StdinMode, OutputMode, Contain
 var init_models = __esm({
   "src/models.ts"() {
     "use strict";
-    SandboxStatus = /* @__PURE__ */ ((SandboxStatus2) => {
-      SandboxStatus2["PENDING"] = "pending";
-      SandboxStatus2["RUNNING"] = "running";
-      SandboxStatus2["SNAPSHOTTING"] = "snapshotting";
-      SandboxStatus2["SUSPENDING"] = "suspending";
-      SandboxStatus2["SUSPENDED"] = "suspended";
-      SandboxStatus2["TERMINATED"] = "terminated";
-      return SandboxStatus2;
+    SandboxStatus = /* @__PURE__ */ ((SandboxStatus3) => {
+      SandboxStatus3["PENDING"] = "pending";
+      SandboxStatus3["RUNNING"] = "running";
+      SandboxStatus3["SNAPSHOTTING"] = "snapshotting";
+      SandboxStatus3["SUSPENDING"] = "suspending";
+      SandboxStatus3["SUSPENDED"] = "suspended";
+      SandboxStatus3["TERMINATED"] = "terminated";
+      return SandboxStatus3;
     })(SandboxStatus || {});
-    SnapshotStatus = /* @__PURE__ */ ((SnapshotStatus2) => {
-      SnapshotStatus2["IN_PROGRESS"] = "in_progress";
-      SnapshotStatus2["COMPLETED"] = "completed";
-      SnapshotStatus2["FAILED"] = "failed";
-      return SnapshotStatus2;
+    SnapshotStatus = /* @__PURE__ */ ((SnapshotStatus3) => {
+      SnapshotStatus3["IN_PROGRESS"] = "in_progress";
+      SnapshotStatus3["COMPLETED"] = "completed";
+      SnapshotStatus3["FAILED"] = "failed";
+      return SnapshotStatus3;
     })(SnapshotStatus || {});
     ProcessStatus = /* @__PURE__ */ ((ProcessStatus2) => {
       ProcessStatus2["RUNNING"] = "running";
@@ -3158,6 +3176,7 @@ var init_sandbox = __esm({
     };
     Sandbox = class {
       sandboxId;
+      traceId = null;
       http;
       baseUrl;
       wsHeaders;
@@ -3195,9 +3214,126 @@ 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`.
+       */
+      static async create(options) {
+        const { SandboxClient: SandboxClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+        const client = new SandboxClient2(
+          options,
+          /* _internal */
+          true
+        );
+        const sandbox = await client.createAndConnect(options);
+        sandbox.lifecycleClient = client;
+        return sandbox;
+      }
+      /**
+       * Attach to an existing sandbox and return a connected handle.
+       *
+       * Verifies the sandbox exists via a server GET call, then returns a handle
+       * in whatever state the sandbox is in. Does **not** auto-resume a suspended
+       * sandbox — call `sandbox.resume()` explicitly.
+       */
+      static async connect(options) {
+        const { SandboxClient: SandboxClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+        const client = new SandboxClient2(
+          options,
+          /* _internal */
+          true
+        );
+        await client.get(options.sandboxId);
+        const sandbox = client.connect(options.sandboxId, options.proxyUrl, options.routingHint);
+        sandbox.lifecycleClient = client;
+        return sandbox;
+      }
+      // --- Static snapshot management ---
+      /** Get information about a snapshot by ID. No sandbox handle needed. */
+      static async getSnapshot(snapshotId, options) {
+        const { SandboxClient: SandboxClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+        const client = new SandboxClient2(
+          options,
+          /* _internal */
+          true
+        );
+        return client.getSnapshot(snapshotId);
+      }
+      /** Delete a snapshot by ID. No sandbox handle needed. */
+      static async deleteSnapshot(snapshotId, options) {
+        const { SandboxClient: SandboxClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+        const client = new SandboxClient2(
+          options,
+          /* _internal */
+          true
+        );
+        await client.deleteSnapshot(snapshotId);
+      }
+      // --- Instance lifecycle methods ---
+      requireLifecycleClient(operation) {
+        if (!this.lifecycleClient) {
+          throw new SandboxError(
+            `Cannot ${operation}: no lifecycle client available. Use Sandbox.create() or Sandbox.connect() to get a lifecycle-aware handle.`
+          );
+        }
+        return this.lifecycleClient;
+      }
+      /**
+       * Suspend this sandbox.
+       *
+       * By default blocks until the sandbox is fully `Suspended`. Pass
+       * `{ wait: false }` for fire-and-return.
+       */
+      async suspend(options) {
+        const client = this.requireLifecycleClient("suspend");
+        await client.suspend(this.sandboxId, options);
+      }
+      /**
+       * Resume this sandbox.
+       *
+       * By default blocks until the sandbox is `Running` and routable. Pass
+       * `{ wait: false }` for fire-and-return.
+       */
+      async resume(options) {
+        const client = this.requireLifecycleClient("resume");
+        await client.resume(this.sandboxId, options);
+      }
+      /**
+       * Create a snapshot of this sandbox's filesystem and wait for it to
+       * be committed.
+       *
+       * By default blocks until the snapshot artifact is ready and returns
+       * the completed `SnapshotInfo`. Pass `{ wait: false }` to fire-and-return
+       * (returns `undefined`).
+       */
+      async checkpoint(options) {
+        const client = this.requireLifecycleClient("checkpoint");
+        if (options?.wait === false) {
+          await client.snapshot(this.sandboxId, { contentMode: options.contentMode });
+          return void 0;
+        }
+        return client.snapshotAndWait(this.sandboxId, {
+          timeout: options?.timeout,
+          pollInterval: options?.pollInterval,
+          contentMode: options?.contentMode
+        });
+      }
+      /**
+       * List snapshots taken from this sandbox.
+       */
+      async listSnapshots() {
+        const client = this.requireLifecycleClient("listSnapshots");
+        const all = await client.listSnapshots();
+        return all.filter((s) => s.sandboxId === this.sandboxId);
+      }
+      /** Close the HTTP client. The sandbox keeps running. */
       close() {
         this.http.close();
       }
+      /** Terminate the sandbox and release all resources. */
       async terminate() {
         const client = this.lifecycleClient;
         this.ownsSandbox = false;
@@ -3250,6 +3386,14 @@ var init_sandbox = __esm({
         };
       }
       // --- Process management ---
+      /**
+       * Start a process in the sandbox without waiting for it to exit.
+       *
+       * Returns a `ProcessInfo` with the assigned `pid`. Use `getProcess()` to
+       * poll status, or `followStdout()` / `followOutput()` to stream output
+       * until the process exits. Use `run()` instead to block until completion
+       * and get combined output in one call.
+       */
       async startProcess(command, options) {
         const payload = { command };
         if (options?.args != null) payload.args = options.args;
@@ -3271,6 +3415,7 @@ var init_sandbox = __esm({
         );
         return fromSnakeKeys(raw);
       }
+      /** List all processes (running and exited) tracked by the sandbox daemon. */
       async listProcesses() {
         const raw = await this.http.requestJson(
           "GET",
@@ -3278,6 +3423,7 @@ var init_sandbox = __esm({
         );
         return (raw.processes ?? []).map((p) => fromSnakeKeys(p));
       }
+      /** Get current status and metadata for a process by PID. */
       async getProcess(pid) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3285,9 +3431,11 @@ var init_sandbox = __esm({
         );
         return fromSnakeKeys(raw);
       }
+      /** Send SIGKILL to a process. */
       async killProcess(pid) {
         await this.http.requestJson("DELETE", `/api/v1/processes/${pid}`);
       }
+      /** Send an arbitrary signal to a process (e.g. `15` for SIGTERM, `9` for SIGKILL). */
       async sendSignal(pid, signal) {
         const raw = await this.http.requestJson(
           "POST",
@@ -3297,15 +3445,18 @@ var init_sandbox = __esm({
         return fromSnakeKeys(raw);
       }
       // --- Process I/O ---
+      /** Write bytes to a process's stdin. The process must have been started with `stdinMode: StdinMode.PIPE`. */
       async writeStdin(pid, data) {
         await this.http.requestBytes("POST", `/api/v1/processes/${pid}/stdin`, {
           body: data,
           contentType: "application/octet-stream"
         });
       }
+      /** Close a process's stdin pipe, signalling EOF to the process. */
       async closeStdin(pid) {
         await this.http.requestJson("POST", `/api/v1/processes/${pid}/stdin/close`);
       }
+      /** Return all captured stdout lines produced so far by a process. */
       async getStdout(pid) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3313,6 +3464,7 @@ var init_sandbox = __esm({
         );
         return fromSnakeKeys(raw);
       }
+      /** Return all captured stderr lines produced so far by a process. */
       async getStderr(pid) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3320,6 +3472,7 @@ var init_sandbox = __esm({
         );
         return fromSnakeKeys(raw);
       }
+      /** Return all captured stdout+stderr lines produced so far by a process. */
       async getOutput(pid) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3328,6 +3481,7 @@ var init_sandbox = __esm({
         return fromSnakeKeys(raw);
       }
       // --- Streaming (SSE) ---
+      /** Stream stdout events from a process until it exits. Yields one `OutputEvent` per line. */
       async *followStdout(pid, options) {
         const stream = await this.http.requestStream(
           "GET",
@@ -3341,6 +3495,7 @@ var init_sandbox = __esm({
           yield fromSnakeKeys(raw);
         }
       }
+      /** Stream stderr events from a process until it exits. Yields one `OutputEvent` per line. */
       async *followStderr(pid, options) {
         const stream = await this.http.requestStream(
           "GET",
@@ -3354,6 +3509,7 @@ var init_sandbox = __esm({
           yield fromSnakeKeys(raw);
         }
       }
+      /** Stream combined stdout+stderr events from a process until it exits. Yields one `OutputEvent` per line. */
       async *followOutput(pid, options) {
         const stream = await this.http.requestStream(
           "GET",
@@ -3368,12 +3524,14 @@ var init_sandbox = __esm({
         }
       }
       // --- File operations ---
+      /** Read a file from the sandbox and return its raw bytes. */
       async readFile(path2) {
         return this.http.requestBytes(
           "GET",
           `/api/v1/files?path=${encodeURIComponent(path2)}`
         );
       }
+      /** Write raw bytes to a file in the sandbox, creating it if it does not exist. */
       async writeFile(path2, content) {
         await this.http.requestBytes(
           "PUT",
@@ -3381,12 +3539,14 @@ var init_sandbox = __esm({
           { body: content, contentType: "application/octet-stream" }
         );
       }
+      /** Delete a file from the sandbox. */
       async deleteFile(path2) {
         await this.http.requestJson(
           "DELETE",
           `/api/v1/files?path=${encodeURIComponent(path2)}`
         );
       }
+      /** List the contents of a directory in the sandbox. */
       async listDirectory(path2) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3395,6 +3555,7 @@ var init_sandbox = __esm({
         return fromSnakeKeys(raw);
       }
       // --- PTY ---
+      /** Create an interactive PTY session. Returns a `sessionId` and `token` for WebSocket connection via `connectPty()`. */
       async createPtySession(options) {
         const payload = {
           command: options.command,
@@ -3411,6 +3572,7 @@ var init_sandbox = __esm({
         );
         return fromSnakeKeys(raw);
       }
+      /** Create a PTY session and connect to it immediately. Cleans up the session if the WebSocket connection fails. */
       async createPty(options) {
         const { onData, onExit, ...createOptions } = options;
         const session = await this.createPtySession(createOptions);
@@ -3424,6 +3586,7 @@ var init_sandbox = __esm({
           throw error;
         }
       }
+      /** Attach to an existing PTY session by ID and token and return a connected `Pty` handle. */
       async connectPty(sessionId, token, options) {
         const wsUrl = new URL(this.ptyWsUrl(sessionId, token));
         const authToken = wsUrl.searchParams.get("token") ?? token;
@@ -3448,6 +3611,7 @@ var init_sandbox = __esm({
         await pty.connect();
         return pty;
       }
+      /** Open a TCP tunnel to a port inside the sandbox and return the local listener. */
       async createTunnel(remotePort, options) {
         return TcpTunnel.listen({
           baseUrl: this.baseUrl,
@@ -3458,6 +3622,7 @@ var init_sandbox = __esm({
           connectTimeout: options?.connectTimeout
         });
       }
+      /** Connect to a sandbox VNC session for programmatic desktop control. */
       async connectDesktop(options) {
         return Desktop.connect({
           baseUrl: this.baseUrl,
@@ -3480,6 +3645,7 @@ var init_sandbox = __esm({
         return `${wsBase}/api/v1/pty/${sessionId}/ws?token=${token}`;
       }
       // --- Health ---
+      /** Check the sandbox daemon health. */
       async health() {
         const raw = await this.http.requestJson(
           "GET",
@@ -3487,6 +3653,7 @@ var init_sandbox = __esm({
         );
         return fromSnakeKeys(raw);
       }
+      /** Get sandbox daemon info (version, uptime, process counts). */
       async info() {
         const raw = await this.http.requestJson(
           "GET",
@@ -3499,6 +3666,10 @@ var init_sandbox = __esm({
 });
 
 // src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  SandboxClient: () => SandboxClient
+});
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -3535,7 +3706,13 @@ var init_client = __esm({
       projectId;
       namespace;
       local;
-      constructor(options) {
+      /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
+      constructor(options, _internal = false) {
+        if (!_internal) {
+          console.warn(
+            "[tensorlake] SandboxClient is deprecated; use Sandbox.create() / Sandbox.connect() instead."
+          );
+        }
         this.apiUrl = options?.apiUrl ?? API_URL;
         this.apiKey = options?.apiKey ?? API_KEY;
         this.organizationId = options?.organizationId;
@@ -3575,6 +3752,7 @@ var init_client = __esm({
         return lifecyclePath(subpath, this.local, this.namespace);
       }
       // --- 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) {
         const body = {
           resources: {
@@ -3601,8 +3779,10 @@ var init_client = __esm({
           this.path("sandboxes"),
           { body }
         );
-        return fromSnakeKeys(raw, "sandboxId");
+        const result = fromSnakeKeys(raw, "sandboxId");
+        return Object.assign(result, { traceId: raw.traceId });
       }
+      /** Get current state and metadata for a sandbox by ID. */
       async get(sandboxId) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3610,6 +3790,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "sandboxId");
       }
+      /** List all sandboxes in the namespace. */
       async list() {
         const raw = await this.http.requestJson(
           "GET",
@@ -3619,6 +3800,7 @@ var init_client = __esm({
           (s) => fromSnakeKeys(s, "sandboxId")
         );
       }
+      /** Update sandbox properties such as name, exposed ports, and proxy auth settings. */
       async update(sandboxId, options) {
         const body = {};
         if (options.name != null) body.name = options.name;
@@ -3638,6 +3820,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "sandboxId");
       }
+      /** Get the current proxy port settings for a sandbox. */
       async getPortAccess(sandboxId) {
         const info = await this.get(sandboxId);
         return {
@@ -3646,6 +3829,7 @@ var init_client = __esm({
           sandboxUrl: info.sandboxUrl
         };
       }
+      /** Add one or more user ports to the sandbox proxy allowlist. */
       async exposePorts(sandboxId, ports, options) {
         const requestedPorts = normalizeUserPorts(ports);
         const current = await this.getPortAccess(sandboxId);
@@ -3658,6 +3842,7 @@ var init_client = __esm({
           exposedPorts: desiredPorts
         });
       }
+      /** Remove one or more user ports from the sandbox proxy allowlist. */
       async unexposePorts(sandboxId, ports) {
         const requestedPorts = normalizeUserPorts(ports);
         const current = await this.getPortAccess(sandboxId);
@@ -3668,32 +3853,98 @@ var init_client = __esm({
           exposedPorts: desiredPorts
         });
       }
+      /** Terminate and delete a sandbox. */
       async delete(sandboxId) {
         await this.http.requestJson(
           "DELETE",
           this.path(`sandboxes/${sandboxId}`)
         );
       }
-      async suspend(sandboxId) {
+      /**
+       * Suspend a named sandbox, preserving its state for later resume.
+       *
+       * Only sandboxes created with a `name` can be suspended; ephemeral sandboxes
+       * cannot. By default blocks until the sandbox is fully `Suspended`. Pass
+       * `{ wait: false }` to return immediately after the request is sent
+       * (fire-and-return); the server processes the suspend asynchronously.
+       *
+       * @param sandboxId - ID or name of the sandbox.
+       * @param options.wait - If `true` (default), poll until `Suspended`. Pass `false` to fire-and-return.
+       * @param options.timeout - Max seconds to wait when `wait=true` (default 300).
+       * @param options.pollInterval - Seconds between status polls when `wait=true` (default 1).
+       * @throws {SandboxError} If `wait=true` and the sandbox does not reach `Suspended` within `timeout`.
+       */
+      async suspend(sandboxId, options) {
         await this.http.requestResponse(
           "POST",
           this.path(`sandboxes/${sandboxId}/suspend`)
         );
+        if (options?.wait === false) return;
+        const timeout = options?.timeout ?? 300;
+        const pollInterval = options?.pollInterval ?? 1;
+        const deadline = Date.now() + timeout * 1e3;
+        while (Date.now() < deadline) {
+          const info = await this.get(sandboxId);
+          if (info.status === "suspended" /* SUSPENDED */) return;
+          if (info.status === "terminated" /* TERMINATED */) {
+            throw new SandboxError(`Sandbox ${sandboxId} terminated while waiting for suspend`);
+          }
+          await sleep2(pollInterval * 1e3);
+        }
+        throw new SandboxError(`Sandbox ${sandboxId} did not suspend within ${timeout}s`);
       }
-      async resume(sandboxId) {
+      /**
+       * Resume a suspended sandbox and bring it back to `Running`.
+       *
+       * By default blocks until the sandbox is `Running` and routable. Pass
+       * `{ wait: false }` to return immediately after the request is sent
+       * (fire-and-return); the server processes the resume asynchronously.
+       *
+       * @param sandboxId - ID or name of the sandbox.
+       * @param options.wait - If `true` (default), poll until `Running`. Pass `false` to fire-and-return.
+       * @param options.timeout - Max seconds to wait when `wait=true` (default 300).
+       * @param options.pollInterval - Seconds between status polls when `wait=true` (default 1).
+       * @throws {SandboxError} If `wait=true` and the sandbox does not reach `Running` within `timeout`.
+       */
+      async resume(sandboxId, options) {
         await this.http.requestResponse(
           "POST",
           this.path(`sandboxes/${sandboxId}/resume`)
         );
+        if (options?.wait === false) return;
+        const timeout = options?.timeout ?? 300;
+        const pollInterval = options?.pollInterval ?? 1;
+        const deadline = Date.now() + timeout * 1e3;
+        while (Date.now() < deadline) {
+          const info = await this.get(sandboxId);
+          if (info.status === "running" /* RUNNING */) return;
+          if (info.status === "terminated" /* TERMINATED */) {
+            throw new SandboxError(`Sandbox ${sandboxId} terminated while waiting for resume`);
+          }
+          await sleep2(pollInterval * 1e3);
+        }
+        throw new SandboxError(`Sandbox ${sandboxId} did not resume within ${timeout}s`);
       }
+      /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
       async claim(poolId) {
         const raw = await this.http.requestJson(
           "POST",
           this.path(`sandbox-pools/${poolId}/sandboxes`)
         );
-        return fromSnakeKeys(raw, "sandboxId");
+        const result = fromSnakeKeys(raw, "sandboxId");
+        return Object.assign(result, { traceId: raw.traceId });
       }
       // --- Snapshots ---
+      /**
+       * Request a snapshot of a running sandbox's filesystem.
+       *
+       * This call **returns immediately** with a `snapshotId` and `in_progress`
+       * status — the snapshot is created asynchronously. Poll `getSnapshot()` until
+       * `completed` or `failed`, or use `snapshotAndWait()` to block automatically.
+       *
+       * @param options.contentMode - `"filesystem_only"` for cold-boot snapshots (e.g. image builds).
+       *   Omit to use the server default (full VM snapshot).
+       */
       async snapshot(sandboxId, options) {
         const requestOptions = options?.contentMode != null ? { body: { snapshot_content_mode: options.contentMode } } : void 0;
         const raw = await this.http.requestJson(
@@ -3703,6 +3954,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "snapshotId");
       }
+      /** Get current status and metadata for a snapshot by ID. */
       async getSnapshot(snapshotId) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3710,6 +3962,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "snapshotId");
       }
+      /** List all snapshots in the namespace. */
       async listSnapshots() {
         const raw = await this.http.requestJson(
           "GET",
@@ -3719,12 +3972,26 @@ var init_client = __esm({
           (s) => fromSnakeKeys(s, "snapshotId")
         );
       }
+      /** Delete a snapshot by ID. */
       async deleteSnapshot(snapshotId) {
         await this.http.requestJson(
           "DELETE",
           this.path(`snapshots/${snapshotId}`)
         );
       }
+      /**
+       * Create a snapshot and block until it is committed.
+       *
+       * Combines `snapshot()` with polling `getSnapshot()` until `completed`.
+       * Prefer `sandbox.checkpoint()` on a `Sandbox` handle for the same behavior
+       * without managing the client separately.
+       *
+       * @param sandboxId - ID of the running sandbox to snapshot.
+       * @param options.timeout - Max seconds to wait (default 300).
+       * @param options.pollInterval - Seconds between status polls (default 1).
+       * @param options.contentMode - Content mode passed through to `snapshot()`.
+       * @throws {SandboxError} If the snapshot fails or `timeout` elapses.
+       */
       async snapshotAndWait(sandboxId, options) {
         const timeout = options?.timeout ?? 300;
         const pollInterval = options?.pollInterval ?? 1;
@@ -3747,6 +4014,7 @@ var init_client = __esm({
         );
       }
       // --- Pools ---
+      /** Create a new sandbox pool with warm pre-booted containers. */
       async createPool(options) {
         const body = {
           image: options.image,
@@ -3768,6 +4036,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "poolId");
       }
+      /** Get current state and metadata for a sandbox pool by ID. */
       async getPool(poolId) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3775,6 +4044,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "poolId");
       }
+      /** List all sandbox pools in the namespace. */
       async listPools() {
         const raw = await this.http.requestJson(
           "GET",
@@ -3784,6 +4054,7 @@ var init_client = __esm({
           (p) => fromSnakeKeys(p, "poolId")
         );
       }
+      /** Replace the configuration of an existing sandbox pool. */
       async updatePool(poolId, options) {
         const body = {
           image: options.image,
@@ -3805,6 +4076,7 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "poolId");
       }
+      /** Delete a sandbox pool. Fails if the pool has active containers. */
       async deletePool(poolId) {
         await this.http.requestJson(
           "DELETE",
@@ -3812,6 +4084,7 @@ var init_client = __esm({
         );
       }
       // --- Connect ---
+      /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
       connect(identifier, proxyUrl, routingHint) {
         const resolvedProxy = proxyUrl ?? resolveProxyUrl(this.apiUrl);
         return new Sandbox({
@@ -3823,6 +4096,15 @@ var init_client = __esm({
           routingHint
         });
       }
+      /**
+       * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
+       *
+       * Blocks until the sandbox is ready or `startupTimeout` elapses. The returned
+       * `Sandbox` auto-terminates when `terminate()` is called.
+       *
+       * @param options.startupTimeout - Max seconds to wait for `Running` status (default 60).
+       * @throws {SandboxError} If the sandbox terminates during startup or the timeout elapses.
+       */
       async createAndConnect(options) {
         const startupTimeout = options?.startupTimeout ?? 60;
         let result;
@@ -3834,6 +4116,7 @@ var init_client = __esm({
         if (result.status === "running" /* RUNNING */) {
           const sandbox = this.connect(result.sandboxId, options?.proxyUrl, result.routingHint);
           sandbox._setOwner(this);
+          sandbox.traceId = result.traceId;
           return sandbox;
         }
         const deadline = Date.now() + startupTimeout * 1e3;
@@ -3842,6 +4125,7 @@ var init_client = __esm({
           if (info.status === "running" /* RUNNING */) {
             const sandbox = this.connect(result.sandboxId, options?.proxyUrl, info.routingHint);
             sandbox._setOwner(this);
+            sandbox.traceId = result.traceId;
             return sandbox;
           }
           if (info.status === "terminated" /* TERMINATED */) {