langsmith 0.5.18 → 0.5.20

package/dist/client.cjs

@@ -679,6 +679,24 @@ class Client {
         }
         return outputs;
     }
+    /**
+     * Filter content from new_token events to prevent streaming LLM output
+     * from being uploaded via events.
+     */
+    _filterNewTokenEvents(events) {
+        if (!events || events.length === 0) {
+            return events;
+        }
+        return events.map((event) => {
+            if (event.name === "new_token") {
+                // Remove the kwargs containing the token data
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { kwargs: _, ...rest } = event;
+                return rest;
+            }
+            return event;
+        });
+    }
     async prepareRunCreateOrUpdateInputs(run) {
         const runParams = { ...run };
         if (runParams.inputs !== undefined) {
@@ -687,6 +705,9 @@ class Client {
         if (runParams.outputs !== undefined) {
             runParams.outputs = await this.processOutputs(runParams.outputs);
         }
+        if (runParams.events !== undefined) {
+            runParams.events = this._filterNewTokenEvents(runParams.events);
+        }
         return runParams;
     }
     async _getResponse(path, queryParams) {
@@ -1531,6 +1552,9 @@ class Client {
         if (run.outputs) {
             run.outputs = await this.processOutputs(run.outputs);
         }
+        if (run.events) {
+            run.events = this._filterNewTokenEvents(run.events);
+        }
         // TODO: Untangle types
         const data = { ...run, id: runId };
         if (!this._filterForSampling([data], true).length) {

package/dist/client.d.ts

@@ -445,6 +445,11 @@ export declare class Client implements LangSmithTracingClientInterface {
     private _getPlatformEndpointPath;
     private processInputs;
     private processOutputs;
+    /**
+     * Filter content from new_token events to prevent streaming LLM output
+     * from being uploaded via events.
+     */
+    private _filterNewTokenEvents;
     private prepareRunCreateOrUpdateInputs;
     private _getResponse;
     private _get;

package/dist/client.js

@@ -641,6 +641,24 @@ export class Client {
         }
         return outputs;
     }
+    /**
+     * Filter content from new_token events to prevent streaming LLM output
+     * from being uploaded via events.
+     */
+    _filterNewTokenEvents(events) {
+        if (!events || events.length === 0) {
+            return events;
+        }
+        return events.map((event) => {
+            if (event.name === "new_token") {
+                // Remove the kwargs containing the token data
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { kwargs: _, ...rest } = event;
+                return rest;
+            }
+            return event;
+        });
+    }
     async prepareRunCreateOrUpdateInputs(run) {
         const runParams = { ...run };
         if (runParams.inputs !== undefined) {
@@ -649,6 +667,9 @@ export class Client {
         if (runParams.outputs !== undefined) {
             runParams.outputs = await this.processOutputs(runParams.outputs);
         }
+        if (runParams.events !== undefined) {
+            runParams.events = this._filterNewTokenEvents(runParams.events);
+        }
         return runParams;
     }
     async _getResponse(path, queryParams) {
@@ -1493,6 +1514,9 @@ export class Client {
         if (run.outputs) {
             run.outputs = await this.processOutputs(run.outputs);
         }
+        if (run.events) {
+            run.events = this._filterNewTokenEvents(run.events);
+        }
         // TODO: Untangle types
         const data = { ...run, id: runId };
         if (!this._filterForSampling([data], true).length) {

package/dist/experimental/anthropic/context.cjs

@@ -133,6 +133,11 @@ class StreamManager {
                             run_type: "chain",
                             inputs: block.input,
                             start_time: eventTime,
+                            extra: {
+                                metadata: {
+                                    ls_agent_type: "subagent",
+                                },
+                            },
                         }) ?? this.tools[block.id];
                     this.namespaces[block.id] ??= this.tools[block.id];
                 }

package/dist/experimental/anthropic/context.js

@@ -130,6 +130,11 @@ export class StreamManager {
                             run_type: "chain",
                             inputs: block.input,
                             start_time: eventTime,
+                            extra: {
+                                metadata: {
+                                    ls_agent_type: "subagent",
+                                },
+                            },
                         }) ?? this.tools[block.id];
                     this.namespaces[block.id] ??= this.tools[block.id];
                 }

package/dist/experimental/anthropic/index.cjs

@@ -112,6 +112,7 @@ function wrapClaudeAgentQuery(queryFn, defaultThis, baseConfig) {
         ...baseConfig,
         metadata: {
             ls_integration: "claude-agent-sdk-js",
+            ls_agent_type: "root",
             ...baseConfig?.metadata,
         },
         __deferredSerializableArgOptions: { maxDepth: 1 },

package/dist/experimental/anthropic/index.js

@@ -109,6 +109,7 @@ function wrapClaudeAgentQuery(queryFn, defaultThis, baseConfig) {
         ...baseConfig,
         metadata: {
             ls_integration: "claude-agent-sdk-js",
+            ls_agent_type: "root",
             ...baseConfig?.metadata,
         },
         __deferredSerializableArgOptions: { maxDepth: 1 },

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.
  *
@@ -53,6 +74,8 @@ function getDefaultApiKey() {
  *   await sandbox.delete();
  * }
  * ```
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 class SandboxClient {
     constructor(config = {}) {
@@ -113,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
     // =========================================================================
@@ -538,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;
         }
@@ -558,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",
@@ -580,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");
@@ -677,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");
@@ -709,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.
@@ -30,6 +30,8 @@ import { Sandbox } from "./sandbox.js";
  *   await sandbox.delete();
  * }
  * ```
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 export declare class SandboxClient {
     private _baseUrl;
@@ -204,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.
      *
@@ -214,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.
      *
@@ -256,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.
      *
@@ -278,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>;
 }