langsmith 0.10.4 → 0.10.6

package/dist/sandbox/sandbox.cjs

@@ -140,6 +140,26 @@ class Sandbox {
             writable: true,
             value: void 0
         });
+        /**
+         * User, working directory and environment this sandbox's commands run
+         * with. Absent on sandboxes created before the server recorded it.
+         */
+        Object.defineProperty(this, "run_config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * LangSmith access granted to code inside the sandbox, or undefined when it
+         * has none.
+         */
+        Object.defineProperty(this, "access_delegation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "_client", {
             enumerable: true,
             configurable: true,
@@ -160,6 +180,8 @@ class Sandbox {
         this.vCpus = data.vcpus;
         this.mem_bytes = data.mem_bytes;
         this.fs_capacity_bytes = data.fs_capacity_bytes;
+        this.run_config = data.run_config;
+        this.access_delegation = data.access_delegation;
         this._client = client;
     }
     /**
@@ -180,8 +202,10 @@ class Sandbox {
         return this.dataplane_url;
     }
     async run(command, options = {}) {
-        const { wait = true, onStdout, onStderr, idleTimeout, killOnDisconnect, ttlSeconds, pty, ...restOptions } = options;
+        const { wait = true, onStdout, onStderr, idleTimeout, killOnDisconnect, ttlSeconds, pty, closeInput, ...restOptions } = options;
         const hasCallbacks = onStdout !== undefined || onStderr !== undefined;
+        (0, helpers_js_1.assertRunConfigNotCombined)(restOptions);
+        const closeStdin = (0, helpers_js_1.resolveCloseInput)(closeInput, pty ?? false);
         if (!wait || hasCallbacks) {
             // WebSocket required for streaming / non-blocking
             const handle = await this._runWs(command, {
@@ -190,6 +214,7 @@ class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                closeInput: closeStdin,
                 onStdout,
                 onStderr,
             });
@@ -208,6 +233,7 @@ class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                closeInput: closeStdin,
             });
             return await handle.result;
         }
@@ -225,7 +251,7 @@ class Sandbox {
      * @internal
      */
     async _runWs(command, options = {}) {
-        const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout, killOnDisconnect, ttlSeconds, pty, } = options;
+        const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout, killOnDisconnect, ttlSeconds, pty, runConfig, closeInput: closeStdin = false, } = options;
         const dataplaneUrl = this.requireDataplaneUrl();
         const clientHeaders = this._client.getDefaultHeaders();
         // A client-supplied command_id makes execute idempotent: the daemon does
@@ -247,6 +273,8 @@ class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                runConfig,
+                closeStdin,
                 openTimeout: (0, ws_execute_js_1.openTimeoutFor)(deadline),
                 ...(Object.keys(clientHeaders).length > 0
                     ? { headers: clientHeaders }
@@ -255,6 +283,8 @@ class Sandbox {
             const handle = new command_handle_js_1.CommandHandle(stream, control, this, {
                 onStdout,
                 onStderr,
+                stdinClosed: closeStdin,
+                pty: pty ?? false,
             });
             try {
                 await handle._ensureStarted();
@@ -297,7 +327,7 @@ class Sandbox {
      * @internal
      */
     async _runHttp(command, options = {}) {
-        const { timeout = 60, env, cwd, shell = "/bin/bash" } = options;
+        const { timeout = 60, env, cwd, runConfig, shell = "/bin/bash" } = options;
         const dataplaneUrl = this.requireDataplaneUrl();
         const url = `${dataplaneUrl}/execute`;
         const payload = {
@@ -308,6 +338,9 @@ class Sandbox {
         if (env !== undefined) {
             payload.env = env;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         if (cwd !== undefined) {
             payload.cwd = cwd;
         }
@@ -339,7 +372,7 @@ class Sandbox {
      * @returns A new CommandHandle.
      */
     async reconnect(commandId, options = {}) {
-        const { stdoutOffset = 0, stderrOffset = 0 } = options;
+        const { stdoutOffset = 0, stderrOffset = 0, stdinClosed = false, pty = false, } = options;
         const dataplaneUrl = this.requireDataplaneUrl();
         const clientHeaders = this._client.getDefaultHeaders();
         const [stream, control] = await (0, ws_execute_js_1.reconnectWsStream)(dataplaneUrl, this._client.getApiKey(), commandId, {
@@ -353,6 +386,8 @@ class Sandbox {
             commandId,
             stdoutOffset,
             stderrOffset,
+            stdinClosed,
+            pty,
         });
     }
     /**
@@ -413,6 +448,127 @@ class Sandbox {
         const buffer = await response.arrayBuffer();
         return new Uint8Array(buffer);
     }
+    /**
+     * Report a file's size and validators without transferring it.
+     *
+     * @param path - File path to stat.
+     * @param timeout - Request timeout in seconds.
+     * @returns The size and the `ETag` to pass to {@link readRange}.
+     */
+    async stat(path, timeout = 60) {
+        const dataplaneUrl = this.requireDataplaneUrl();
+        const url = `${dataplaneUrl}/download?path=${encodeURIComponent(path)}`;
+        const response = await this._client._fetch(url, {
+            method: "HEAD",
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (!response.ok) {
+            await (0, helpers_js_1.handleFileHttpError)(response, path, this.name);
+        }
+        return (0, helpers_js_1.fileStatFromResponse)(response);
+    }
+    /**
+     * Read part of a file, for chunked reads and resumed downloads.
+     *
+     * @param path - File path to read.
+     * @param options - The byte range, plus optional `ifRange`/`ifNoneMatch`
+     *   validators. A 200 answer to a ranged request means the file changed and
+     *   the server sent it whole -- restart rather than append.
+     * @returns The bytes and where they sit in the file.
+     *
+     * @example
+     * ```typescript
+     * const head = await sandbox.readRange("/big.bin", { start: 0, end: 1023 });
+     * const next = await sandbox.readRange("/big.bin", {
+     *   start: head.end ?? 1024,
+     *   ifRange: head.etag,
+     * });
+     * ```
+     */
+    async readRange(path, options) {
+        const { ifRange, ifNoneMatch, timeout = 60, headers } = options;
+        const dataplaneUrl = this.requireDataplaneUrl();
+        const url = `${dataplaneUrl}/download?path=${encodeURIComponent(path)}`;
+        const requestHeaders = {
+            ...(headers ?? {}),
+            Range: (0, helpers_js_1.buildRangeHeader)(options),
+        };
+        if (ifRange)
+            requestHeaders["If-Range"] = ifRange;
+        if (ifNoneMatch)
+            requestHeaders["If-None-Match"] = ifNoneMatch;
+        const response = await this._client._fetch(url, {
+            method: "GET",
+            headers: requestHeaders,
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (!response.ok && response.status !== 304) {
+            await (0, helpers_js_1.handleFileHttpError)(response, path, this.name);
+        }
+        return (0, helpers_js_1.fileChunkFromResponse)(response);
+    }
+    /**
+     * Find files and directories matching a pattern.
+     *
+     * @param pattern - Match against each entry's path relative to `path`.
+     *   Supports `**` for any number of segments plus `*`, `?` and `[...]`
+     *   within one segment.
+     * @param path - Absolute path of the directory to search under.
+     * @param options - Result cap and request options.
+     * @returns The matches; check `truncated` before treating them as complete.
+     */
+    async glob(pattern, path, options = {}) {
+        const body = { pattern, path };
+        if (options.limit !== undefined)
+            body.limit = options.limit;
+        return (await this._fileSearch("glob", body, options));
+    }
+    /**
+     * List a directory's immediate entries, without recursing.
+     *
+     * A convenience over {@link glob} with the pattern `*`.
+     *
+     * @param path - Absolute path of the directory to list.
+     * @param options - Result cap and request options.
+     * @returns The directory's files and subdirectories.
+     */
+    async ls(path, options = {}) {
+        return this.glob("*", path, options);
+    }
+    /**
+     * Search file contents for a literal string.
+     *
+     * @param pattern - Literal text to search for. Not a regular expression.
+     * @param path - Absolute path of the directory to search under.
+     * @param options - Optional `glob` file filter, result cap, request options.
+     * @returns The matching lines; check `truncated` for completeness.
+     */
+    async grep(pattern, path, options = {}) {
+        const body = { pattern, path };
+        if (options.glob !== undefined)
+            body.glob = options.glob;
+        if (options.limit !== undefined)
+            body.limit = options.limit;
+        return (await this._fileSearch("grep", body, options));
+    }
+    /**
+     * POST one of the read-only filesystem search endpoints.
+     * @internal
+     */
+    async _fileSearch(operation, body, options) {
+        const { timeout = 60, headers } = options;
+        const dataplaneUrl = this.requireDataplaneUrl();
+        const response = await this._client._fetch(`${dataplaneUrl}/${operation}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...(headers ?? {}) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (!response.ok) {
+            await (0, helpers_js_1.handleFileHttpError)(response, String(body.path), this.name);
+        }
+        return response.json();
+    }
     /**
      * Create a link that downloads one file from this sandbox.
      *

package/dist/sandbox/sandbox.d.ts

@@ -1,7 +1,8 @@
 /**
  * Sandbox class for interacting with a specific sandbox instance.
  */
-import type { CaptureSnapshotOptions, DownloadURL, ExecutionResult, GenerateDownloadURLOptions, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
+import type { AccessDelegation } from "./access_delegation.js";
+import type { CaptureSnapshotOptions, DownloadURL, ExecutionResult, FileChunk, FileStat, GenerateDownloadURLOptions, GlobOptions, GlobResult, GrepOptions, GrepResult, ReadRangeOptions, RunConfig, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
 import { CommandHandle } from "./command_handle.js";
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -62,6 +63,16 @@ export declare class Sandbox {
     readonly mem_bytes?: number;
     /** Root filesystem capacity in bytes. */
     readonly fs_capacity_bytes?: number;
+    /**
+     * User, working directory and environment this sandbox's commands run
+     * with. Absent on sandboxes created before the server recorded it.
+     */
+    readonly run_config?: RunConfig;
+    /**
+     * LangSmith access granted to code inside the sandbox, or undefined when it
+     * has none.
+     */
+    readonly access_delegation?: AccessDelegation;
     private _client;
     /**
      * Return the dataplane URL.
@@ -126,6 +137,8 @@ export declare class Sandbox {
     reconnect(commandId: string, options?: {
         stdoutOffset?: number;
         stderrOffset?: number;
+        stdinClosed?: boolean;
+        pty?: boolean;
     }): Promise<CommandHandle>;
     /**
      * Write content to a file in the sandbox.
@@ -155,6 +168,63 @@ export declare class Sandbox {
      * ```
      */
     read(path: string, timeout?: number): Promise<Uint8Array>;
+    /**
+     * Report a file's size and validators without transferring it.
+     *
+     * @param path - File path to stat.
+     * @param timeout - Request timeout in seconds.
+     * @returns The size and the `ETag` to pass to {@link readRange}.
+     */
+    stat(path: string, timeout?: number): Promise<FileStat>;
+    /**
+     * Read part of a file, for chunked reads and resumed downloads.
+     *
+     * @param path - File path to read.
+     * @param options - The byte range, plus optional `ifRange`/`ifNoneMatch`
+     *   validators. A 200 answer to a ranged request means the file changed and
+     *   the server sent it whole -- restart rather than append.
+     * @returns The bytes and where they sit in the file.
+     *
+     * @example
+     * ```typescript
+     * const head = await sandbox.readRange("/big.bin", { start: 0, end: 1023 });
+     * const next = await sandbox.readRange("/big.bin", {
+     *   start: head.end ?? 1024,
+     *   ifRange: head.etag,
+     * });
+     * ```
+     */
+    readRange(path: string, options: ReadRangeOptions): Promise<FileChunk>;
+    /**
+     * Find files and directories matching a pattern.
+     *
+     * @param pattern - Match against each entry's path relative to `path`.
+     *   Supports `**` for any number of segments plus `*`, `?` and `[...]`
+     *   within one segment.
+     * @param path - Absolute path of the directory to search under.
+     * @param options - Result cap and request options.
+     * @returns The matches; check `truncated` before treating them as complete.
+     */
+    glob(pattern: string, path: string, options?: GlobOptions): Promise<GlobResult>;
+    /**
+     * List a directory's immediate entries, without recursing.
+     *
+     * A convenience over {@link glob} with the pattern `*`.
+     *
+     * @param path - Absolute path of the directory to list.
+     * @param options - Result cap and request options.
+     * @returns The directory's files and subdirectories.
+     */
+    ls(path: string, options?: GlobOptions): Promise<GlobResult>;
+    /**
+     * Search file contents for a literal string.
+     *
+     * @param pattern - Literal text to search for. Not a regular expression.
+     * @param path - Absolute path of the directory to search under.
+     * @param options - Optional `glob` file filter, result cap, request options.
+     * @returns The matching lines; check `truncated` for completeness.
+     */
+    grep(pattern: string, path: string, options?: GrepOptions): Promise<GrepResult>;
     /**
      * Create a link that downloads one file from this sandbox.
      *

package/dist/sandbox/sandbox.js

@@ -3,7 +3,7 @@
  */
 import { uuid7 } from "../uuid.js";
 import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxRetryableConnectionError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
-import { handleSandboxHttpError } from "./helpers.js";
+import { assertRunConfigNotCombined, buildRangeHeader, fileChunkFromResponse, fileStatFromResponse, handleFileHttpError, handleSandboxHttpError, resolveCloseInput, } from "./helpers.js";
 import { CommandHandle } from "./command_handle.js";
 import { connectDeadline, isWsAvailable, openTimeoutFor, reconnectWsStream, remainingBudget, runWsStream, } from "./ws_execute.js";
 /**
@@ -137,6 +137,26 @@ export class Sandbox {
             writable: true,
             value: void 0
         });
+        /**
+         * User, working directory and environment this sandbox's commands run
+         * with. Absent on sandboxes created before the server recorded it.
+         */
+        Object.defineProperty(this, "run_config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * LangSmith access granted to code inside the sandbox, or undefined when it
+         * has none.
+         */
+        Object.defineProperty(this, "access_delegation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "_client", {
             enumerable: true,
             configurable: true,
@@ -157,6 +177,8 @@ export class Sandbox {
         this.vCpus = data.vcpus;
         this.mem_bytes = data.mem_bytes;
         this.fs_capacity_bytes = data.fs_capacity_bytes;
+        this.run_config = data.run_config;
+        this.access_delegation = data.access_delegation;
         this._client = client;
     }
     /**
@@ -177,8 +199,10 @@ export class Sandbox {
         return this.dataplane_url;
     }
     async run(command, options = {}) {
-        const { wait = true, onStdout, onStderr, idleTimeout, killOnDisconnect, ttlSeconds, pty, ...restOptions } = options;
+        const { wait = true, onStdout, onStderr, idleTimeout, killOnDisconnect, ttlSeconds, pty, closeInput, ...restOptions } = options;
         const hasCallbacks = onStdout !== undefined || onStderr !== undefined;
+        assertRunConfigNotCombined(restOptions);
+        const closeStdin = resolveCloseInput(closeInput, pty ?? false);
         if (!wait || hasCallbacks) {
             // WebSocket required for streaming / non-blocking
             const handle = await this._runWs(command, {
@@ -187,6 +211,7 @@ export class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                closeInput: closeStdin,
                 onStdout,
                 onStderr,
             });
@@ -205,6 +230,7 @@ export class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                closeInput: closeStdin,
             });
             return await handle.result;
         }
@@ -222,7 +248,7 @@ export class Sandbox {
      * @internal
      */
     async _runWs(command, options = {}) {
-        const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout, killOnDisconnect, ttlSeconds, pty, } = options;
+        const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout, killOnDisconnect, ttlSeconds, pty, runConfig, closeInput: closeStdin = false, } = options;
         const dataplaneUrl = this.requireDataplaneUrl();
         const clientHeaders = this._client.getDefaultHeaders();
         // A client-supplied command_id makes execute idempotent: the daemon does
@@ -244,6 +270,8 @@ export class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                runConfig,
+                closeStdin,
                 openTimeout: openTimeoutFor(deadline),
                 ...(Object.keys(clientHeaders).length > 0
                     ? { headers: clientHeaders }
@@ -252,6 +280,8 @@ export class Sandbox {
             const handle = new CommandHandle(stream, control, this, {
                 onStdout,
                 onStderr,
+                stdinClosed: closeStdin,
+                pty: pty ?? false,
             });
             try {
                 await handle._ensureStarted();
@@ -294,7 +324,7 @@ export class Sandbox {
      * @internal
      */
     async _runHttp(command, options = {}) {
-        const { timeout = 60, env, cwd, shell = "/bin/bash" } = options;
+        const { timeout = 60, env, cwd, runConfig, shell = "/bin/bash" } = options;
         const dataplaneUrl = this.requireDataplaneUrl();
         const url = `${dataplaneUrl}/execute`;
         const payload = {
@@ -305,6 +335,9 @@ export class Sandbox {
         if (env !== undefined) {
             payload.env = env;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         if (cwd !== undefined) {
             payload.cwd = cwd;
         }
@@ -336,7 +369,7 @@ export class Sandbox {
      * @returns A new CommandHandle.
      */
     async reconnect(commandId, options = {}) {
-        const { stdoutOffset = 0, stderrOffset = 0 } = options;
+        const { stdoutOffset = 0, stderrOffset = 0, stdinClosed = false, pty = false, } = options;
         const dataplaneUrl = this.requireDataplaneUrl();
         const clientHeaders = this._client.getDefaultHeaders();
         const [stream, control] = await reconnectWsStream(dataplaneUrl, this._client.getApiKey(), commandId, {
@@ -350,6 +383,8 @@ export class Sandbox {
             commandId,
             stdoutOffset,
             stderrOffset,
+            stdinClosed,
+            pty,
         });
     }
     /**
@@ -410,6 +445,127 @@ export class Sandbox {
         const buffer = await response.arrayBuffer();
         return new Uint8Array(buffer);
     }
+    /**
+     * Report a file's size and validators without transferring it.
+     *
+     * @param path - File path to stat.
+     * @param timeout - Request timeout in seconds.
+     * @returns The size and the `ETag` to pass to {@link readRange}.
+     */
+    async stat(path, timeout = 60) {
+        const dataplaneUrl = this.requireDataplaneUrl();
+        const url = `${dataplaneUrl}/download?path=${encodeURIComponent(path)}`;
+        const response = await this._client._fetch(url, {
+            method: "HEAD",
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (!response.ok) {
+            await handleFileHttpError(response, path, this.name);
+        }
+        return fileStatFromResponse(response);
+    }
+    /**
+     * Read part of a file, for chunked reads and resumed downloads.
+     *
+     * @param path - File path to read.
+     * @param options - The byte range, plus optional `ifRange`/`ifNoneMatch`
+     *   validators. A 200 answer to a ranged request means the file changed and
+     *   the server sent it whole -- restart rather than append.
+     * @returns The bytes and where they sit in the file.
+     *
+     * @example
+     * ```typescript
+     * const head = await sandbox.readRange("/big.bin", { start: 0, end: 1023 });
+     * const next = await sandbox.readRange("/big.bin", {
+     *   start: head.end ?? 1024,
+     *   ifRange: head.etag,
+     * });
+     * ```
+     */
+    async readRange(path, options) {
+        const { ifRange, ifNoneMatch, timeout = 60, headers } = options;
+        const dataplaneUrl = this.requireDataplaneUrl();
+        const url = `${dataplaneUrl}/download?path=${encodeURIComponent(path)}`;
+        const requestHeaders = {
+            ...(headers ?? {}),
+            Range: buildRangeHeader(options),
+        };
+        if (ifRange)
+            requestHeaders["If-Range"] = ifRange;
+        if (ifNoneMatch)
+            requestHeaders["If-None-Match"] = ifNoneMatch;
+        const response = await this._client._fetch(url, {
+            method: "GET",
+            headers: requestHeaders,
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (!response.ok && response.status !== 304) {
+            await handleFileHttpError(response, path, this.name);
+        }
+        return fileChunkFromResponse(response);
+    }
+    /**
+     * Find files and directories matching a pattern.
+     *
+     * @param pattern - Match against each entry's path relative to `path`.
+     *   Supports `**` for any number of segments plus `*`, `?` and `[...]`
+     *   within one segment.
+     * @param path - Absolute path of the directory to search under.
+     * @param options - Result cap and request options.
+     * @returns The matches; check `truncated` before treating them as complete.
+     */
+    async glob(pattern, path, options = {}) {
+        const body = { pattern, path };
+        if (options.limit !== undefined)
+            body.limit = options.limit;
+        return (await this._fileSearch("glob", body, options));
+    }
+    /**
+     * List a directory's immediate entries, without recursing.
+     *
+     * A convenience over {@link glob} with the pattern `*`.
+     *
+     * @param path - Absolute path of the directory to list.
+     * @param options - Result cap and request options.
+     * @returns The directory's files and subdirectories.
+     */
+    async ls(path, options = {}) {
+        return this.glob("*", path, options);
+    }
+    /**
+     * Search file contents for a literal string.
+     *
+     * @param pattern - Literal text to search for. Not a regular expression.
+     * @param path - Absolute path of the directory to search under.
+     * @param options - Optional `glob` file filter, result cap, request options.
+     * @returns The matching lines; check `truncated` for completeness.
+     */
+    async grep(pattern, path, options = {}) {
+        const body = { pattern, path };
+        if (options.glob !== undefined)
+            body.glob = options.glob;
+        if (options.limit !== undefined)
+            body.limit = options.limit;
+        return (await this._fileSearch("grep", body, options));
+    }
+    /**
+     * POST one of the read-only filesystem search endpoints.
+     * @internal
+     */
+    async _fileSearch(operation, body, options) {
+        const { timeout = 60, headers } = options;
+        const dataplaneUrl = this.requireDataplaneUrl();
+        const response = await this._client._fetch(`${dataplaneUrl}/${operation}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...(headers ?? {}) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (!response.ok) {
+            await handleFileHttpError(response, String(body.path), this.name);
+        }
+        return response.json();
+    }
     /**
      * Create a link that downloads one file from this sandbox.
      *