langsmith 0.5.19 → 0.5.20

package/dist/experimental/sandbox/client.cjs

@@ -10,6 +10,27 @@ const async_caller_js_1 = require("../../utils/async_caller.cjs");
 const sandbox_js_1 = require("./sandbox.cjs");
 const errors_js_1 = require("./errors.cjs");
 const helpers_js_1 = require("./helpers.cjs");
+/**
+ * Sleep that can be interrupted by an AbortSignal.
+ * Resolves after `ms` milliseconds or rejects immediately if the signal fires.
+ */
+function sleepWithSignal(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /**
  * Get the default sandbox API endpoint from environment.
  *
@@ -115,6 +136,25 @@ class SandboxClient {
     getApiKey() {
         return this._apiKey;
     }
+    /**
+     * JSON POST helper. Sends JSON body, checks response status,
+     * and returns the Response for further processing.
+     * Throws on non-ok responses via handleClientHttpError.
+     * Callers can add specific status checks (e.g. 404) before calling this.
+     * @internal
+     */
+    async _postJson(url, body, options) {
+        const response = await this._fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        if (!response.ok) {
+            await (0, helpers_js_1.handleClientHttpError)(response);
+        }
+        return response;
+    }
     // =========================================================================
     // Volume Operations
     // =========================================================================
@@ -540,14 +580,25 @@ class SandboxClient {
      * ```
      */
     async createSandbox(templateName, options = {}) {
-        const { name, timeout = 30, waitForReady = true, ttlSeconds, idleTtlSeconds, } = options;
+        const { snapshotId, name, timeout = 30, waitForReady = true, ttlSeconds, idleTtlSeconds, vCpus, memBytes, fsCapacityBytes, } = options;
+        if (!templateName && !snapshotId) {
+            throw new Error("Either templateName or snapshotId is required");
+        }
+        if (templateName && snapshotId) {
+            throw new Error("Cannot specify both templateName and snapshotId");
+        }
         (0, helpers_js_1.validateTtl)(ttlSeconds, "ttlSeconds");
         (0, helpers_js_1.validateTtl)(idleTtlSeconds, "idleTtlSeconds");
         const url = `${this._baseUrl}/boxes`;
         const payload = {
-            template_name: templateName,
             wait_for_ready: waitForReady,
         };
+        if (templateName) {
+            payload.template_name = templateName;
+        }
+        if (snapshotId) {
+            payload.snapshot_id = snapshotId;
+        }
         if (waitForReady) {
             payload.timeout = timeout;
         }
@@ -560,6 +611,15 @@ class SandboxClient {
         if (idleTtlSeconds !== undefined) {
             payload.idle_ttl_seconds = idleTtlSeconds;
         }
+        if (vCpus !== undefined) {
+            payload.vcpus = vCpus;
+        }
+        if (memBytes !== undefined) {
+            payload.mem_bytes = memBytes;
+        }
+        if (fsCapacityBytes !== undefined) {
+            payload.fs_capacity_bytes = fsCapacityBytes;
+        }
         const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
@@ -582,9 +642,9 @@ class SandboxClient {
      * @returns Sandbox.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    async getSandbox(name) {
+    async getSandbox(name, options) {
         const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
-        const response = await this._fetch(url);
+        const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
                 throw new errors_js_1.LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
@@ -679,9 +739,9 @@ class SandboxClient {
      * @returns ResourceStatus with status and optional status_message.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    async getSandboxStatus(name) {
+    async getSandboxStatus(name, options) {
         const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
-        const response = await this._fetch(url);
+        const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
                 throw new errors_js_1.LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
@@ -711,22 +771,183 @@ class SandboxClient {
      * ```
      */
     async waitForSandbox(name, options = {}) {
-        const { timeout = 120, pollInterval = 1.0 } = options;
+        const { timeout = 120, pollInterval = 1.0, signal } = options;
         const deadline = Date.now() + timeout * 1000;
         let lastStatus = "provisioning";
         while (Date.now() < deadline) {
-            const statusResult = await this.getSandboxStatus(name);
+            signal?.throwIfAborted();
+            const statusResult = await this.getSandboxStatus(name, { signal });
             lastStatus = statusResult.status;
             if (statusResult.status === "ready") {
-                return this.getSandbox(name);
+                return this.getSandbox(name, { signal });
             }
             if (statusResult.status === "failed") {
                 throw new errors_js_1.LangSmithResourceCreationError(statusResult.status_message ?? `Sandbox '${name}' creation failed`, "sandbox");
             }
-            // Wait before polling again
-            await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+            // Wait before polling again, capped to remaining time + jitter
+            const remaining = deadline - Date.now();
+            const jitter = pollInterval * 200 * (Math.random() - 0.5); // ±10%
+            const delay = Math.min(pollInterval * 1000 + jitter, remaining);
+            if (delay > 0) {
+                await sleepWithSignal(delay, signal);
+            }
         }
         throw new errors_js_1.LangSmithResourceTimeoutError(`Sandbox '${name}' did not become ready within ${timeout}s`, "sandbox", lastStatus);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * @param name - Sandbox name.
+     * @param options - Options with timeout.
+     * @returns Sandbox in "ready" status.
+     */
+    async startSandbox(name, options = {}) {
+        const { timeout = 120, signal } = options;
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/start`;
+        await this._postJson(url, {}, { signal });
+        return this.waitForSandbox(name, { timeout, signal });
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     *
+     * @param name - Sandbox name.
+     */
+    async stopSandbox(name) {
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/stop`;
+        await this._postJson(url, {});
+    }
+    // =========================================================================
+    // Snapshot Operations
+    // =========================================================================
+    /**
+     * Build a snapshot from a Docker image.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param name - Snapshot name.
+     * @param dockerImage - Docker image to build from (e.g., "python:3.12-slim").
+     * @param fsCapacityBytes - Filesystem capacity in bytes.
+     * @param options - Additional options (registry credentials, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
+        const { registryId, registryUrl, registryUsername, registryPassword, timeout = 60, signal, } = options;
+        const url = `${this._baseUrl}/snapshots`;
+        const payload = {
+            name,
+            docker_image: dockerImage,
+            fs_capacity_bytes: fsCapacityBytes,
+        };
+        if (registryId !== undefined) {
+            payload.registry_id = registryId;
+        }
+        if (registryUrl !== undefined) {
+            payload.registry_url = registryUrl;
+        }
+        if (registryUsername !== undefined) {
+            payload.registry_username = registryUsername;
+        }
+        if (registryPassword !== undefined) {
+            payload.registry_password = registryPassword;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const snapshot = (await response.json());
+        return this.waitForSnapshot(snapshot.id, { timeout, signal });
+    }
+    /**
+     * Capture a snapshot from a running sandbox.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param sandboxName - Name of the sandbox to capture from.
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(sandboxName, name, options = {}) {
+        const { checkpoint, timeout = 60, signal } = options;
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(sandboxName)}/snapshot`;
+        const payload = { name };
+        if (checkpoint !== undefined) {
+            payload.checkpoint = checkpoint;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const snapshot = (await response.json());
+        return this.waitForSnapshot(snapshot.id, { timeout, signal });
+    }
+    /**
+     * Get a snapshot by ID.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @returns Snapshot.
+     */
+    async getSnapshot(snapshotId, options) {
+        const url = `${this._baseUrl}/snapshots/${encodeURIComponent(snapshotId)}`;
+        const response = await this._fetch(url, { signal: options?.signal });
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new errors_js_1.LangSmithResourceNotFoundError(`Snapshot '${snapshotId}' not found`, "snapshot");
+            }
+            await (0, helpers_js_1.handleClientHttpError)(response);
+        }
+        return (await response.json());
+    }
+    /**
+     * List all snapshots.
+     *
+     * @returns List of Snapshots.
+     */
+    async listSnapshots() {
+        const url = `${this._baseUrl}/snapshots`;
+        const response = await this._fetch(url);
+        if (!response.ok) {
+            await (0, helpers_js_1.handleClientHttpError)(response);
+        }
+        const data = await response.json();
+        return (data.snapshots ?? []);
+    }
+    /**
+     * Delete a snapshot.
+     *
+     * @param snapshotId - Snapshot UUID.
+     */
+    async deleteSnapshot(snapshotId) {
+        const url = `${this._baseUrl}/snapshots/${encodeURIComponent(snapshotId)}`;
+        const response = await this._fetch(url, { method: "DELETE" });
+        if (!response.ok) {
+            await (0, helpers_js_1.handleClientHttpError)(response);
+        }
+    }
+    /**
+     * Poll until a snapshot reaches "ready" or "failed" status.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Snapshot in "ready" status.
+     */
+    async waitForSnapshot(snapshotId, options = {}) {
+        const { timeout = 300, pollInterval = 2.0, signal } = options;
+        const deadline = Date.now() + timeout * 1000;
+        let lastStatus = "building";
+        while (Date.now() < deadline) {
+            signal?.throwIfAborted();
+            const snapshot = await this.getSnapshot(snapshotId, { signal });
+            lastStatus = snapshot.status;
+            if (snapshot.status === "ready") {
+                return snapshot;
+            }
+            if (snapshot.status === "failed") {
+                throw new errors_js_1.LangSmithResourceCreationError(snapshot.status_message ?? `Snapshot '${snapshotId}' build failed`, "snapshot");
+            }
+            // Cap sleep to remaining time + jitter
+            const remaining = deadline - Date.now();
+            const jitter = pollInterval * 200 * (Math.random() - 0.5); // ±10%
+            const delay = Math.min(pollInterval * 1000 + jitter, remaining);
+            if (delay > 0) {
+                await sleepWithSignal(delay, signal);
+            }
+        }
+        throw new errors_js_1.LangSmithResourceTimeoutError(`Snapshot '${snapshotId}' did not become ready within ${timeout}s`, "snapshot", lastStatus);
+    }
 }
 exports.SandboxClient = SandboxClient;

