langsmith 0.5.19 → 0.6.0

package/dist/experimental/sandbox/errors.cjs

@@ -165,7 +165,6 @@ exports.LangSmithResourceNameConflictError = LangSmithResourceNameConflictError;
  * - Resource values exceeding server-defined limits (CPU, memory, storage)
  * - Invalid resource units
  * - Invalid name formats
- * - Pool validation failures (e.g., template has volumes)
  */
 class LangSmithValidationError extends LangSmithSandboxError {
     constructor(message, field, details, errorType) {
@@ -224,7 +223,7 @@ class LangSmithResourceCreationError extends LangSmithSandboxError {
     constructor(message, resourceType, errorType) {
         super(message);
         /**
-         * Type of resource that failed (e.g., "sandbox", "volume").
+         * Type of resource that failed (e.g., "sandbox", "snapshot").
          */
         Object.defineProperty(this, "resourceType", {
             enumerable: true,

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

@@ -75,7 +75,6 @@ export declare class LangSmithResourceNameConflictError extends LangSmithSandbox
  * - Resource values exceeding server-defined limits (CPU, memory, storage)
  * - Invalid resource units
  * - Invalid name formats
- * - Pool validation failures (e.g., template has volumes)
  */
 export declare class LangSmithValidationError extends LangSmithSandboxError {
     field?: string;
@@ -97,7 +96,7 @@ export declare class LangSmithQuotaExceededError extends LangSmithSandboxError {
  */
 export declare class LangSmithResourceCreationError extends LangSmithSandboxError {
     /**
-     * Type of resource that failed (e.g., "sandbox", "volume").
+     * Type of resource that failed (e.g., "sandbox", "snapshot").
      */
     resourceType?: string;
     /**

package/dist/experimental/sandbox/errors.js

@@ -153,7 +153,6 @@ export class LangSmithResourceNameConflictError extends LangSmithSandboxError {
  * - Resource values exceeding server-defined limits (CPU, memory, storage)
  * - Invalid resource units
  * - Invalid name formats
- * - Pool validation failures (e.g., template has volumes)
  */
 export class LangSmithValidationError extends LangSmithSandboxError {
     constructor(message, field, details, errorType) {
@@ -210,7 +209,7 @@ export class LangSmithResourceCreationError extends LangSmithSandboxError {
     constructor(message, resourceType, errorType) {
         super(message);
         /**
-         * Type of resource that failed (e.g., "sandbox", "volume").
+         * Type of resource that failed (e.g., "sandbox", "snapshot").
          */
         Object.defineProperty(this, "resourceType", {
             enumerable: true,

package/dist/experimental/sandbox/helpers.cjs

@@ -11,12 +11,8 @@ exports.parseErrorResponse = parseErrorResponse;
 exports.parseValidationError = parseValidationError;
 exports.extractQuotaType = extractQuotaType;
 exports.handleSandboxCreationError = handleSandboxCreationError;
-exports.handleVolumeCreationError = handleVolumeCreationError;
-exports.handlePoolError = handlePoolError;
 exports.handleClientHttpError = handleClientHttpError;
 exports.handleSandboxHttpError = handleSandboxHttpError;
-exports.handleConflictError = handleConflictError;
-exports.handleResourceInUseError = handleResourceInUseError;
 const errors_js_1 = require("./errors.cjs");
 // =============================================================================
 // Input validation
@@ -115,11 +111,6 @@ function extractQuotaType(message) {
     else if (messageLower.includes("memory")) {
         return "memory";
     }
-    // Check for volume count quota
-    else if (messageLower.includes("volume") &&
-        (messageLower.includes("count") || messageLower.includes("limit"))) {
-        return "volume_count";
-    }
     else if (messageLower.includes("storage")) {
         return "storage";
     }
@@ -140,6 +131,7 @@ function extractQuotaType(message) {
  */
 async function handleSandboxCreationError(response) {
     const status = response.status;
+    const clonedResponse = response.clone();
     const data = await parseErrorResponse(response);
     if (status === 408) {
         // Timeout - include the message which contains last known status
@@ -147,7 +139,6 @@ async function handleSandboxCreationError(response) {
     }
     else if (status === 422) {
         // Check if this is a Pydantic validation error (bad input) vs creation error
-        const clonedResponse = response.clone();
         const details = await parseValidationError(clonedResponse);
         if (details.length > 0 && details.some((d) => d.type === "value_error")) {
             // Pydantic validation error (bad input - exceeds server limits)
@@ -168,86 +159,20 @@ async function handleSandboxCreationError(response) {
         // Service Unavailable - scheduling failed
         throw new errors_js_1.LangSmithSandboxCreationError(data.message, data.errorType || "Unschedulable");
     }
-    // Fall through to generic handling
-    return handleClientHttpError(response);
-}
-/**
- * Handle HTTP errors specific to volume creation.
- *
- * Maps API error responses to specific exception types:
- * - 429: LangSmithQuotaExceededError (org limits exceeded)
- * - 503: LangSmithSandboxCreationError (provisioning failed)
- * - 504: LangSmithResourceTimeoutError (volume didn't become ready in time)
- * - Other: Falls through to generic error handling
- */
-async function handleVolumeCreationError(response) {
-    const status = response.status;
-    const data = await parseErrorResponse(response);
-    if (status === 429) {
-        // Organization quota exceeded - extract type or default to volume_count
-        const quotaType = extractQuotaType(data.message) ?? "unknown";
-        throw new errors_js_1.LangSmithQuotaExceededError(data.message, quotaType);
-    }
-    else if (status === 503) {
-        // Provisioning failed (invalid storage class, quota exceeded)
-        throw new errors_js_1.LangSmithSandboxCreationError(data.message, "VolumeProvisioning");
-    }
-    else if (status === 504) {
-        // Timeout - volume didn't become ready in time
-        throw new errors_js_1.LangSmithResourceTimeoutError(data.message, "volume");
-    }
-    // Fall through to generic handling
-    return handleClientHttpError(response);
-}
-/**
- * Handle HTTP errors specific to pool creation/update.
- *
- * Maps API error responses to specific exception types:
- * - 400: LangSmithResourceNotFoundError or LangSmithValidationError (template has volumes)
- * - 409: LangSmithResourceAlreadyExistsError
- * - 429: LangSmithQuotaExceededError (org limits exceeded)
- * - 504: LangSmithResourceTimeoutError (timeout waiting for ready replicas)
- * - Other: Falls through to generic error handling
- */
-async function handlePoolError(response) {
-    const status = response.status;
-    const data = await parseErrorResponse(response);
-    const errorType = data.errorType;
-    if (status === 400) {
-        // Check the error type to determine the specific exception
-        if (errorType === "TemplateNotFound") {
-            throw new errors_js_1.LangSmithResourceNotFoundError(data.message, "template");
-        }
-        else if (errorType === "LangSmithValidationError") {
-            // Template has volumes attached
-            throw new errors_js_1.LangSmithValidationError(data.message, undefined, undefined, errorType);
-        }
-        // Generic bad request - fall through to generic handling
-    }
-    else if (status === 409) {
-        // Pool already exists
-        throw new errors_js_1.LangSmithResourceAlreadyExistsError(data.message, "pool");
-    }
-    else if (status === 429) {
-        // Organization quota exceeded - extract type or default to pool_count
-        const quotaType = extractQuotaType(data.message) ?? "unknown";
-        throw new errors_js_1.LangSmithQuotaExceededError(data.message, quotaType);
-    }
-    else if (status === 504) {
-        // Timeout waiting for pool to be ready
-        throw new errors_js_1.LangSmithResourceTimeoutError(data.message, "pool");
-    }
-    // Fall through to generic handling
-    return handleClientHttpError(response);
+    // Fall through to generic handling — pass clone since body is already consumed
+    return handleClientHttpError(clonedResponse);
 }
 /**
  * Handle HTTP errors and raise appropriate exceptions (for client operations).
  */
 async function handleClientHttpError(response) {
+    const status = response.status;
+    // Only clone when we need to read the body twice (status 422 reads it again
+    // for structured validation details after parseErrorResponse consumes it).
+    const clonedResponse = status === 422 ? response.clone() : null;
     const data = await parseErrorResponse(response);
     const message = data.message;
     const errorType = data.errorType;
-    const status = response.status;
     if (status === 401 || status === 403) {
         throw new errors_js_1.LangSmithSandboxAuthenticationError(message);
     }
@@ -255,8 +180,7 @@ async function handleClientHttpError(response) {
         throw new errors_js_1.LangSmithResourceNotFoundError(message);
     }
     // Handle validation errors (invalid resource values, formats, etc.)
-    if (status === 422) {
-        const clonedResponse = response.clone();
+    if (status === 422 && clonedResponse) {
         const details = await parseValidationError(clonedResponse);
         const field = details[0]?.loc?.slice(-1)[0];
         throw new errors_js_1.LangSmithValidationError(message, field, details);
@@ -321,17 +245,3 @@ async function handleSandboxHttpError(response) {
     }
     throw new errors_js_1.LangSmithSandboxError(message);
 }
-/**
- * Handle 409 Conflict errors for resource name conflicts.
- */
-async function handleConflictError(response, resourceType) {
-    const data = await parseErrorResponse(response);
-    throw new errors_js_1.LangSmithResourceNameConflictError(data.message, resourceType);
-}
-/**
- * Handle 409 Conflict errors for resources in use.
- */
-async function handleResourceInUseError(response, resourceType) {
-    const data = await parseErrorResponse(response);
-    throw new errors_js_1.LangSmithResourceInUseError(data.message, resourceType);
-}

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

@@ -49,27 +49,6 @@ export declare function extractQuotaType(message: string): string | undefined;
  * - Other: Falls through to generic error handling
  */
 export declare function handleSandboxCreationError(response: Response): Promise<never>;
-/**
- * Handle HTTP errors specific to volume creation.
- *
- * Maps API error responses to specific exception types:
- * - 429: LangSmithQuotaExceededError (org limits exceeded)
- * - 503: LangSmithSandboxCreationError (provisioning failed)
- * - 504: LangSmithResourceTimeoutError (volume didn't become ready in time)
- * - Other: Falls through to generic error handling
- */
-export declare function handleVolumeCreationError(response: Response): Promise<never>;
-/**
- * Handle HTTP errors specific to pool creation/update.
- *
- * Maps API error responses to specific exception types:
- * - 400: LangSmithResourceNotFoundError or LangSmithValidationError (template has volumes)
- * - 409: LangSmithResourceAlreadyExistsError
- * - 429: LangSmithQuotaExceededError (org limits exceeded)
- * - 504: LangSmithResourceTimeoutError (timeout waiting for ready replicas)
- * - Other: Falls through to generic error handling
- */
-export declare function handlePoolError(response: Response): Promise<never>;
 /**
  * Handle HTTP errors and raise appropriate exceptions (for client operations).
  */
@@ -87,12 +66,4 @@ export declare function handleClientHttpError(response: Response): Promise<never
  * - 403 -> LangSmithSandboxOperationError (permission denied)
  */
 export declare function handleSandboxHttpError(response: Response): Promise<never>;
-/**
- * Handle 409 Conflict errors for resource name conflicts.
- */
-export declare function handleConflictError(response: Response, resourceType: string): Promise<never>;
-/**
- * Handle 409 Conflict errors for resources in use.
- */
-export declare function handleResourceInUseError(response: Response, resourceType: string): Promise<never>;
 export {};

package/dist/experimental/sandbox/helpers.js

@@ -4,7 +4,7 @@
  * These functions are used to parse error responses and raise appropriate
  * exceptions. They contain no I/O operations.
  */
-import { LangSmithQuotaExceededError, LangSmithResourceAlreadyExistsError, LangSmithResourceInUseError, LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxError, LangSmithSandboxConnectionError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithValidationError, } from "./errors.js";
+import { LangSmithQuotaExceededError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxError, LangSmithSandboxConnectionError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithValidationError, } from "./errors.js";
 // =============================================================================
 // Input validation
 // =============================================================================
@@ -102,11 +102,6 @@ export function extractQuotaType(message) {
     else if (messageLower.includes("memory")) {
         return "memory";
     }
-    // Check for volume count quota
-    else if (messageLower.includes("volume") &&
-        (messageLower.includes("count") || messageLower.includes("limit"))) {
-        return "volume_count";
-    }
     else if (messageLower.includes("storage")) {
         return "storage";
     }
@@ -127,6 +122,7 @@ export function extractQuotaType(message) {
  */
 export async function handleSandboxCreationError(response) {
     const status = response.status;
+    const clonedResponse = response.clone();
     const data = await parseErrorResponse(response);
     if (status === 408) {
         // Timeout - include the message which contains last known status
@@ -134,7 +130,6 @@ export async function handleSandboxCreationError(response) {
     }
     else if (status === 422) {
         // Check if this is a Pydantic validation error (bad input) vs creation error
-        const clonedResponse = response.clone();
         const details = await parseValidationError(clonedResponse);
         if (details.length > 0 && details.some((d) => d.type === "value_error")) {
             // Pydantic validation error (bad input - exceeds server limits)
@@ -155,86 +150,20 @@ export async function handleSandboxCreationError(response) {
         // Service Unavailable - scheduling failed
         throw new LangSmithSandboxCreationError(data.message, data.errorType || "Unschedulable");
     }
-    // Fall through to generic handling
-    return handleClientHttpError(response);
-}
-/**
- * Handle HTTP errors specific to volume creation.
- *
- * Maps API error responses to specific exception types:
- * - 429: LangSmithQuotaExceededError (org limits exceeded)
- * - 503: LangSmithSandboxCreationError (provisioning failed)
- * - 504: LangSmithResourceTimeoutError (volume didn't become ready in time)
- * - Other: Falls through to generic error handling
- */
-export async function handleVolumeCreationError(response) {
-    const status = response.status;
-    const data = await parseErrorResponse(response);
-    if (status === 429) {
-        // Organization quota exceeded - extract type or default to volume_count
-        const quotaType = extractQuotaType(data.message) ?? "unknown";
-        throw new LangSmithQuotaExceededError(data.message, quotaType);
-    }
-    else if (status === 503) {
-        // Provisioning failed (invalid storage class, quota exceeded)
-        throw new LangSmithSandboxCreationError(data.message, "VolumeProvisioning");
-    }
-    else if (status === 504) {
-        // Timeout - volume didn't become ready in time
-        throw new LangSmithResourceTimeoutError(data.message, "volume");
-    }
-    // Fall through to generic handling
-    return handleClientHttpError(response);
-}
-/**
- * Handle HTTP errors specific to pool creation/update.
- *
- * Maps API error responses to specific exception types:
- * - 400: LangSmithResourceNotFoundError or LangSmithValidationError (template has volumes)
- * - 409: LangSmithResourceAlreadyExistsError
- * - 429: LangSmithQuotaExceededError (org limits exceeded)
- * - 504: LangSmithResourceTimeoutError (timeout waiting for ready replicas)
- * - Other: Falls through to generic error handling
- */
-export async function handlePoolError(response) {
-    const status = response.status;
-    const data = await parseErrorResponse(response);
-    const errorType = data.errorType;
-    if (status === 400) {
-        // Check the error type to determine the specific exception
-        if (errorType === "TemplateNotFound") {
-            throw new LangSmithResourceNotFoundError(data.message, "template");
-        }
-        else if (errorType === "LangSmithValidationError") {
-            // Template has volumes attached
-            throw new LangSmithValidationError(data.message, undefined, undefined, errorType);
-        }
-        // Generic bad request - fall through to generic handling
-    }
-    else if (status === 409) {
-        // Pool already exists
-        throw new LangSmithResourceAlreadyExistsError(data.message, "pool");
-    }
-    else if (status === 429) {
-        // Organization quota exceeded - extract type or default to pool_count
-        const quotaType = extractQuotaType(data.message) ?? "unknown";
-        throw new LangSmithQuotaExceededError(data.message, quotaType);
-    }
-    else if (status === 504) {
-        // Timeout waiting for pool to be ready
-        throw new LangSmithResourceTimeoutError(data.message, "pool");
-    }
-    // Fall through to generic handling
-    return handleClientHttpError(response);
+    // Fall through to generic handling — pass clone since body is already consumed
+    return handleClientHttpError(clonedResponse);
 }
 /**
  * Handle HTTP errors and raise appropriate exceptions (for client operations).
  */
 export async function handleClientHttpError(response) {
+    const status = response.status;
+    // Only clone when we need to read the body twice (status 422 reads it again
+    // for structured validation details after parseErrorResponse consumes it).
+    const clonedResponse = status === 422 ? response.clone() : null;
     const data = await parseErrorResponse(response);
     const message = data.message;
     const errorType = data.errorType;
-    const status = response.status;
     if (status === 401 || status === 403) {
         throw new LangSmithSandboxAuthenticationError(message);
     }
@@ -242,8 +171,7 @@ export async function handleClientHttpError(response) {
         throw new LangSmithResourceNotFoundError(message);
     }
     // Handle validation errors (invalid resource values, formats, etc.)
-    if (status === 422) {
-        const clonedResponse = response.clone();
+    if (status === 422 && clonedResponse) {
         const details = await parseValidationError(clonedResponse);
         const field = details[0]?.loc?.slice(-1)[0];
         throw new LangSmithValidationError(message, field, details);
@@ -308,17 +236,3 @@ export async function handleSandboxHttpError(response) {
     }
     throw new LangSmithSandboxError(message);
 }
-/**
- * Handle 409 Conflict errors for resource name conflicts.
- */
-export async function handleConflictError(response, resourceType) {
-    const data = await parseErrorResponse(response);
-    throw new LangSmithResourceNameConflictError(data.message, resourceType);
-}
-/**
- * Handle 409 Conflict errors for resources in use.
- */
-export async function handleResourceInUseError(response, resourceType) {
-    const data = await parseErrorResponse(response);
-    throw new LangSmithResourceInUseError(data.message, resourceType);
-}

package/dist/experimental/sandbox/index.cjs

@@ -12,7 +12,12 @@
  * // Uses LANGSMITH_ENDPOINT and LANGSMITH_API_KEY from environment
  * const client = new SandboxClient();
  *
- * const sandbox = await client.createSandbox("python-sandbox");
+ * const snapshot = await client.createSnapshot(
+ *   "python",
+ *   "python:3.12-slim",
+ *   1_073_741_824
+ * );
+ * const sandbox = await client.createSandbox(snapshot.id);
  * try {
  *   const result = await sandbox.run("python --version");
  *   console.log(result.stdout);

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

@@ -11,7 +11,12 @@
  * // Uses LANGSMITH_ENDPOINT and LANGSMITH_API_KEY from environment
  * const client = new SandboxClient();
  *
- * const sandbox = await client.createSandbox("python-sandbox");
+ * const snapshot = await client.createSnapshot(
+ *   "python",
+ *   "python:3.12-slim",
+ *   1_073_741_824
+ * );
+ * const sandbox = await client.createSandbox(snapshot.id);
  * try {
  *   const result = await sandbox.run("python --version");
  *   console.log(result.stdout);
@@ -25,5 +30,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, ResourceStatus, Snapshot, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, SandboxAccessControl, SandboxProxyConfig, CreateSnapshotOptions, CaptureSnapshotOptions, ListSnapshotsOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, } 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/index.js

@@ -11,7 +11,12 @@
  * // Uses LANGSMITH_ENDPOINT and LANGSMITH_API_KEY from environment
  * const client = new SandboxClient();
  *
- * const sandbox = await client.createSandbox("python-sandbox");
+ * const snapshot = await client.createSnapshot(
+ *   "python",
+ *   "python:3.12-slim",
+ *   1_073_741_824
+ * );
+ * const sandbox = await client.createSandbox(snapshot.id);
  * try {
  *   const result = await sandbox.run("python --version");
  *   console.log(result.stdout);

package/dist/experimental/sandbox/sandbox.cjs

@@ -17,7 +17,7 @@ const ws_execute_js_1 = require("./ws_execute.cjs");
  *
  * @example
  * ```typescript
- * const sandbox = await client.createSandbox("python-sandbox");
+ * const sandbox = await client.createSandbox(snapshot.id);
  * try {
  *   const result = await sandbox.run("python --version");
  *   console.log(result.stdout);
@@ -38,13 +38,6 @@ class Sandbox {
             writable: true,
             value: void 0
         });
-        /** Name of the template used to create this sandbox. */
-        Object.defineProperty(this, "template_name", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         /** URL for data plane operations (file I/O, command execution). */
         Object.defineProperty(this, "dataplane_url", {
             enumerable: true,
@@ -52,7 +45,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,
@@ -94,7 +87,11 @@ class Sandbox {
             writable: true,
             value: void 0
         });
-        /** Idle timeout TTL in seconds (`0` means disabled). */
+        /**
+         * Idle timeout TTL in seconds (`0` means disabled).
+         * New sandboxes receive a server-side default of `600` seconds (10 minutes)
+         * when the caller did not set `idleTtlSeconds` explicitly.
+         */
         Object.defineProperty(this, "idle_ttl_seconds", {
             enumerable: true,
             configurable: true,
@@ -108,6 +105,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,
@@ -115,7 +140,6 @@ class Sandbox {
             value: void 0
         });
         this.name = data.name;
-        this.template_name = data.template_name;
         this.dataplane_url = data.dataplane_url;
         this.status = data.status;
         this.status_message = data.status_message;
@@ -125,6 +149,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;
     }
     /**
@@ -177,7 +205,7 @@ class Sandbox {
         catch (e) {
             // Fall back to HTTP on connection errors or missing ws package
             const name = e != null && typeof e === "object" ? e.name : "";
-            const message = e != null && typeof e === "object" ? e.message ?? "" : "";
+            const message = e != null && typeof e === "object" ? (e.message ?? "") : "";
             if (name === "LangSmithSandboxConnectionError" ||
                 name === "LangSmithSandboxServerReloadError" ||
                 message.includes("'ws' package")) {
@@ -328,7 +356,7 @@ class Sandbox {
      *
      * @example
      * ```typescript
-     * const sandbox = await client.createSandbox("python-sandbox");
+     * const sandbox = await client.createSandbox(snapshot.id);
      * try {
      *   await sandbox.run("echo hello");
      * } finally {
@@ -339,5 +367,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 (timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    async captureSnapshot(name, options = {}) {
+        return this._client.captureSnapshot(this.name, name, options);
+    }
 }
 exports.Sandbox = Sandbox;