tensorlake 0.4.49 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,23 @@
-import { C as CreatePtySessionOptions, S as SandboxOptions, R as RunOptions, a as CommandResult, b as StartProcessOptions, P as ProcessInfo, c as SendSignalResponse, O as OutputResponse, d as OutputEvent, L as ListDirectoryResponse, e as PtySessionInfo, H as HealthResponse, D as DaemonInfo, f as SandboxClientOptions, g as CreateSandboxOptions, h as CreateSandboxResponse, i as SandboxInfo, U as UpdateSandboxOptions, j as SandboxPortAccess, k as SnapshotOptions, l as CreateSnapshotResponse, m as SnapshotInfo, n as SnapshotAndWaitOptions, o as CreatePoolOptions, p as CreateSandboxPoolResponse, q as SandboxPoolInfo, r as UpdatePoolOptions, s as CreateAndConnectOptions } from './sandbox-image-BQ6fJT92.cjs';
-export { t as ContainerResourcesInfo, u as ContainerState, v as CreateSandboxImageOptions, w as DirectoryEntry, x as DockerfileBuildPlan, y as DockerfileInstruction, I as Image, z as ImageBuildOperation, A as ImageBuildOperationType, A as ImageBuildOperationTypeValue, B as ImageOptions, N as NetworkConfig, E as OutputMode, F as PoolContainerInfo, G as ProcessStatus, J as SandboxImageSource, K as SandboxStatus, M as SnapshotContentMode, Q as SnapshotStatus, T as StdinMode, V as createSandboxImage, W as dockerfileContent } from './sandbox-image-BQ6fJT92.cjs';
+import { C as CreatePtySessionOptions, S as SandboxOptions, a as CreateAndConnectOptions, b as SandboxClientOptions, c as ConnectOptions, d as SnapshotInfo, e as SuspendResumeOptions, f as CheckpointOptions, R as RunOptions, g as CommandResult, h as StartProcessOptions, P as ProcessInfo, i as SendSignalResponse, O as OutputResponse, j as OutputEvent, L as ListDirectoryResponse, k as PtySessionInfo, H as HealthResponse, D as DaemonInfo, l as CreateSandboxOptions, m as CreateSandboxResponse, n as SandboxInfo, U as UpdateSandboxOptions, o as SandboxPortAccess, p as SnapshotOptions, q as CreateSnapshotResponse, r as SnapshotAndWaitOptions, s as CreatePoolOptions, t as CreateSandboxPoolResponse, u as SandboxPoolInfo, v as UpdatePoolOptions } from './sandbox-image-CMJ_FOOV.cjs';
+export { w as ContainerResourcesInfo, x as ContainerState, y as CreateSandboxImageOptions, z as DirectoryEntry, A as DockerfileBuildPlan, B as DockerfileInstruction, I as Image, E as ImageBuildOperation, F as ImageBuildOperationType, F as ImageBuildOperationTypeValue, G as ImageOptions, N as NetworkConfig, J as OutputMode, K as PoolContainerInfo, M as ProcessStatus, Q as SandboxImageSource, T as SandboxStatus, V as SnapshotContentMode, W as SnapshotStatus, X as StdinMode, Y as createSandboxImage, Z as dockerfileContent } from './sandbox-image-CMJ_FOOV.cjs';
+
+/**
+ * The return value of every SDK operation. Carries the W3C `trace_id` so callers
+ * can correlate a specific request with its server-side spans in Datadog APM or
+ * any other OTEL-compatible backend.
+ *
+ * Because this is an intersection type, all properties of `T` are accessible
+ * directly — existing code that ignores `traceId` continues to compile and run
+ * unchanged.
+ *
+ * @example
+ * const sandbox = await client.createSandbox(req);
+ * console.log(sandbox.id);      // existing field — unchanged
+ * console.log(sandbox.traceId); // new: look this up in Datadog APM
+ */
+type Traced<T> = T & {
+    readonly traceId: string;
+};
 
 type MouseButton = "left" | "middle" | "right";
 interface ConnectDesktopOptions {
@@ -147,6 +165,7 @@ declare class Pty {
  */
 declare class Sandbox {
     readonly sandboxId: string;
+    traceId: string | null;
     private readonly http;
     private readonly baseUrl;
     private readonly wsHeaders;
@@ -155,7 +174,56 @@ declare class Sandbox {
     constructor(options: SandboxOptions);
     /** @internal Used by SandboxClient.createAndConnect to set ownership. */
     _setOwner(client: SandboxClient): void;
+    /**
+     * 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 create(options?: CreateAndConnectOptions & Partial<SandboxClientOptions>): Promise<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 connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
+    /** Get information about a snapshot by ID. No sandbox handle needed. */
+    static getSnapshot(snapshotId: string, options?: Partial<SandboxClientOptions>): Promise<SnapshotInfo>;
+    /** Delete a snapshot by ID. No sandbox handle needed. */
+    static deleteSnapshot(snapshotId: string, options?: Partial<SandboxClientOptions>): Promise<void>;
+    private requireLifecycleClient;
+    /**
+     * Suspend this sandbox.
+     *
+     * By default blocks until the sandbox is fully `Suspended`. Pass
+     * `{ wait: false }` for fire-and-return.
+     */
+    suspend(options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * Resume this sandbox.
+     *
+     * By default blocks until the sandbox is `Running` and routable. Pass
+     * `{ wait: false }` for fire-and-return.
+     */
+    resume(options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * 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`).
+     */
+    checkpoint(options?: CheckpointOptions): Promise<SnapshotInfo | undefined>;
+    /**
+     * List snapshots taken from this sandbox.
+     */
+    listSnapshots(): Promise<SnapshotInfo[]>;
+    /** Close the HTTP client. The sandbox keeps running. */
     close(): void;
+    /** Terminate the sandbox and release all resources. */
     terminate(): Promise<void>;
     /**
      * Run a command to completion and return its output.
@@ -164,36 +232,67 @@ declare class Sandbox {
      * the process, streams output, and delivers the exit code over one connection.
      */
     run(command: string, options?: RunOptions): Promise<CommandResult>;
+    /**
+     * 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.
+     */
     startProcess(command: string, options?: StartProcessOptions): Promise<ProcessInfo>;
+    /** List all processes (running and exited) tracked by the sandbox daemon. */
     listProcesses(): Promise<ProcessInfo[]>;
+    /** Get current status and metadata for a process by PID. */
     getProcess(pid: number): Promise<ProcessInfo>;
+    /** Send SIGKILL to a process. */
     killProcess(pid: number): Promise<void>;
+    /** Send an arbitrary signal to a process (e.g. `15` for SIGTERM, `9` for SIGKILL). */
     sendSignal(pid: number, signal: number): Promise<SendSignalResponse>;
+    /** Write bytes to a process's stdin. The process must have been started with `stdinMode: StdinMode.PIPE`. */
     writeStdin(pid: number, data: Uint8Array): Promise<void>;
+    /** Close a process's stdin pipe, signalling EOF to the process. */
     closeStdin(pid: number): Promise<void>;
+    /** Return all captured stdout lines produced so far by a process. */
     getStdout(pid: number): Promise<OutputResponse>;
+    /** Return all captured stderr lines produced so far by a process. */
     getStderr(pid: number): Promise<OutputResponse>;
+    /** Return all captured stdout+stderr lines produced so far by a process. */
     getOutput(pid: number): Promise<OutputResponse>;
+    /** Stream stdout events from a process until it exits. Yields one `OutputEvent` per line. */
     followStdout(pid: number, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<OutputEvent>;
+    /** Stream stderr events from a process until it exits. Yields one `OutputEvent` per line. */
     followStderr(pid: number, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<OutputEvent>;
+    /** Stream combined stdout+stderr events from a process until it exits. Yields one `OutputEvent` per line. */
     followOutput(pid: number, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<OutputEvent>;
+    /** Read a file from the sandbox and return its raw bytes. */
     readFile(path: string): Promise<Uint8Array>;
+    /** Write raw bytes to a file in the sandbox, creating it if it does not exist. */
     writeFile(path: string, content: Uint8Array): Promise<void>;
+    /** Delete a file from the sandbox. */
     deleteFile(path: string): Promise<void>;
+    /** List the contents of a directory in the sandbox. */
     listDirectory(path: string): Promise<ListDirectoryResponse>;
+    /** Create an interactive PTY session. Returns a `sessionId` and `token` for WebSocket connection via `connectPty()`. */
     createPtySession(options: CreatePtySessionOptions): Promise<PtySessionInfo>;
+    /** Create a PTY session and connect to it immediately. Cleans up the session if the WebSocket connection fails. */
     createPty(options: CreatePtyOptions): Promise<Pty>;
+    /** Attach to an existing PTY session by ID and token and return a connected `Pty` handle. */
     connectPty(sessionId: string, token: string, options?: PtyConnectionOptions): Promise<Pty>;
+    /** Open a TCP tunnel to a port inside the sandbox and return the local listener. */
     createTunnel(remotePort: number, options?: CreateTunnelOptions): Promise<TcpTunnel>;
+    /** Connect to a sandbox VNC session for programmatic desktop control. */
     connectDesktop(options?: ConnectDesktopOptions): Promise<Desktop>;
     ptyWsUrl(sessionId: string, token: string): string;
+    /** Check the sandbox daemon health. */
     health(): Promise<HealthResponse>;
+    /** Get sandbox daemon info (version, uptime, process counts). */
     info(): Promise<DaemonInfo>;
 }
 
@@ -211,7 +310,8 @@ declare class SandboxClient {
     private readonly projectId;
     private readonly namespace;
     private readonly local;
-    constructor(options?: SandboxClientOptions);
+    /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
+    constructor(options?: SandboxClientOptions, _internal?: boolean);
     /** Create a client for the TensorLake cloud platform. */
     static forCloud(options?: {
         apiKey?: string;
@@ -226,30 +326,107 @@ declare class SandboxClient {
     }): SandboxClient;
     close(): void;
     private path;
-    create(options?: CreateSandboxOptions): Promise<CreateSandboxResponse>;
+    /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
+    create(options?: CreateSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
+    /** Get current state and metadata for a sandbox by ID. */
     get(sandboxId: string): Promise<SandboxInfo>;
+    /** List all sandboxes in the namespace. */
     list(): Promise<SandboxInfo[]>;
+    /** Update sandbox properties such as name, exposed ports, and proxy auth settings. */
     update(sandboxId: string, options: UpdateSandboxOptions): Promise<SandboxInfo>;
+    /** Get the current proxy port settings for a sandbox. */
     getPortAccess(sandboxId: string): Promise<SandboxPortAccess>;
+    /** Add one or more user ports to the sandbox proxy allowlist. */
     exposePorts(sandboxId: string, ports: number[], options?: {
         allowUnauthenticatedAccess?: boolean;
     }): Promise<SandboxInfo>;
+    /** Remove one or more user ports from the sandbox proxy allowlist. */
     unexposePorts(sandboxId: string, ports: number[]): Promise<SandboxInfo>;
+    /** Terminate and delete a sandbox. */
     delete(sandboxId: string): Promise<void>;
-    suspend(sandboxId: string): Promise<void>;
-    resume(sandboxId: string): Promise<void>;
-    claim(poolId: string): Promise<CreateSandboxResponse>;
+    /**
+     * 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`.
+     */
+    suspend(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * 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`.
+     */
+    resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
+    /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
+    claim(poolId: string): Promise<Traced<CreateSandboxResponse>>;
+    /**
+     * 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).
+     */
     snapshot(sandboxId: string, options?: SnapshotOptions): Promise<CreateSnapshotResponse>;
+    /** Get current status and metadata for a snapshot by ID. */
     getSnapshot(snapshotId: string): Promise<SnapshotInfo>;
+    /** List all snapshots in the namespace. */
     listSnapshots(): Promise<SnapshotInfo[]>;
+    /** Delete a snapshot by ID. */
     deleteSnapshot(snapshotId: string): Promise<void>;
+    /**
+     * 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.
+     */
     snapshotAndWait(sandboxId: string, options?: SnapshotAndWaitOptions): Promise<SnapshotInfo>;
+    /** Create a new sandbox pool with warm pre-booted containers. */
     createPool(options: CreatePoolOptions): Promise<CreateSandboxPoolResponse>;
+    /** Get current state and metadata for a sandbox pool by ID. */
     getPool(poolId: string): Promise<SandboxPoolInfo>;
+    /** List all sandbox pools in the namespace. */
     listPools(): Promise<SandboxPoolInfo[]>;
+    /** Replace the configuration of an existing sandbox pool. */
     updatePool(poolId: string, options: UpdatePoolOptions): Promise<SandboxPoolInfo>;
+    /** Delete a sandbox pool. Fails if the pool has active containers. */
     deletePool(poolId: string): Promise<void>;
+    /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
     connect(identifier: string, proxyUrl?: string, routingHint?: string): Sandbox;
+    /**
+     * 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.
+     */
     createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
 }
 
@@ -498,4 +675,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type BinaryPayload, type BuildInfo, type BuildLogEntry, CloudClient, type CloudClientOptions, CommandResult, type ConnectDesktopOptions, CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, CreatePoolOptions, type CreatePtyOptions, CreatePtySessionOptions, CreateSandboxOptions, CreateSandboxPoolResponse, CreateSandboxResponse, CreateSnapshotResponse, type CreateTunnelOptions, DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, HealthResponse, ListDirectoryResponse, type MouseButton, type NewSecret, OutputEvent, OutputResponse, PoolInUseError, PoolNotFoundError, ProcessInfo, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, RunOptions, Sandbox, SandboxClient, SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, SandboxInfo, SandboxNotFoundError, SandboxOptions, SandboxPoolInfo, SandboxPortAccess, type Secret, type SecretsList, type SecretsPagination, SendSignalResponse, SnapshotAndWaitOptions, SnapshotInfo, SnapshotOptions, type StartImageBuildRequest, StartProcessOptions, TcpTunnel, type TunnelAddress, UpdatePoolOptions, type UpsertSecretResponse };
+export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type BinaryPayload, type BuildInfo, type BuildLogEntry, CheckpointOptions, CloudClient, type CloudClientOptions, CommandResult, type ConnectDesktopOptions, ConnectOptions, CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, CreatePoolOptions, type CreatePtyOptions, CreatePtySessionOptions, CreateSandboxOptions, CreateSandboxPoolResponse, CreateSandboxResponse, CreateSnapshotResponse, type CreateTunnelOptions, DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, HealthResponse, ListDirectoryResponse, type MouseButton, type NewSecret, OutputEvent, OutputResponse, PoolInUseError, PoolNotFoundError, ProcessInfo, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, RunOptions, Sandbox, SandboxClient, SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, SandboxInfo, SandboxNotFoundError, SandboxOptions, SandboxPoolInfo, SandboxPortAccess, type Secret, type SecretsList, type SecretsPagination, SendSignalResponse, SnapshotAndWaitOptions, SnapshotInfo, SnapshotOptions, type StartImageBuildRequest, StartProcessOptions, SuspendResumeOptions, TcpTunnel, type TunnelAddress, UpdatePoolOptions, type UpsertSecretResponse };

package/dist/index.d.ts

@@ -1,5 +1,23 @@
-import { C as CreatePtySessionOptions, S as SandboxOptions, R as RunOptions, a as CommandResult, b as StartProcessOptions, P as ProcessInfo, c as SendSignalResponse, O as OutputResponse, d as OutputEvent, L as ListDirectoryResponse, e as PtySessionInfo, H as HealthResponse, D as DaemonInfo, f as SandboxClientOptions, g as CreateSandboxOptions, h as CreateSandboxResponse, i as SandboxInfo, U as UpdateSandboxOptions, j as SandboxPortAccess, k as SnapshotOptions, l as CreateSnapshotResponse, m as SnapshotInfo, n as SnapshotAndWaitOptions, o as CreatePoolOptions, p as CreateSandboxPoolResponse, q as SandboxPoolInfo, r as UpdatePoolOptions, s as CreateAndConnectOptions } from './sandbox-image-BQ6fJT92.js';
-export { t as ContainerResourcesInfo, u as ContainerState, v as CreateSandboxImageOptions, w as DirectoryEntry, x as DockerfileBuildPlan, y as DockerfileInstruction, I as Image, z as ImageBuildOperation, A as ImageBuildOperationType, A as ImageBuildOperationTypeValue, B as ImageOptions, N as NetworkConfig, E as OutputMode, F as PoolContainerInfo, G as ProcessStatus, J as SandboxImageSource, K as SandboxStatus, M as SnapshotContentMode, Q as SnapshotStatus, T as StdinMode, V as createSandboxImage, W as dockerfileContent } from './sandbox-image-BQ6fJT92.js';
+import { C as CreatePtySessionOptions, S as SandboxOptions, a as CreateAndConnectOptions, b as SandboxClientOptions, c as ConnectOptions, d as SnapshotInfo, e as SuspendResumeOptions, f as CheckpointOptions, R as RunOptions, g as CommandResult, h as StartProcessOptions, P as ProcessInfo, i as SendSignalResponse, O as OutputResponse, j as OutputEvent, L as ListDirectoryResponse, k as PtySessionInfo, H as HealthResponse, D as DaemonInfo, l as CreateSandboxOptions, m as CreateSandboxResponse, n as SandboxInfo, U as UpdateSandboxOptions, o as SandboxPortAccess, p as SnapshotOptions, q as CreateSnapshotResponse, r as SnapshotAndWaitOptions, s as CreatePoolOptions, t as CreateSandboxPoolResponse, u as SandboxPoolInfo, v as UpdatePoolOptions } from './sandbox-image-CMJ_FOOV.js';
+export { w as ContainerResourcesInfo, x as ContainerState, y as CreateSandboxImageOptions, z as DirectoryEntry, A as DockerfileBuildPlan, B as DockerfileInstruction, I as Image, E as ImageBuildOperation, F as ImageBuildOperationType, F as ImageBuildOperationTypeValue, G as ImageOptions, N as NetworkConfig, J as OutputMode, K as PoolContainerInfo, M as ProcessStatus, Q as SandboxImageSource, T as SandboxStatus, V as SnapshotContentMode, W as SnapshotStatus, X as StdinMode, Y as createSandboxImage, Z as dockerfileContent } from './sandbox-image-CMJ_FOOV.js';
+
+/**
+ * The return value of every SDK operation. Carries the W3C `trace_id` so callers
+ * can correlate a specific request with its server-side spans in Datadog APM or
+ * any other OTEL-compatible backend.
+ *
+ * Because this is an intersection type, all properties of `T` are accessible
+ * directly — existing code that ignores `traceId` continues to compile and run
+ * unchanged.
+ *
+ * @example
+ * const sandbox = await client.createSandbox(req);
+ * console.log(sandbox.id);      // existing field — unchanged
+ * console.log(sandbox.traceId); // new: look this up in Datadog APM
+ */
+type Traced<T> = T & {
+    readonly traceId: string;
+};
 
 type MouseButton = "left" | "middle" | "right";
 interface ConnectDesktopOptions {
@@ -147,6 +165,7 @@ declare class Pty {
  */
 declare class Sandbox {
     readonly sandboxId: string;
+    traceId: string | null;
     private readonly http;
     private readonly baseUrl;
     private readonly wsHeaders;
@@ -155,7 +174,56 @@ declare class Sandbox {
     constructor(options: SandboxOptions);
     /** @internal Used by SandboxClient.createAndConnect to set ownership. */
     _setOwner(client: SandboxClient): void;
+    /**
+     * 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 create(options?: CreateAndConnectOptions & Partial<SandboxClientOptions>): Promise<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 connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
+    /** Get information about a snapshot by ID. No sandbox handle needed. */
+    static getSnapshot(snapshotId: string, options?: Partial<SandboxClientOptions>): Promise<SnapshotInfo>;
+    /** Delete a snapshot by ID. No sandbox handle needed. */
+    static deleteSnapshot(snapshotId: string, options?: Partial<SandboxClientOptions>): Promise<void>;
+    private requireLifecycleClient;
+    /**
+     * Suspend this sandbox.
+     *
+     * By default blocks until the sandbox is fully `Suspended`. Pass
+     * `{ wait: false }` for fire-and-return.
+     */
+    suspend(options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * Resume this sandbox.
+     *
+     * By default blocks until the sandbox is `Running` and routable. Pass
+     * `{ wait: false }` for fire-and-return.
+     */
+    resume(options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * 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`).
+     */
+    checkpoint(options?: CheckpointOptions): Promise<SnapshotInfo | undefined>;
+    /**
+     * List snapshots taken from this sandbox.
+     */
+    listSnapshots(): Promise<SnapshotInfo[]>;
+    /** Close the HTTP client. The sandbox keeps running. */
     close(): void;
+    /** Terminate the sandbox and release all resources. */
     terminate(): Promise<void>;
     /**
      * Run a command to completion and return its output.
@@ -164,36 +232,67 @@ declare class Sandbox {
      * the process, streams output, and delivers the exit code over one connection.
      */
     run(command: string, options?: RunOptions): Promise<CommandResult>;
+    /**
+     * 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.
+     */
     startProcess(command: string, options?: StartProcessOptions): Promise<ProcessInfo>;
+    /** List all processes (running and exited) tracked by the sandbox daemon. */
     listProcesses(): Promise<ProcessInfo[]>;
+    /** Get current status and metadata for a process by PID. */
     getProcess(pid: number): Promise<ProcessInfo>;
+    /** Send SIGKILL to a process. */
     killProcess(pid: number): Promise<void>;
+    /** Send an arbitrary signal to a process (e.g. `15` for SIGTERM, `9` for SIGKILL). */
     sendSignal(pid: number, signal: number): Promise<SendSignalResponse>;
+    /** Write bytes to a process's stdin. The process must have been started with `stdinMode: StdinMode.PIPE`. */
     writeStdin(pid: number, data: Uint8Array): Promise<void>;
+    /** Close a process's stdin pipe, signalling EOF to the process. */
     closeStdin(pid: number): Promise<void>;
+    /** Return all captured stdout lines produced so far by a process. */
     getStdout(pid: number): Promise<OutputResponse>;
+    /** Return all captured stderr lines produced so far by a process. */
     getStderr(pid: number): Promise<OutputResponse>;
+    /** Return all captured stdout+stderr lines produced so far by a process. */
     getOutput(pid: number): Promise<OutputResponse>;
+    /** Stream stdout events from a process until it exits. Yields one `OutputEvent` per line. */
     followStdout(pid: number, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<OutputEvent>;
+    /** Stream stderr events from a process until it exits. Yields one `OutputEvent` per line. */
     followStderr(pid: number, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<OutputEvent>;
+    /** Stream combined stdout+stderr events from a process until it exits. Yields one `OutputEvent` per line. */
     followOutput(pid: number, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<OutputEvent>;
+    /** Read a file from the sandbox and return its raw bytes. */
     readFile(path: string): Promise<Uint8Array>;
+    /** Write raw bytes to a file in the sandbox, creating it if it does not exist. */
     writeFile(path: string, content: Uint8Array): Promise<void>;
+    /** Delete a file from the sandbox. */
     deleteFile(path: string): Promise<void>;
+    /** List the contents of a directory in the sandbox. */
     listDirectory(path: string): Promise<ListDirectoryResponse>;
+    /** Create an interactive PTY session. Returns a `sessionId` and `token` for WebSocket connection via `connectPty()`. */
     createPtySession(options: CreatePtySessionOptions): Promise<PtySessionInfo>;
+    /** Create a PTY session and connect to it immediately. Cleans up the session if the WebSocket connection fails. */
     createPty(options: CreatePtyOptions): Promise<Pty>;
+    /** Attach to an existing PTY session by ID and token and return a connected `Pty` handle. */
     connectPty(sessionId: string, token: string, options?: PtyConnectionOptions): Promise<Pty>;
+    /** Open a TCP tunnel to a port inside the sandbox and return the local listener. */
     createTunnel(remotePort: number, options?: CreateTunnelOptions): Promise<TcpTunnel>;
+    /** Connect to a sandbox VNC session for programmatic desktop control. */
     connectDesktop(options?: ConnectDesktopOptions): Promise<Desktop>;
     ptyWsUrl(sessionId: string, token: string): string;
+    /** Check the sandbox daemon health. */
     health(): Promise<HealthResponse>;
+    /** Get sandbox daemon info (version, uptime, process counts). */
     info(): Promise<DaemonInfo>;
 }
 
@@ -211,7 +310,8 @@ declare class SandboxClient {
     private readonly projectId;
     private readonly namespace;
     private readonly local;
-    constructor(options?: SandboxClientOptions);
+    /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
+    constructor(options?: SandboxClientOptions, _internal?: boolean);
     /** Create a client for the TensorLake cloud platform. */
     static forCloud(options?: {
         apiKey?: string;
@@ -226,30 +326,107 @@ declare class SandboxClient {
     }): SandboxClient;
     close(): void;
     private path;
-    create(options?: CreateSandboxOptions): Promise<CreateSandboxResponse>;
+    /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
+    create(options?: CreateSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
+    /** Get current state and metadata for a sandbox by ID. */
     get(sandboxId: string): Promise<SandboxInfo>;
+    /** List all sandboxes in the namespace. */
     list(): Promise<SandboxInfo[]>;
+    /** Update sandbox properties such as name, exposed ports, and proxy auth settings. */
     update(sandboxId: string, options: UpdateSandboxOptions): Promise<SandboxInfo>;
+    /** Get the current proxy port settings for a sandbox. */
     getPortAccess(sandboxId: string): Promise<SandboxPortAccess>;
+    /** Add one or more user ports to the sandbox proxy allowlist. */
     exposePorts(sandboxId: string, ports: number[], options?: {
         allowUnauthenticatedAccess?: boolean;
     }): Promise<SandboxInfo>;
+    /** Remove one or more user ports from the sandbox proxy allowlist. */
     unexposePorts(sandboxId: string, ports: number[]): Promise<SandboxInfo>;
+    /** Terminate and delete a sandbox. */
     delete(sandboxId: string): Promise<void>;
-    suspend(sandboxId: string): Promise<void>;
-    resume(sandboxId: string): Promise<void>;
-    claim(poolId: string): Promise<CreateSandboxResponse>;
+    /**
+     * 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`.
+     */
+    suspend(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * 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`.
+     */
+    resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
+    /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
+    claim(poolId: string): Promise<Traced<CreateSandboxResponse>>;
+    /**
+     * 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).
+     */
     snapshot(sandboxId: string, options?: SnapshotOptions): Promise<CreateSnapshotResponse>;
+    /** Get current status and metadata for a snapshot by ID. */
     getSnapshot(snapshotId: string): Promise<SnapshotInfo>;
+    /** List all snapshots in the namespace. */
     listSnapshots(): Promise<SnapshotInfo[]>;
+    /** Delete a snapshot by ID. */
     deleteSnapshot(snapshotId: string): Promise<void>;
+    /**
+     * 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.
+     */
     snapshotAndWait(sandboxId: string, options?: SnapshotAndWaitOptions): Promise<SnapshotInfo>;
+    /** Create a new sandbox pool with warm pre-booted containers. */
     createPool(options: CreatePoolOptions): Promise<CreateSandboxPoolResponse>;
+    /** Get current state and metadata for a sandbox pool by ID. */
     getPool(poolId: string): Promise<SandboxPoolInfo>;
+    /** List all sandbox pools in the namespace. */
     listPools(): Promise<SandboxPoolInfo[]>;
+    /** Replace the configuration of an existing sandbox pool. */
     updatePool(poolId: string, options: UpdatePoolOptions): Promise<SandboxPoolInfo>;
+    /** Delete a sandbox pool. Fails if the pool has active containers. */
     deletePool(poolId: string): Promise<void>;
+    /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
     connect(identifier: string, proxyUrl?: string, routingHint?: string): Sandbox;
+    /**
+     * 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.
+     */
     createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
 }
 
@@ -498,4 +675,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type BinaryPayload, type BuildInfo, type BuildLogEntry, CloudClient, type CloudClientOptions, CommandResult, type ConnectDesktopOptions, CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, CreatePoolOptions, type CreatePtyOptions, CreatePtySessionOptions, CreateSandboxOptions, CreateSandboxPoolResponse, CreateSandboxResponse, CreateSnapshotResponse, type CreateTunnelOptions, DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, HealthResponse, ListDirectoryResponse, type MouseButton, type NewSecret, OutputEvent, OutputResponse, PoolInUseError, PoolNotFoundError, ProcessInfo, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, RunOptions, Sandbox, SandboxClient, SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, SandboxInfo, SandboxNotFoundError, SandboxOptions, SandboxPoolInfo, SandboxPortAccess, type Secret, type SecretsList, type SecretsPagination, SendSignalResponse, SnapshotAndWaitOptions, SnapshotInfo, SnapshotOptions, type StartImageBuildRequest, StartProcessOptions, TcpTunnel, type TunnelAddress, UpdatePoolOptions, type UpsertSecretResponse };
+export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type BinaryPayload, type BuildInfo, type BuildLogEntry, CheckpointOptions, CloudClient, type CloudClientOptions, CommandResult, type ConnectDesktopOptions, ConnectOptions, CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, CreatePoolOptions, type CreatePtyOptions, CreatePtySessionOptions, CreateSandboxOptions, CreateSandboxPoolResponse, CreateSandboxResponse, CreateSnapshotResponse, type CreateTunnelOptions, DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, HealthResponse, ListDirectoryResponse, type MouseButton, type NewSecret, OutputEvent, OutputResponse, PoolInUseError, PoolNotFoundError, ProcessInfo, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, RunOptions, Sandbox, SandboxClient, SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, SandboxInfo, SandboxNotFoundError, SandboxOptions, SandboxPoolInfo, SandboxPortAccess, type Secret, type SecretsList, type SecretsPagination, SendSignalResponse, SnapshotAndWaitOptions, SnapshotInfo, SnapshotOptions, type StartImageBuildRequest, StartProcessOptions, SuspendResumeOptions, TcpTunnel, type TunnelAddress, UpdatePoolOptions, type UpsertSecretResponse };