package/dist/experimental/sandbox/client.d.ts

@@ -1,7 +1,7 @@
 /**
  * Main SandboxClient class for interacting with the sandbox server API.
  */
-import type { CreatePoolOptions, CreateSandboxOptions, CreateTemplateOptions, CreateVolumeOptions, Pool, ResourceStatus, SandboxClientConfig, SandboxTemplate, UpdatePoolOptions, UpdateSandboxOptions, UpdateTemplateOptions, UpdateVolumeOptions, Volume, WaitForSandboxOptions } from "./types.js";
+import type { CaptureSnapshotOptions, CreatePoolOptions, CreateSandboxOptions, CreateSnapshotOptions, CreateTemplateOptions, CreateVolumeOptions, Pool, ResourceStatus, SandboxClientConfig, SandboxTemplate, Snapshot, StartSandboxOptions, UpdatePoolOptions, UpdateSandboxOptions, UpdateTemplateOptions, UpdateVolumeOptions, Volume, WaitForSandboxOptions, WaitForSnapshotOptions } from "./types.js";
 import { Sandbox } from "./sandbox.js";
 /**
  * Client for interacting with the Sandbox Server API.
@@ -206,7 +206,7 @@ export declare class SandboxClient {
      * }
      * ```
      */
-    createSandbox(templateName: string, options?: CreateSandboxOptions): Promise<Sandbox>;
+    createSandbox(templateName?: string, options?: CreateSandboxOptions): Promise<Sandbox>;
     /**
      * Get a Sandbox by name.
      *
@@ -216,7 +216,9 @@ export declare class SandboxClient {
      * @returns Sandbox.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    getSandbox(name: string): Promise<Sandbox>;
+    getSandbox(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Sandbox>;
     /**
      * List all Sandboxes.
      *
@@ -258,7 +260,9 @@ export declare class SandboxClient {
      * @returns ResourceStatus with status and optional status_message.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    getSandboxStatus(name: string): Promise<ResourceStatus>;
+    getSandboxStatus(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ResourceStatus>;
     /**
      * Wait for a sandbox to become ready.
      *
@@ -280,4 +284,70 @@ export declare class SandboxClient {
      * ```
      */
     waitForSandbox(name: string, options?: WaitForSandboxOptions): Promise<Sandbox>;
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * @param name - Sandbox name.
+     * @param options - Options with timeout.
+     * @returns Sandbox in "ready" status.
+     */
+    startSandbox(name: string, options?: StartSandboxOptions): Promise<Sandbox>;
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     *
+     * @param name - Sandbox name.
+     */
+    stopSandbox(name: string): Promise<void>;
+    /**
+     * Build a snapshot from a Docker image.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param name - Snapshot name.
+     * @param dockerImage - Docker image to build from (e.g., "python:3.12-slim").
+     * @param fsCapacityBytes - Filesystem capacity in bytes.
+     * @param options - Additional options (registry credentials, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    createSnapshot(name: string, dockerImage: string, fsCapacityBytes: number, options?: CreateSnapshotOptions): Promise<Snapshot>;
+    /**
+     * Capture a snapshot from a running sandbox.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param sandboxName - Name of the sandbox to capture from.
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    captureSnapshot(sandboxName: string, name: string, options?: CaptureSnapshotOptions): Promise<Snapshot>;
+    /**
+     * Get a snapshot by ID.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @returns Snapshot.
+     */
+    getSnapshot(snapshotId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Snapshot>;
+    /**
+     * List all snapshots.
+     *
+     * @returns List of Snapshots.
+     */
+    listSnapshots(): Promise<Snapshot[]>;
+    /**
+     * Delete a snapshot.
+     *
+     * @param snapshotId - Snapshot UUID.
+     */
+    deleteSnapshot(snapshotId: string): Promise<void>;
+    /**
+     * Poll until a snapshot reaches "ready" or "failed" status.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Snapshot in "ready" status.
+     */
+    waitForSnapshot(snapshotId: string, options?: WaitForSnapshotOptions): Promise<Snapshot>;
 }

