langsmith 0.5.19 → 0.6.0

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

@@ -1,12 +1,12 @@
 /**
  * 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, CreateSandboxOptions, CreateSnapshotOptions, ListSnapshotsOptions, ResourceStatus, SandboxClientConfig, Snapshot, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, WaitForSnapshotOptions } from "./types.js";
 import { Sandbox } from "./sandbox.js";
 /**
  * Client for interacting with the Sandbox Server API.
  *
- * This client provides a simple interface for managing sandboxes and templates.
+ * This client provides a simple interface for managing sandboxes and snapshots.
  *
  * @example
  * ```typescript
@@ -21,8 +21,13 @@ import { Sandbox } from "./sandbox.js";
  *   apiKey: "your-api-key",
  * });
  *
- * // Create a sandbox and run commands
- * const sandbox = await client.createSandbox("python-sandbox");
+ * // Build a snapshot, then create a sandbox from it
+ * const snapshot = await client.createSnapshot(
+ *   "python",
+ *   "python:3.12-slim",
+ *   1_073_741_824 // 1 GiB
+ * );
+ * const sandbox = await client.createSandbox(snapshot.id);
  * try {
  *   const result = await sandbox.run("python --version");
  *   console.log(result.stdout);
@@ -40,164 +45,37 @@ export declare class SandboxClient {
     private _caller;
     constructor(config?: SandboxClientConfig);
     /**
-     * Create a new persistent volume.
-     *
-     * Creates a persistent storage volume that can be referenced in templates.
-     *
-     * @param name - Volume name.
-     * @param options - Creation options including size and optional timeout.
-     * @returns Created Volume.
-     * @throws SandboxCreationError if volume provisioning fails.
-     * @throws ResourceTimeoutError if volume doesn't become ready within timeout.
-     */
-    createVolume(name: string, options: CreateVolumeOptions): Promise<Volume>;
-    /**
-     * Get a volume by name.
-     *
-     * @param name - Volume name.
-     * @returns Volume.
-     * @throws LangSmithResourceNotFoundError if volume not found.
-     */
-    getVolume(name: string): Promise<Volume>;
-    /**
-     * List all volumes.
-     *
-     * @returns List of Volumes.
-     */
-    listVolumes(): Promise<Volume[]>;
-    /**
-     * Delete a volume.
-     *
-     * @param name - Volume name.
-     * @throws LangSmithResourceNotFoundError if volume not found.
-     * @throws ResourceInUseError if volume is referenced by templates.
-     */
-    deleteVolume(name: string): Promise<void>;
-    /**
-     * Update a volume's name and/or size.
-     *
-     * You can update the display name, size, or both in a single request.
-     * Only storage size increases are allowed (storage backend limitation).
-     *
-     * @param name - Current volume name.
-     * @param options - Update options.
-     * @returns Updated Volume.
-     * @throws LangSmithResourceNotFoundError if volume not found.
-     * @throws ValidationError if storage decrease attempted.
-     * @throws LangSmithResourceNameConflictError if newName is already in use.
-     */
-    updateVolume(name: string, options: UpdateVolumeOptions): Promise<Volume>;
-    /**
-     * Create a new SandboxTemplate.
-     *
-     * Only the container image, resource limits, and volume mounts can be
-     * configured. All other container details are handled by the server.
-     *
-     * @param name - Template name.
-     * @param options - Creation options including image and resource limits.
-     * @returns Created SandboxTemplate.
-     */
-    createTemplate(name: string, options: CreateTemplateOptions): Promise<SandboxTemplate>;
-    /**
-     * Get a SandboxTemplate by name.
-     *
-     * @param name - Template name.
-     * @returns SandboxTemplate.
-     * @throws LangSmithResourceNotFoundError if template not found.
-     */
-    getTemplate(name: string): Promise<SandboxTemplate>;
-    /**
-     * List all SandboxTemplates.
-     *
-     * @returns List of SandboxTemplates.
-     */
-    listTemplates(): Promise<SandboxTemplate[]>;
-    /**
-     * Update a template.
-     *
-     * @param name - Current template name.
-     * @param options - Update options (e.g., newName).
-     * @returns Updated SandboxTemplate.
-     * @throws LangSmithResourceNotFoundError if template not found.
-     * @throws LangSmithResourceNameConflictError if newName is already in use.
-     */
-    updateTemplate(name: string, options: UpdateTemplateOptions): Promise<SandboxTemplate>;
-    /**
-     * Delete a SandboxTemplate.
-     *
-     * @param name - Template name.
-     * @throws LangSmithResourceNotFoundError if template not found.
-     * @throws ResourceInUseError if template is referenced by sandboxes or pools.
-     */
-    deleteTemplate(name: string): Promise<void>;
-    /**
-     * Create a new Sandbox Pool.
-     *
-     * Pools pre-provision sandboxes from a template for faster startup.
-     *
-     * @param name - Pool name (lowercase letters, numbers, hyphens; max 63 chars).
-     * @param options - Creation options including templateName, replicas, and optional timeout.
-     * @returns Created Pool.
-     * @throws LangSmithResourceNotFoundError if template not found.
-     * @throws ValidationError if template has volumes attached.
-     * @throws ResourceAlreadyExistsError if pool with this name already exists.
-     * @throws ResourceTimeoutError if pool doesn't reach ready state within timeout.
-     * @throws QuotaExceededError if organization quota is exceeded.
-     */
-    createPool(name: string, options: CreatePoolOptions): Promise<Pool>;
-    /**
-     * Get a Pool by name.
-     *
-     * @param name - Pool name.
-     * @returns Pool.
-     * @throws LangSmithResourceNotFoundError if pool not found.
-     */
-    getPool(name: string): Promise<Pool>;
-    /**
-     * List all Pools.
-     *
-     * @returns List of Pools.
-     */
-    listPools(): Promise<Pool[]>;
-    /**
-     * Update a Pool's name and/or replica count.
-     *
-     * You can update the display name, replica count, or both.
-     * The template reference cannot be changed after creation.
-     *
-     * @param name - Current pool name.
-     * @param options - Update options.
-     * @returns Updated Pool.
-     * @throws LangSmithResourceNotFoundError if pool not found.
-     * @throws ValidationError if template was deleted.
-     * @throws LangSmithResourceNameConflictError if newName is already in use.
-     * @throws QuotaExceededError if quota exceeded when scaling up.
-     */
-    updatePool(name: string, options: UpdatePoolOptions): Promise<Pool>;
-    /**
-     * Delete a Pool.
-     *
-     * This will terminate all sandboxes in the pool.
-     *
-     * @param name - Pool name.
-     * @throws LangSmithResourceNotFoundError if pool not found.
-     */
-    deletePool(name: string): Promise<void>;
-    /**
-     * Create a new Sandbox.
+     * Create a new Sandbox from a snapshot.
      *
      * Remember to call `sandbox.delete()` when done to clean up resources.
      *
-     * @param templateName - Name of the SandboxTemplate to use.
-     * @param options - Creation options.
+     * Exactly one of `snapshotId` (positional) or `options.snapshotName` must
+     * be provided. When `snapshotName` is used, the server resolves it to a
+     * snapshot owned by the caller's tenant.
+     *
+     * @param snapshotId - ID of the snapshot to boot from. Create one with
+     *   `createSnapshot()` or `captureSnapshot()`, or pass an existing snapshot ID.
+     *   Pass `undefined` when booting by name via `options.snapshotName`.
+     * @param options - Creation options. Use `options.snapshotName` to boot
+     *   by snapshot name instead of ID.
      * @returns Created Sandbox.
      * @throws ResourceTimeoutError if timeout waiting for sandbox to be ready.
      * @throws SandboxCreationError if sandbox creation fails.
-     * @throws LangSmithValidationError if TTL values are invalid.
+     * @throws LangSmithValidationError if TTL values are invalid, or if neither
+     *   (or both) of `snapshotId` / `options.snapshotName` are provided.
      *
      * @example
      * ```typescript
-     * 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);
+     * // Or, resolve by snapshot name:
+     * const sandbox = await client.createSandbox(undefined, {
+     *   snapshotName: "python",
+     * });
      * try {
      *   const result = await sandbox.run("echo hello");
      *   console.log(result.stdout);
@@ -206,7 +84,7 @@ export declare class SandboxClient {
      * }
      * ```
      */
