langsmith 0.5.19 → 0.6.0

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.
@@ -12,7 +12,7 @@ import { CommandHandle } from "./command_handle.js";
  *
  * @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);
@@ -26,12 +26,10 @@ import { CommandHandle } from "./command_handle.js";
 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;
     /** 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. */
@@ -42,10 +40,22 @@ export declare class Sandbox {
     readonly updated_at?: string;
     /** Maximum lifetime TTL in seconds (`0` means disabled). */
     readonly ttl_seconds?: number;
-    /** 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.
+     */
     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.
@@ -138,7 +148,7 @@ export declare 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 {
@@ -147,4 +157,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 (timeout).
+     * @returns Snapshot in "ready" status.
+     */
+    captureSnapshot(name: string, options?: CaptureSnapshotOptions): Promise<Snapshot>;
 }

package/dist/experimental/sandbox/sandbox.js

@@ -14,7 +14,7 @@ import { reconnectWsStream, runWsStream } from "./ws_execute.js";
  *
  * @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);
@@ -35,13 +35,6 @@ export 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,
@@ -49,7 +42,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,
@@ -91,7 +84,11 @@ export 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,
@@ -105,6 +102,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,
@@ -112,7 +137,6 @@ export 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;
@@ -122,6 +146,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;
     }
     /**
@@ -174,7 +202,7 @@ export 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")) {
@@ -325,7 +353,7 @@ export 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 {
@@ -336,4 +364,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 (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

@@ -12,66 +12,35 @@ export interface ExecutionResult {
     exit_code: number;
 }
 /**
- * Resource specification for a sandbox.
- */
-export interface ResourceSpec {
-    cpu?: string;
-    memory?: string;
-    storage?: string;
-}
-/**
- * Specification for mounting a volume in a sandbox template.
- */
-export interface VolumeMountSpec {
-    volume_name: string;
-    mount_path: string;
-}
-/**
- * Represents a persistent volume.
- */
-export interface Volume {
-    id?: string;
-    name: string;
-    size: string;
-    storage_class: string;
-    created_at?: string;
-    updated_at?: string;
-}
-/**
- * Represents a SandboxTemplate.
- *
- * Templates define the image, resource limits, and volume mounts for sandboxes.
+ * Lightweight provisioning status for any async-created resource.
  */