package/dist/experimental/sandbox/client.js

@@ -7,6 +7,27 @@ import { AsyncCaller } from "../../utils/async_caller.js";
 import { Sandbox } from "./sandbox.js";
 import { LangSmithResourceCreationError, LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, } from "./errors.js";
 import { handleClientHttpError, handleConflictError, handlePoolError, handleResourceInUseError, handleSandboxCreationError, handleVolumeCreationError, validateTtl, } from "./helpers.js";
+/**
+ * Sleep that can be interrupted by an AbortSignal.
+ * Resolves after `ms` milliseconds or rejects immediately if the signal fires.
+ */
+function sleepWithSignal(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /**
  * Get the default sandbox API endpoint from environment.
  *
@@ -112,6 +133,25 @@ export class SandboxClient {
     getApiKey() {
         return this._apiKey;
     }
+    /**
+     * JSON POST helper. Sends JSON body, checks response status,
+     * and returns the Response for further processing.
+     * Throws on non-ok responses via handleClientHttpError.
+     * Callers can add specific status checks (e.g. 404) before calling this.
+     * @internal
+     */
+    async _postJson(url, body, options) {
+        const response = await this._fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        if (!response.ok) {
+            await handleClientHttpError(response);
+        }
+        return response;
+    }
     // =========================================================================
     // Volume Operations
     // =========================================================================
@@ -537,14 +577,25 @@ export class SandboxClient {
      * ```
      */
     async createSandbox(templateName, options = {}) {
-        const { name, timeout = 30, waitForReady = true, ttlSeconds, idleTtlSeconds, } = options;
+        const { snapshotId, name, timeout = 30, waitForReady = true, ttlSeconds, idleTtlSeconds, vCpus, memBytes, fsCapacityBytes, } = options;
+        if (!templateName && !snapshotId) {
+            throw new Error("Either templateName or snapshotId is required");
+        }
+        if (templateName && snapshotId) {
+            throw new Error("Cannot specify both templateName and snapshotId");
+        }
         validateTtl(ttlSeconds, "ttlSeconds");
         validateTtl(idleTtlSeconds, "idleTtlSeconds");
         const url = `${this._baseUrl}/boxes`;
         const payload = {
-            template_name: templateName,
             wait_for_ready: waitForReady,
         };
+        if (templateName) {
+            payload.template_name = templateName;
+        }
+        if (snapshotId) {
+            payload.snapshot_id = snapshotId;
+        }
         if (waitForReady) {
             payload.timeout = timeout;
         }
@@ -557,6 +608,15 @@ export class SandboxClient {
         if (idleTtlSeconds !== undefined) {
             payload.idle_ttl_seconds = idleTtlSeconds;
         }
+        if (vCpus !== undefined) {
+            payload.vcpus = vCpus;
+        }
+        if (memBytes !== undefined) {
+            payload.mem_bytes = memBytes;
+        }
+        if (fsCapacityBytes !== undefined) {
+            payload.fs_capacity_bytes = fsCapacityBytes;
+        }
         const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
@@ -579,9 +639,9 @@ export class SandboxClient {
      * @returns Sandbox.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    async getSandbox(name) {
+    async getSandbox(name, options) {
         const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
-        const response = await this._fetch(url);
+        const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
                 throw new LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
@@ -676,9 +736,9 @@ export class SandboxClient {
      * @returns ResourceStatus with status and optional status_message.
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
-    async getSandboxStatus(name) {
+    async getSandboxStatus(name, options) {
         const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
-        const response = await this._fetch(url);
+        const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
                 throw new LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
@@ -708,21 +768,182 @@ export class SandboxClient {
      * ```
      */
     async waitForSandbox(name, options = {}) {
-        const { timeout = 120, pollInterval = 1.0 } = options;
+        const { timeout = 120, pollInterval = 1.0, signal } = options;
         const deadline = Date.now() + timeout * 1000;
         let lastStatus = "provisioning";
         while (Date.now() < deadline) {
-            const statusResult = await this.getSandboxStatus(name);
+            signal?.throwIfAborted();
+            const statusResult = await this.getSandboxStatus(name, { signal });
             lastStatus = statusResult.status;
             if (statusResult.status === "ready") {
-                return this.getSandbox(name);
+                return this.getSandbox(name, { signal });
             }
             if (statusResult.status === "failed") {
                 throw new LangSmithResourceCreationError(statusResult.status_message ?? `Sandbox '${name}' creation failed`, "sandbox");
             }
-            // Wait before polling again
-            await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+            // Wait before polling again, capped to remaining time + jitter
+            const remaining = deadline - Date.now();
+            const jitter = pollInterval * 200 * (Math.random() - 0.5); // ±10%
+            const delay = Math.min(pollInterval * 1000 + jitter, remaining);
+            if (delay > 0) {
+                await sleepWithSignal(delay, signal);
+            }
         }
         throw new LangSmithResourceTimeoutError(`Sandbox '${name}' did not become ready within ${timeout}s`, "sandbox", lastStatus);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * @param name - Sandbox name.
+     * @param options - Options with timeout.
+     * @returns Sandbox in "ready" status.
+     */
+    async startSandbox(name, options = {}) {
+        const { timeout = 120, signal } = options;
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/start`;
+        await this._postJson(url, {}, { signal });
+        return this.waitForSandbox(name, { timeout, signal });
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     *
+     * @param name - Sandbox name.
+     */
+    async stopSandbox(name) {
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/stop`;
+        await this._postJson(url, {});
+    }
+    // =========================================================================
+    // Snapshot Operations
+    // =========================================================================
+    /**
+     * Build a snapshot from a Docker image.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param name - Snapshot name.
+     * @param dockerImage - Docker image to build from (e.g., "python:3.12-slim").
+     * @param fsCapacityBytes - Filesystem capacity in bytes.
+     * @param options - Additional options (registry credentials, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
+        const { registryId, registryUrl, registryUsername, registryPassword, timeout = 60, signal, } = options;
+        const url = `${this._baseUrl}/snapshots`;
+        const payload = {
+            name,
+            docker_image: dockerImage,
+            fs_capacity_bytes: fsCapacityBytes,
+        };
+        if (registryId !== undefined) {
+            payload.registry_id = registryId;
+        }
+        if (registryUrl !== undefined) {
+            payload.registry_url = registryUrl;
+        }
+        if (registryUsername !== undefined) {
+            payload.registry_username = registryUsername;
+        }
+        if (registryPassword !== undefined) {
+            payload.registry_password = registryPassword;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const snapshot = (await response.json());
+        return this.waitForSnapshot(snapshot.id, { timeout, signal });
+    }
+    /**
+     * Capture a snapshot from a running sandbox.
+     *
+     * Blocks until the snapshot is ready (polls with 2s interval).
+     *
+     * @param sandboxName - Name of the sandbox to capture from.
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(sandboxName, name, options = {}) {
+        const { checkpoint, timeout = 60, signal } = options;
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(sandboxName)}/snapshot`;
+        const payload = { name };
+        if (checkpoint !== undefined) {
+            payload.checkpoint = checkpoint;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const snapshot = (await response.json());
+        return this.waitForSnapshot(snapshot.id, { timeout, signal });
+    }
+    /**
+     * Get a snapshot by ID.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @returns Snapshot.
+     */
+    async getSnapshot(snapshotId, options) {
+        const url = `${this._baseUrl}/snapshots/${encodeURIComponent(snapshotId)}`;
+        const response = await this._fetch(url, { signal: options?.signal });
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new LangSmithResourceNotFoundError(`Snapshot '${snapshotId}' not found`, "snapshot");
+            }
+            await handleClientHttpError(response);
+        }
+        return (await response.json());
+    }
+    /**
+     * List all snapshots.
+     *
+     * @returns List of Snapshots.
+     */
+    async listSnapshots() {
+        const url = `${this._baseUrl}/snapshots`;
+        const response = await this._fetch(url);
+        if (!response.ok) {
+            await handleClientHttpError(response);
+        }
+        const data = await response.json();
+        return (data.snapshots ?? []);
+    }
+    /**
+     * Delete a snapshot.
+     *
+     * @param snapshotId - Snapshot UUID.
+     */
+    async deleteSnapshot(snapshotId) {
+        const url = `${this._baseUrl}/snapshots/${encodeURIComponent(snapshotId)}`;
+        const response = await this._fetch(url, { method: "DELETE" });
+        if (!response.ok) {
+            await handleClientHttpError(response);
+        }
+    }
+    /**
+     * Poll until a snapshot reaches "ready" or "failed" status.
+     *
+     * @param snapshotId - Snapshot UUID.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Snapshot in "ready" status.
+     */
+    async waitForSnapshot(snapshotId, options = {}) {
+        const { timeout = 300, pollInterval = 2.0, signal } = options;
+        const deadline = Date.now() + timeout * 1000;
+        let lastStatus = "building";
+        while (Date.now() < deadline) {
+            signal?.throwIfAborted();
+            const snapshot = await this.getSnapshot(snapshotId, { signal });
+            lastStatus = snapshot.status;
+            if (snapshot.status === "ready") {
+                return snapshot;
+            }
+            if (snapshot.status === "failed") {
+                throw new LangSmithResourceCreationError(snapshot.status_message ?? `Snapshot '${snapshotId}' build failed`, "snapshot");
+            }
+            // Cap sleep to remaining time + jitter
+            const remaining = deadline - Date.now();
+            const jitter = pollInterval * 200 * (Math.random() - 0.5); // ±10%
+            const delay = Math.min(pollInterval * 1000 + jitter, remaining);
+            if (delay > 0) {
+                await sleepWithSignal(delay, signal);
+            }
+        }
+        throw new LangSmithResourceTimeoutError(`Snapshot '${snapshotId}' did not become ready within ${timeout}s`, "snapshot", lastStatus);
+    }
 }