-    createSandbox(templateName: string, options?: CreateSandboxOptions): Promise<Sandbox>;
+    createSandbox(snapshotId?: string, options?: CreateSandboxOptions): Promise<Sandbox>;
     /**
      * Get a Sandbox by name.
      *
@@ -216,7 +94,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 +138,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.
      *
@@ -274,10 +156,107 @@ export declare class SandboxClient {
      *
      * @example
      * ```typescript
-     * const sandbox = await client.createSandbox("python-sandbox", { waitForReady: false });
+     * const sandbox = await client.createSandbox(snapshot.id, { waitForReady: false });
      * // ... do other work ...
      * const readySandbox = await client.waitForSandbox(sandbox.name);
      * ```
      */
     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 (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 snapshots, optionally filtered and paginated server-side.
+     *
+     * The backend always paginates this endpoint. When `limit` is omitted the
+     * server applies a default page size (currently 50), so a single call is
+     * not guaranteed to return every snapshot visible to the tenant. To iterate
+     * through all results, repeat the call with increasing `offset` values (or
+     * an explicit `limit`) until fewer than `limit` snapshots come back.
+     *
+     * @param options - Optional filter/pagination options.
+     *   - `nameContains`: case-insensitive substring match on snapshot name.
+     *   - `limit`: page size; must be between 1 and 500 (inclusive). Defaults
+     *     to 50 server-side when omitted.
+     *   - `offset`: number of snapshots to skip; must be `>= 0`.
+     *
+     *   Values outside those ranges are rejected by the server.
+     * @returns A single page of Snapshots matching the provided filters.
+     *
+     * @example
+     * ```typescript
+     * const firstPage = await client.listSnapshots();
+     * const page = await client.listSnapshots({
+     *   nameContains: "python",
+     *   limit: 100,
+     *   offset: 0,
+     * });
+     * ```
+     */
+    listSnapshots(options?: ListSnapshotsOptions): 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>;
+    /**
+     * Returns a string representation of the SandboxClient instance.
+     * This method is called when the object is converted to a string
+     * or logged, ensuring sensitive information like API keys is not exposed.
+     *
+     * @returns A string representation of the SandboxClient.
+     */
+    toString(): string;
 }