-export interface SandboxTemplate {
-    id?: string;
-    name: string;
-    image: string;
-    resources: ResourceSpec;
-    volume_mounts?: VolumeMountSpec[];
-    created_at?: string;
-    updated_at?: string;
+export interface ResourceStatus {
+    /** One of "provisioning", "ready", "failed". */
+    status: string;
+    /** Human-readable details when failed. */
+    status_message?: string;
 }
 /**
- * Represents a Sandbox Pool for pre-provisioned sandboxes.
+ * Represents a sandbox snapshot.
  *
- * Pools pre-provision sandboxes from a template for faster startup.
+ * Snapshots are built from Docker images or captured from running sandboxes.
+ * They are used to create new sandboxes.
  */
-export interface Pool {
-    id?: string;
+export interface Snapshot {
+    id: string;
     name: string;
-    template_name: string;
-    replicas: number;
-    created_at?: string;
-    updated_at?: string;
-}
-/**
- * Lightweight provisioning status for any async-created resource.
- */
-export interface ResourceStatus {
-    /** One of "provisioning", "ready", "failed". */
+    /** One of "building", "ready", "failed". */
     status: string;
-    /** Human-readable details when failed. */
+    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.
@@ -79,7 +48,6 @@ export interface ResourceStatus {
 export interface SandboxData {
     id?: string;
     name: string;
-    template_name: string;
     dataplane_url?: string;
     status?: string;
     status_message?: string;
@@ -91,6 +59,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.
@@ -235,10 +211,43 @@ export interface RunOptions {
      */
     pty?: boolean;
 }
+/**
+ * Network access-control rules for a sandbox's proxy sidecar.
+ *
+ * Supported pattern types: exact domains, globs (e.g. `*.example.com`),
+ * IPs, CIDR ranges (e.g. `10.0.0.0/8`), and regex (`~pattern`).
+ *
+ * Only one of `allow_list` and `deny_list` may be populated.
+ */
+export interface SandboxAccessControl {
+    /** Hosts the sandbox is allowed to reach. */
+    allow_list?: string[];
+    /** Hosts the sandbox is blocked from reaching. */
+    deny_list?: string[];
+}
+/**
+ * Full proxy configuration forwarded to the sandbox server as-is (snake_case
+ * so it's wire-compatible with the backend). Mirrors the server's
+ * `ProxyConfig` type.
+ */
+export interface SandboxProxyConfig {
+    /** Header-injection rules keyed by host pattern. */
+    rules?: unknown[];
+    /** Hosts that bypass the proxy entirely. */
+    no_proxy?: string[];
+    /** Allow/deny list enforced at the proxy sidecar. */
+    access_control?: SandboxAccessControl;
+}
 /**
  * Options for creating a sandbox.
  */
 export interface CreateSandboxOptions {
+    /**
+     * Snapshot name to boot from. Mutually exclusive with the positional
+     * `snapshotId` argument on `createSandbox`; exactly one must be provided.
+     * Resolved server-side to a snapshot owned by the caller's tenant.
+     */
+    snapshotName?: string;
     /**
      * Optional sandbox name (auto-generated if not provided).
      */
@@ -261,128 +270,129 @@ export interface CreateSandboxOptions {
     ttlSeconds?: number;
     /**
      * Idle timeout in seconds. The sandbox is deleted after this much inactivity.
-     * Must be a multiple of 60, or `0`/`undefined` to disable or omit.
-     */
-    idleTtlSeconds?: number;
-}
-/**
- * Options for updating a sandbox (name and/or TTL).
- */
-export interface UpdateSandboxOptions {
-    /** New display name. */
-    newName?: string;
-    /**
-     * Maximum lifetime in seconds from creation. Must be a multiple of 60.
-     * Pass `0` to disable absolute TTL.
-     */
-    ttlSeconds?: number;
-    /**
-     * Idle timeout in seconds. Must be a multiple of 60. Pass `0` to disable.
+     * Must be a multiple of 60. Pass `0` to explicitly disable the idle timeout.
+     * When omitted, the server applies a default of `600` seconds (10 minutes).
      */
     idleTtlSeconds?: number;
+    /** Number of vCPUs. */
+    vCpus?: number;
+    /** Memory in bytes. */
+    memBytes?: number;
+    /** Root filesystem capacity in bytes. */
+    fsCapacityBytes?: number;
+    /**
+     * Per-sandbox proxy configuration. Use
+     * `{ access_control: { allow_list: ["github.com", "*.example.com"] } }`
+     * to restrict outbound HTTPS to a set of host patterns. Forwarded to the
+     * server as-is on the wire.
+     */
+    proxyConfig?: SandboxProxyConfig;
 }
 /**
- * Options for waiting for a sandbox to become ready.
+ * Options for creating a snapshot from a Docker image.
  */
-export interface WaitForSandboxOptions {
-    /**
-     * Maximum time in seconds to wait for the sandbox to become ready.
-     * Default: 120.
-     */
+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;
-    /**
-     * Time in seconds between status polls.
-     * Default: 1.0.
-     */
-    pollInterval?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }
 /**
- * Options for creating a volume.
+ * Options for capturing a snapshot from a running sandbox.
  */
-export interface CreateVolumeOptions {
-    /**
-     * Storage size (e.g., "1Gi", "10Gi").
-     */
-    size: string;
-    /**
-     * Timeout in seconds when waiting for volume to be ready. Default: 60.
-     */
+export interface CaptureSnapshotOptions {
+    /** Timeout in seconds when waiting for ready. Default: 60. */
     timeout?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }
 /**
- * Options for creating a template.
+ * Options for listing snapshots. All fields are optional and independent.
+ *
+ * The backend always paginates: when `limit` is omitted the server applies
+ * a default page size (currently 50), so a single call will not necessarily
+ * return every snapshot visible to the caller's tenant.
  */
-export interface CreateTemplateOptions {
-    /**
-     * Container image (e.g., "python:3.12-slim", "node:20-slim").
-     */
-    image: string;
+export interface ListSnapshotsOptions {
     /**
-     * CPU limit (e.g., "500m", "1", "2"). Default: "500m".
+     * Case-insensitive substring filter applied server-side to snapshot
+     * names.
      */
-    cpu?: string;
+    nameContains?: string;
     /**
-     * Memory limit (e.g., "256Mi", "1Gi"). Default: "512Mi".
+     * Maximum number of snapshots to return for a single request. Must be
+     * between 1 and 500 (inclusive); the server rejects values outside that
+     * range. Defaults to 50 server-side when omitted.
      */
-    memory?: string;
+    limit?: number;
     /**
-     * Ephemeral storage limit (e.g., "1Gi"). Optional.
+     * Number of snapshots to skip before returning results. Must be `>= 0`.
+     * Useful for paginating through large result sets in combination with
+     * `limit`.
      */
-    storage?: string;
-    /**
-     * List of volumes to mount in the sandbox. Optional.
-     */
-    volumeMounts?: VolumeMountSpec[];
+    offset?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }
 /**
- * Options for updating a template.
+ * Options for waiting for a snapshot to become ready.
  */
-export interface UpdateTemplateOptions {
-    /**
-     * New display name (optional).
-     */
-    newName?: string;
+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 creating a pool.
+ * Options for starting a stopped sandbox.
  */
-export interface CreatePoolOptions {
-    /**
-     * Name of the template to use for sandboxes in this pool.
-     */
-    templateName: string;
-    /**
-     * Number of pre-warmed sandboxes to maintain (0-100).
-     */
-    replicas: number;
-    /**
-     * Timeout in seconds when waiting for pool to be ready. Default: 30.
-     */
+export interface StartSandboxOptions {
+    /** Timeout in seconds when waiting for ready. Default: 120. */
     timeout?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }
 /**
- * Options for updating a volume.
+ * Options for updating a sandbox (name and/or TTL).
  */
-export interface UpdateVolumeOptions {
+export interface UpdateSandboxOptions {
+    /** New display name. */
+    newName?: string;
     /**
-     * New display name (optional).
+     * Maximum lifetime in seconds from creation. Must be a multiple of 60.
+     * Pass `0` to disable absolute TTL.
      */
-    newName?: string;
+    ttlSeconds?: number;
     /**
-     * New storage size (must be >= current size). Optional.
+     * Idle timeout in seconds. Must be a multiple of 60. Pass `0` to disable.
+     * Omit (or pass `undefined`) to leave the existing value unchanged.
      */
-    size?: string;
+    idleTtlSeconds?: number;
 }
 /**
- * Options for updating a pool.
+ * Options for waiting for a sandbox to become ready.
  */
-export interface UpdatePoolOptions {
+export interface WaitForSandboxOptions {
     /**
-     * New display name (optional).
+     * Maximum time in seconds to wait for the sandbox to become ready.
+     * Default: 120.
      */
-    newName?: string;
+    timeout?: number;
     /**
-     * New number of replicas (0-100). Set to 0 to pause.
+     * Time in seconds between status polls.
+     * Default: 1.0.
      */
-    replicas?: number;
+    pollInterval?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
 }

package/dist/experimental/vercel/index.cjs

@@ -191,7 +191,7 @@ const _getGenerateTextWrapperConfig = ({ model, runName, aiSdkMethodName, resolv
                 return (0, utils_js_1.convertMessageToTracedFormat)({
                     content: content ?? outputs.outputs.text,
                     role: "assistant",
-                }, resolvedLsConfig?.traceResponseMetadata ?? traceResponseMetadata
+                }, (resolvedLsConfig?.traceResponseMetadata ?? traceResponseMetadata)
                     ? { steps }
                     : undefined);
             }

package/dist/experimental/vercel/index.js

@@ -187,7 +187,7 @@ const _getGenerateTextWrapperConfig = ({ model, runName, aiSdkMethodName, resolv
                 return convertMessageToTracedFormat({
                     content: content ?? outputs.outputs.text,
                     role: "assistant",
-                }, resolvedLsConfig?.traceResponseMetadata ?? traceResponseMetadata
+                }, (resolvedLsConfig?.traceResponseMetadata ?? traceResponseMetadata)
                     ? { steps }
                     : undefined);
             }

package/dist/experimental/vercel/middleware.cjs

@@ -280,7 +280,8 @@ function LangSmithMiddleware(config) {
                             }
                             let formattedOutputs;
                             if (lsConfig?.processOutputs) {
-                                formattedOutputs = await lsConfig.processOutputs(outputForTracing);
+                                formattedOutputs =
+                                    await lsConfig.processOutputs(outputForTracing);
                             }
                             else {
                                 formattedOutputs = _formatTracedOutputs(outputForTracing, lsConfig?.traceRawHttp);

package/dist/experimental/vercel/middleware.js

@@ -277,7 +277,8 @@ export function LangSmithMiddleware(config) {
                             }
                             let formattedOutputs;
                             if (lsConfig?.processOutputs) {
-                                formattedOutputs = await lsConfig.processOutputs(outputForTracing);
+                                formattedOutputs =
+                                    await lsConfig.processOutputs(outputForTracing);
                             }
                             else {
                                 formattedOutputs = _formatTracedOutputs(outputForTracing, lsConfig?.traceRawHttp);

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.6.0";

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.6.0";

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.6.0";