package/dist/experimental/sandbox/index.d.ts

@@ -25,5 +25,5 @@
 export { SandboxClient } from "./client.js";
 export { Sandbox } from "./sandbox.js";
 export { CommandHandle } from "./command_handle.js";
-export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceSpec, ResourceStatus, VolumeMountSpec, Volume, SandboxTemplate, Pool, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, CreateVolumeOptions, CreateTemplateOptions, UpdateTemplateOptions, CreatePoolOptions, UpdateVolumeOptions, UpdatePoolOptions, } from "./types.js";
+export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceSpec, ResourceStatus, Snapshot, VolumeMountSpec, Volume, SandboxTemplate, Pool, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, CreateSnapshotOptions, CaptureSnapshotOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, CreateVolumeOptions, CreateTemplateOptions, UpdateTemplateOptions, CreatePoolOptions, UpdateVolumeOptions, UpdatePoolOptions, } from "./types.js";
 export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/experimental/sandbox/sandbox.cjs

@@ -52,7 +52,7 @@ class Sandbox {
             writable: true,
             value: void 0
         });
-        /** Provisioning status ("provisioning", "ready", "failed"). */
+        /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
         Object.defineProperty(this, "status", {
             enumerable: true,
             configurable: true,
@@ -108,6 +108,34 @@ class Sandbox {
             writable: true,
             value: void 0
         });
+        /** Snapshot ID used to create this sandbox. */
+        Object.defineProperty(this, "snapshot_id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Number of vCPUs allocated. */
+        Object.defineProperty(this, "vCpus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Memory allocation in bytes. */
+        Object.defineProperty(this, "mem_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Root filesystem capacity in bytes. */
+        Object.defineProperty(this, "fs_capacity_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "_client", {
             enumerable: true,
             configurable: true,
@@ -125,6 +153,10 @@ class Sandbox {
         this.ttl_seconds = data.ttl_seconds;
         this.idle_ttl_seconds = data.idle_ttl_seconds;
         this.expires_at = data.expires_at;
+        this.snapshot_id = data.snapshot_id;
+        this.vCpus = data.vcpus;
+        this.mem_bytes = data.mem_bytes;
+        this.fs_capacity_bytes = data.fs_capacity_bytes;
         this._client = client;
     }
     /**
@@ -339,5 +371,35 @@ class Sandbox {
     async delete() {
         await this._client.deleteSandbox(this.name);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * Updates this sandbox's status and dataplane_url in place.
+     *
+     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
+     */
+    async start(options = {}) {
+        const refreshed = await this._client.startSandbox(this.name, options);
+        this.status = refreshed.status;
+        this.dataplane_url = refreshed.dataplane_url;
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     */
+    async stop() {
+        await this._client.stopSandbox(this.name);
+        this.status = "stopped";
+        this.dataplane_url = undefined;
+    }
+    /**
+     * Capture a snapshot from this sandbox.
+     *
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(name, options = {}) {
+        return this._client.captureSnapshot(this.name, name, options);
+    }
 }
 exports.Sandbox = Sandbox;

package/dist/experimental/sandbox/sandbox.d.ts

@@ -1,7 +1,7 @@
 /**
  * Sandbox class for interacting with a specific sandbox instance.
  */
-import type { ExecutionResult, RunOptions } from "./types.js";
+import type { CaptureSnapshotOptions, ExecutionResult, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
 import { CommandHandle } from "./command_handle.js";
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -27,11 +27,11 @@ export declare class Sandbox {
     /** Display name (can be updated). */
     readonly name: string;
     /** Name of the template used to create this sandbox. */
-    readonly template_name: string;
+    readonly template_name?: string;
     /** URL for data plane operations (file I/O, command execution). */
-    readonly dataplane_url?: string;
-    /** Provisioning status ("provisioning", "ready", "failed"). */
-    readonly status?: string;
+    dataplane_url?: string;
+    /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
+    status?: string;
     /** Human-readable status message (e.g., error details when failed). */
     readonly status_message?: string;
     /** Unique identifier (UUID). Remains constant even if name changes. */
@@ -46,6 +46,14 @@ export declare class Sandbox {
     readonly idle_ttl_seconds?: number;
     /** Computed expiration timestamp when a TTL is active. */
     readonly expires_at?: string;
+    /** Snapshot ID used to create this sandbox. */
+    readonly snapshot_id?: string;
+    /** Number of vCPUs allocated. */
+    readonly vCpus?: number;
+    /** Memory allocation in bytes. */
+    readonly mem_bytes?: number;
+    /** Root filesystem capacity in bytes. */
+    readonly fs_capacity_bytes?: number;
     private _client;
     /**
      * Validate and return the dataplane URL.
@@ -147,4 +155,24 @@ export declare class Sandbox {
      * ```
      */
     delete(): Promise<void>;
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * Updates this sandbox's status and dataplane_url in place.
+     *
+     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
+     */
+    start(options?: StartSandboxOptions): Promise<void>;
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     */
+    stop(): Promise<void>;
+    /**
+     * Capture a snapshot from this sandbox.
+     *
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    captureSnapshot(name: string, options?: CaptureSnapshotOptions): Promise<Snapshot>;
 }

package/dist/experimental/sandbox/sandbox.js

@@ -49,7 +49,7 @@ export class Sandbox {
             writable: true,
             value: void 0
         });
-        /** Provisioning status ("provisioning", "ready", "failed"). */
+        /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
         Object.defineProperty(this, "status", {
             enumerable: true,
             configurable: true,
@@ -105,6 +105,34 @@ export class Sandbox {
             writable: true,
             value: void 0
         });
+        /** Snapshot ID used to create this sandbox. */
+        Object.defineProperty(this, "snapshot_id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Number of vCPUs allocated. */
+        Object.defineProperty(this, "vCpus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Memory allocation in bytes. */
+        Object.defineProperty(this, "mem_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Root filesystem capacity in bytes. */
+        Object.defineProperty(this, "fs_capacity_bytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "_client", {
             enumerable: true,
             configurable: true,
@@ -122,6 +150,10 @@ export class Sandbox {
         this.ttl_seconds = data.ttl_seconds;
         this.idle_ttl_seconds = data.idle_ttl_seconds;
         this.expires_at = data.expires_at;
+        this.snapshot_id = data.snapshot_id;
+        this.vCpus = data.vcpus;
+        this.mem_bytes = data.mem_bytes;
+        this.fs_capacity_bytes = data.fs_capacity_bytes;
         this._client = client;
     }
     /**
@@ -336,4 +368,34 @@ export class Sandbox {
     async delete() {
         await this._client.deleteSandbox(this.name);
     }
+    /**
+     * Start a stopped sandbox and wait until ready.
+     *
+     * Updates this sandbox's status and dataplane_url in place.
+     *
+     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
+     */
+    async start(options = {}) {
+        const refreshed = await this._client.startSandbox(this.name, options);
+        this.status = refreshed.status;
+        this.dataplane_url = refreshed.dataplane_url;
+    }
+    /**
+     * Stop a running sandbox (preserves sandbox files for later restart).
+     */
+    async stop() {
+        await this._client.stopSandbox(this.name);
+        this.status = "stopped";
+        this.dataplane_url = undefined;
+    }
+    /**
+     * Capture a snapshot from this sandbox.
+     *
+     * @param name - Snapshot name.
+     * @param options - Capture options (checkpoint, timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(name, options = {}) {
+        return this._client.captureSnapshot(this.name, name, options);
+    }
 }

package/dist/experimental/sandbox/types.d.ts

@@ -73,13 +73,35 @@ export interface ResourceStatus {
     /** Human-readable details when failed. */
     status_message?: string;
 }
+/**
+ * Represents a sandbox snapshot.
+ *
+ * Snapshots are built from Docker images or captured from running sandboxes.
+ * They are used to create new sandboxes.
+ */
+export interface Snapshot {
+    id: string;
+    name: string;
+    /** One of "building", "ready", "failed". */
+    status: string;
+    fs_capacity_bytes: number;
+    docker_image?: string;
+    image_digest?: string;
+    source_sandbox_id?: string;
+    status_message?: string;
+    fs_used_bytes?: number;
+    created_by?: string;
+    registry_id?: string;
+    created_at?: string;
+    updated_at?: string;
+}
 /**
  * Data representing a sandbox instance from the API.
  */
 export interface SandboxData {
     id?: string;
     name: string;
-    template_name: string;
+    template_name?: string;
     dataplane_url?: string;
     status?: string;
     status_message?: string;
@@ -91,6 +113,14 @@ export interface SandboxData {
     idle_ttl_seconds?: number;
     /** Computed expiration timestamp when a TTL is active, else omitted/`undefined`. */
     expires_at?: string;
+    /** Snapshot ID used to create this sandbox. */
+    snapshot_id?: string;
+    /** Number of vCPUs allocated. */
+    vcpus?: number;
+    /** Memory allocation in bytes. */
+    mem_bytes?: number;
+    /** Root filesystem capacity in bytes. */
+    fs_capacity_bytes?: number;
 }
 /**
  * Configuration options for the SandboxClient.
@@ -239,6 +269,11 @@ export interface RunOptions {
  * Options for creating a sandbox.
  */
 export interface CreateSandboxOptions {
+    /**
+     * Snapshot ID to boot from.
+     * Mutually exclusive with the `templateName` positional arg.
+     */
+    snapshotId?: string;
     /**
      * Optional sandbox name (auto-generated if not provided).
      */
@@ -264,6 +299,60 @@ export interface CreateSandboxOptions {
      * Must be a multiple of 60, or `0`/`undefined` to disable or omit.
      */
     idleTtlSeconds?: number;
+    /** Number of vCPUs. */
+    vCpus?: number;
+    /** Memory in bytes. */
+    memBytes?: number;
+    /** Root filesystem capacity in bytes. */
+    fsCapacityBytes?: number;
+}
+/**
+ * Options for creating a snapshot from a Docker image.
+ */
+export interface CreateSnapshotOptions {
+    /** Private registry ID (alternative to URL/credentials). */
+    registryId?: string;
+    /** Registry URL for private images. */
+    registryUrl?: string;
+    /** Registry username. */
+    registryUsername?: string;
+    /** Registry password. */
+    registryPassword?: string;
+    /** Timeout in seconds when waiting for ready. Default: 60. */
+    timeout?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Options for capturing a snapshot from a running sandbox.
+ */
+export interface CaptureSnapshotOptions {
+    /** Checkpoint timestamp to use. If omitted, creates a fresh checkpoint. */
+    checkpoint?: string;
+    /** Timeout in seconds when waiting for ready. Default: 60. */
+    timeout?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Options for waiting for a snapshot to become ready.
+ */
+export interface WaitForSnapshotOptions {
+    /** Maximum time in seconds to wait. Default: 300. */
+    timeout?: number;
+    /** Time in seconds between status polls. Default: 2.0. */
+    pollInterval?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Options for starting a stopped sandbox.
+ */
+export interface StartSandboxOptions {
+    /** Timeout in seconds when waiting for ready. Default: 120. */
+    timeout?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }
 /**
  * Options for updating a sandbox (name and/or TTL).
@@ -295,6 +384,8 @@ export interface WaitForSandboxOptions {
      * Default: 1.0.
      */
     pollInterval?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }
 /**
  * Options for creating a volume.

package/dist/index.cjs

@@ -18,4 +18,4 @@ Object.defineProperty(exports, "PromptCache", { enumerable: true, get: function
 Object.defineProperty(exports, "configureGlobalPromptCache", { enumerable: true, get: function () { return index_js_1.configureGlobalPromptCache; } });
 Object.defineProperty(exports, "promptCacheSingleton", { enumerable: true, get: function () { return index_js_1.promptCacheSingleton; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.5.19";
+exports.__version__ = "0.5.20";

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { uuid7, uuid7FromTime } from "./uuid.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
-export declare const __version__ = "0.5.19";
+export declare const __version__ = "0.5.20";

package/dist/index.js

@@ -5,4 +5,4 @@ export { getDefaultProjectName } from "./utils/project.js";
 export { uuid7, uuid7FromTime } from "./uuid.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 // Update using pnpm bump-version
-export const __version__ = "0.5.19";
+export const __version__ = "0.5.20";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.5.19",
+  "version": "0.5.20",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "pnpm@10.33.0",
   "files": [