tensorlake 0.4.50 → 0.5.1

package/dist/sandbox-image.cjs

@@ -79,10 +79,11 @@ var init_models = __esm({
 });
 
 // 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";
@@ -156,6 +157,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);
@@ -225,7 +232,7 @@ var init_http = __esm({
         allowH2: true
       })
     );
-    HttpClient = class {
+    HttpClient = class _HttpClient {
       baseUrl;
       headers;
       maxRetries;
@@ -238,7 +245,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}`;
         }
@@ -267,8 +276,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) {
@@ -282,7 +291,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) {
@@ -297,7 +306,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) {
@@ -310,7 +319,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,
@@ -318,9 +327,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) {
@@ -341,7 +359,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,
@@ -350,7 +368,7 @@ var init_http = __esm({
               continue;
             }
             if (allowHttpErrors) {
-              return response;
+              return { response, traceId };
             }
             const errorBody = await response.text().catch(() => "");
             throwMappedError(response.status, errorBody, path2);
@@ -3097,13 +3115,17 @@ var init_sandbox = __esm({
     };
     Sandbox = class {
       sandboxId;
+      traceId = null;
       http;
       baseUrl;
       wsHeaders;
       ownsSandbox = false;
       lifecycleClient = null;
+      lifecycleIdentifier;
+      sandboxName = null;
       constructor(options) {
         this.sandboxId = options.sandboxId;
+        this.lifecycleIdentifier = options.sandboxId;
         const proxyUrl = options.proxyUrl ?? SANDBOX_PROXY_URL;
         const { baseUrl, hostHeader } = resolveProxyTarget(proxyUrl, options.sandboxId);
         this.baseUrl = baseUrl;
@@ -3129,21 +3151,182 @@ var init_sandbox = __esm({
           routingHint: options.routingHint
         });
       }
+      get name() {
+        return this.sandboxName;
+      }
+      /** @internal Used by client wiring to keep locally cached name in sync. */
+      _setName(name) {
+        this.sandboxName = name;
+      }
+      /** @internal Used by lifecycle operations to pin to canonical sandbox ID. */
+      _setLifecycleIdentifier(identifier) {
+        this.lifecycleIdentifier = identifier;
+      }
       /** @internal Used by SandboxClient.createAndConnect to set ownership. */
       _setOwner(client) {
         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
+        );
+        const info = await client.get(options.sandboxId);
+        const sandbox = client.connect(
+          info.sandboxId,
+          options.proxyUrl,
+          options.routingHint ?? info.routingHint
+        );
+        sandbox.lifecycleClient = client;
+        sandbox._setLifecycleIdentifier(info.sandboxId);
+        sandbox._setName(info.name ?? null);
+        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;
+      }
+      /**
+       * Fetch the current sandbox status from the server.
+       *
+       * Always hits the network — the value is not cached locally because the
+       * status changes over the sandbox's lifecycle.
+       */
+      async status() {
+        const client = this.requireLifecycleClient("read_status");
+        const info = await client.get(this.lifecycleIdentifier);
+        this._setLifecycleIdentifier(info.sandboxId);
+        this._setName(info.name ?? null);
+        return info.status;
+      }
+      /**
+       * Update this sandbox's properties (name, exposed ports, proxy auth).
+       *
+       * Naming an ephemeral sandbox makes it non-ephemeral and enables
+       * suspend/resume.
+       */
+      async update(options) {
+        const client = this.requireLifecycleClient("update");
+        const info = await client.update(this.lifecycleIdentifier, options);
+        this._setLifecycleIdentifier(info.sandboxId);
+        this._setName(info.name ?? null);
+        return info;
+      }
+      /**
+       * 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.lifecycleIdentifier, 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.lifecycleIdentifier, 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.lifecycleIdentifier, { contentMode: options.contentMode });
+          return void 0;
+        }
+        return client.snapshotAndWait(this.lifecycleIdentifier, {
+          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();
+        const filtered = all.filter((s) => s.sandboxId === this.lifecycleIdentifier);
+        return Object.assign(filtered, { traceId: all.traceId });
+      }
+      /** 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;
         this.lifecycleClient = null;
         this.close();
         if (client) {
-          await client.delete(this.sandboxId);
+          await client.delete(this.lifecycleIdentifier);
         }
       }
       // --- High-level convenience ---
@@ -3189,6 +3372,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;
@@ -3210,13 +3401,16 @@ 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",
           "/api/v1/processes"
         );
-        return (raw.processes ?? []).map((p) => fromSnakeKeys(p));
+        const processes = (raw.processes ?? []).map((p) => fromSnakeKeys(p));
+        return Object.assign(processes, { traceId: raw.traceId });
       }
+      /** Get current status and metadata for a process by PID. */
       async getProcess(pid) {
         const raw = await this.http.requestJson(
           "GET",
@@ -3224,9 +3418,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",
@@ -3236,15 +3432,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",
@@ -3252,6 +3451,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",
@@ -3259,6 +3459,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",
@@ -3267,6 +3468,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",
@@ -3280,6 +3482,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",
@@ -3293,6 +3496,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",
@@ -3307,12 +3511,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",
@@ -3320,12 +3526,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",
@@ -3334,6 +3542,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,
@@ -3350,6 +3559,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);
@@ -3363,6 +3573,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;
@@ -3387,6 +3598,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,
@@ -3397,6 +3609,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,
@@ -3419,6 +3632,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",
@@ -3426,6 +3640,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",
@@ -3438,6 +3653,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));
 }
@@ -3474,7 +3693,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;
@@ -3514,12 +3739,13 @@ 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: {
             cpus: options?.cpus ?? 1,
             memory_mb: options?.memoryMb ?? 1024,
-            ephemeral_disk_mb: options?.ephemeralDiskMb ?? 1024
+            ...options?.diskMb != null ? { disk_mb: options.diskMb } : {}
           }
         };
         if (options?.image != null) body.image = options.image;
@@ -3540,8 +3766,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",
@@ -3549,15 +3777,18 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "sandboxId");
       }
+      /** List all sandboxes in the namespace. */
       async list() {
         const raw = await this.http.requestJson(
           "GET",
           this.path("sandboxes")
         );
-        return (raw.sandboxes ?? []).map(
+        const sandboxes = (raw.sandboxes ?? []).map(
           (s) => fromSnakeKeys(s, "sandboxId")
         );
+        return Object.assign(sandboxes, { traceId: raw.traceId });
       }
+      /** 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;
@@ -3577,6 +3808,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 {
@@ -3585,6 +3817,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);
@@ -3597,6 +3830,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);
@@ -3607,32 +3841,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(
@@ -3642,6 +3942,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",
@@ -3649,21 +3950,37 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "snapshotId");
       }
+      /** List all snapshots in the namespace. */
       async listSnapshots() {
         const raw = await this.http.requestJson(
           "GET",
           this.path("snapshots")
         );
-        return (raw.snapshots ?? []).map(
+        const snapshots = (raw.snapshots ?? []).map(
           (s) => fromSnakeKeys(s, "snapshotId")
         );
+        return Object.assign(snapshots, { traceId: raw.traceId });
       }
+      /** 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;
@@ -3686,6 +4003,7 @@ var init_client = __esm({
         );
       }
       // --- Pools ---
+      /** Create a new sandbox pool with warm pre-booted containers. */
       async createPool(options) {
         const body = {
           image: options.image,
@@ -3707,6 +4025,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",
@@ -3714,15 +4033,18 @@ var init_client = __esm({
         );
         return fromSnakeKeys(raw, "poolId");
       }
+      /** List all sandbox pools in the namespace. */
       async listPools() {
         const raw = await this.http.requestJson(
           "GET",
           this.path("sandbox-pools")
         );
-        return (raw.pools ?? []).map(
+        const pools = (raw.pools ?? []).map(
           (p) => fromSnakeKeys(p, "poolId")
         );
+        return Object.assign(pools, { traceId: raw.traceId });
       }
+      /** Replace the configuration of an existing sandbox pool. */
       async updatePool(poolId, options) {
         const body = {
           image: options.image,
@@ -3744,6 +4066,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",
@@ -3751,6 +4074,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({
@@ -3762,26 +4086,35 @@ 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;
-        if (options?.poolId != null) {
-          result = await this.claim(options.poolId);
-        } else {
-          result = await this.create(options);
-        }
-        if (result.status === "running" /* RUNNING */) {
-          const sandbox = this.connect(result.sandboxId, options?.proxyUrl, result.routingHint);
+        const result = options?.poolId != null ? await this.claim(options.poolId) : await this.create(options);
+        const requestedName = options?.poolId != null ? null : options?.name ?? null;
+        const finishConnect = (routingHint, name) => {
+          const sandbox = this.connect(result.sandboxId, options?.proxyUrl, routingHint);
           sandbox._setOwner(this);
+          sandbox.traceId = result.traceId;
+          sandbox._setLifecycleIdentifier(result.sandboxId);
+          sandbox._setName(name ?? requestedName);
           return sandbox;
+        };
+        if (result.status === "running" /* RUNNING */) {
+          return finishConnect(result.routingHint, result.name);
         }
         const deadline = Date.now() + startupTimeout * 1e3;
         while (Date.now() < deadline) {
           const info = await this.get(result.sandboxId);
           if (info.status === "running" /* RUNNING */) {
-            const sandbox = this.connect(result.sandboxId, options?.proxyUrl, info.routingHint);
-            sandbox._setOwner(this);
-            return sandbox;
+            return finishConnect(info.routingHint, info.name);
           }
           if (info.status === "terminated" /* TERMINATED */) {
             throw new SandboxError(
@@ -4527,7 +4860,8 @@ async function createSandboxImage(source, options = {}, deps = {}) {
     sandbox = await client.createAndConnect({
       ...plan.baseImage == null ? {} : { image: plan.baseImage },
       cpus: options.cpus ?? 2,
-      memoryMb: options.memoryMb ?? 4096
+      memoryMb: options.memoryMb ?? 4096,
+      ...options.diskMb != null ? { diskMb: options.diskMb } : {}
     });
     emit({
       type: "status",
@@ -4540,8 +4874,7 @@ async function createSandboxImage(source, options = {}, deps = {}) {
     });
     emit({
       type: "snapshot_created",
-      snapshot_id: snapshot.snapshotId,
-      snapshot_uri: snapshot.snapshotUri ?? null
+      snapshot_id: snapshot.snapshotId
     });
     if (!snapshot.snapshotUri) {
       throw new Error(
@@ -4585,27 +4918,33 @@ async function runCreateSandboxImageCli(argv = process.argv.slice(2)) {
       name: { type: "string", short: "n" },
       cpus: { type: "string" },
       memory: { type: "string" },
+      disk: { type: "string" },
       public: { type: "boolean", default: false }
     }
   });
   const dockerfilePath = parsed.positionals[0];
   if (!dockerfilePath) {
-    throw new Error("Usage: tensorlake-create-sandbox-image <dockerfile_path> [--name NAME] [--cpus N] [--memory MB] [--public]");
+    throw new Error("Usage: tensorlake-create-sandbox-image <dockerfile_path> [--name NAME] [--cpus N] [--memory MB] [--disk GB] [--public]");
   }
   const cpus = parsed.values.cpus != null ? Number(parsed.values.cpus) : void 0;
   const memoryMb = parsed.values.memory != null ? Number(parsed.values.memory) : void 0;
+  const diskGb = parsed.values.disk != null ? Number(parsed.values.disk) : void 0;
   if (cpus != null && !Number.isFinite(cpus)) {
     throw new Error(`Invalid --cpus value: ${parsed.values.cpus}`);
   }
   if (memoryMb != null && !Number.isInteger(memoryMb)) {
     throw new Error(`Invalid --memory value: ${parsed.values.memory}`);
   }
+  if (diskGb != null && !Number.isInteger(diskGb)) {
+    throw new Error(`Invalid --disk value: ${parsed.values.disk}`);
+  }
   await createSandboxImage(
     dockerfilePath,
     {
       registeredName: parsed.values.name,
       cpus,
       memoryMb,
+      diskMb: diskGb != null ? diskGb * 1024 : void 0,
       isPublic: parsed.values.public
     },
     { emit: ndjsonStdoutEmit }